2718lab-devkit

[简体中文](README.zh-CN.md) # 2718lab DevKit — Codex + MCP v1.2.1 [](./.codex-plugin/plugin.json) [](LICENSE) 2718lab DevKit is a Codex-first engineering toolkit: a local, stdio-only MCP runtime for bounded project indexing, Atlas evidence, Relay lifecycle coordination, and deterministic Fast Lane planning, plus a compact Skill bundle of reference manuals. This repository carries the versioned v1.2.1 package. The checked-in manifest and allowlist define the executable runtime surface; the manual map, install, build, and verification sections below describe the supported workflow. The public Python compiler and CLI retain the deliberately fail-closed `team-efficiency/fast-lane-plan-v1` preview. For new work, prepare `fast-lane-request-v2` with `prepare_model_neutral_fast_lane_request`; MCP `fastlane_compile` then resolves the workspace/snapshot selectors through its local RuntimeRoot and returns a verified `team-efficiency/fast-lane-plan-v3`. Its assignments describe requirements and leave model selection to the coordinator using current Codex tool metadata. Every descriptor remains `plan_only`: it never dispatches, claims a lease, creates a worktree, or authorizes execution. Request-v1/plan-v2 stays available for exact legacy replay. The prior v1.1.3 storage-governance integration references compatible Host source only on Ayleovelle's user-fork [`codex/host-1.1.3-storage-governance-upstream`](https://github.com/Ayleovelle/codex/tree/codex/host-1.1.3-storage-governance-upstream) branch, pinned to immutable commit [`c3dde23bec21c45d10740f2eec09d9a1b87cd329`](https://github.com/Ayleovelle/codex/commit/c3dde23bec21c45d10740f2eec09d9a1b87cd329). That fork is buildable Host source, not an OpenAI upstream merge or a component shipped by this package. Stock Codex Hosts have no attested protected broker and continue to fail closed. > [!IMPORTANT] > **Workflow reminder:** route from bounded evidence. Parallel A1/A2/A3 work is > allowed only with disjoint, exclusively owned write scopes and independent G: > task roots. Claim and bind before execution; prewarm is read-only and > `action="retain"` is not a new spawn. The coordinator integrates only after > PR-style independent review, then accepts before archiving. Fast Lane does not > use an account-usage coordinator or account-usage inputs. Do not commit runtime state or > credentials. > **Scheduler topology V1:** `2718lab-devkit/scheduler-topology-v1` binds the > plan, lease, and G-drive worktree as auditable opaque identities. A/B/C means > main-conversation review/integration, scheduler, and writer; each scheduler > has at most a 1:3 writer relationship. Design/prewarm are read-only and stay > subject to actual host slots, host capability, and safety gates. Cross-scope > work requires a declared-child split that strictly reduces conflict, or is > UNSPLITTABLE. ## 1.2.1 hotfix The compatibility preflight now rejects any missing or extra retained Codex manifest field, including unreviewed hooks, agents and skill entry points. It remains read-only and does not authorize execution. ## What is new in 1.2.0 Portable Agent Plugins entry points now accompany the retained Codex manifests. Run the read-only package preflight before installing an extracted artifact: python .codex-plugin/check_compatibility.py --plugin-root <extracted-plugin> The JSON report checks package consistency, not host permissions or model availability. See [the September 2026 compatibility guide](docs/compatibility/codex-2026-09.md) for current plugin packaging, dynamic model selection and actual host boundaries. The 17-tool runtime and fail-closed execution contracts remain intact. ## What is shipped - Project Index exposes opaque workspace registration, bounded snapshots, status, and graph queries. - Checkpoint services create, inspect, and restore evidence-bound snapshots. - Atlas provides bounded graph queries, packet preparation, inert rendering, and durable acceptance projection. - Relay validates explicit work packages and exposes lifecycle state. Python returns structured host actions; the Codex host remains responsible for worktree bootstrap and agent dispatch. - The executable MCP runtime exposes exactly 17 tools, no MCP prompts, no MCP resources, no static prompt agents, and no model runner. - The optional Codex Skill bundle is part of DevKit's documentation surface. It provides short, module-specific manuals without becoming a second runtime or an executable prompt/agent surface. - Fast Lane is a pure planning compiler. New model-neutral requests emit bounded `team-efficiency/fast-lane-plan-v3` assignments only after its private RuntimeRoot verifies a registered `INDEX_READY` snapshot, Git HEAD, and full write-scope coverage. Assignments contain no default model name; the coordinator records an exact model/effort choice before the dispatch tool validates availability. Every result remains `plan_only`; no agent, Git command, lease, or worktree action is executed. The public Python compiler/CLI remains the authority-inert plan-v1 diagnostic surface. ## Module overview | Module | Responsibility | Start here | | --- | --- | --- | | [`mcp-tools/server.py`](mcp-tools/server.py) | stdio MCP entry point and the public 17-tool surface | [MCP surface](#exact-mcp-surface) | | [`mcp-tools/project_index/`](mcp-tools/project_index/) | workspace registration, bounded snapshots, status, and graph queries | [Project Index tools](#exact-mcp-surface) | | [`mcp-tools/devkit_atlas/`](mcp-tools/devkit_atlas/) | evidence graph queries, implementation packets, rendering, and acceptance projection | [Atlas tools](#exact-mcp-surface) | | [`mcp-tools/devkit_relay/`](mcp-tools/devkit_relay/) | explicit work-package compilation and lifecycle host actions | [Relay tools](#exact-mcp-surface) | | [`mcp-tools/devkit_runtime/`](mcp-tools/devkit_runtime/) | runtime paths, checkpoints, durable boundaries, and the private host bridge | [runtime and recovery](#runtime-data-and-recovery) | | [`mcp-tools/orchestrator/`](mcp-tools/orchestrator/) | durable workflow, task, lease, and lifecycle state | [workflow lifecycle](mcp-tools/devkit_fastlane/references/efficiency-automation.md#workflow-lifecycle-plan) | | [`mcp-tools/devkit_fastlane/`](mcp-tools/devkit_fastlane/) | deterministic routing/Fast Lane compiler, contracts, and tests | [Fast Lane contract](mcp-tools/devkit_fastlane/FASTLANE_CONTRACT.md) | | [`.codex-plugin/`](.codex-plugin/) | plugin manifest, artifact allowlist, and reproducible package builder | [artifact build](#build-the-primary-artifact) | ## Overall workflow The repository workflow defaults to Fast Lane. `workflow-design` prepares a bounded model-neutral request-v2 input. MCP `fastlane_compile` verifies the persisted local project snapshot and returns a plan-v3 descriptor; `team_efficiency.py` retains the blocked plan-v1 diagnostic path. Neither path starts agents or creates/executes cross-session worktrees. A coordinator must separately validate route availability, claim a lease, and dispatch any selected work. ```mermaid flowchart TD A["Install + configure .mcp.json"] --> B{"Choose entry"} subgraph MCP["MCP runtime"] C["mcp-tools/server.py<br/>stdio entry"] --> D["Project Index / Checkpoint<br/>Atlas / Relay"] --> E["Bounded result<br/>host action"] end subgraph FAST["Fast Lane"] F["fast-lane request"] --> G["MCP fastlane_compile<br/>private RuntimeRoot verification"] G --> X["plan-v3 requirements<br/>unselected, plan_only"] F --> H["public Python / CLI"] --> I["plan-v1<br/>NO_SAFE_WORK"] end B -->|MCP tools| C B -->|Fast Lane| F ``` ## Codex manual map DevKit deliberately has two separate surfaces: the MCP runtime performs bounded tool work, while the local plugin includes an optional, documentation-only Codex manual bundle. The bundle has one short navigator (`skills/devkit-overview`), one workflow-design manual (`skills/workflow-design`, default Fast Lane policy), and six separate module manuals. A task loads only the manual it needs: `fast-lane-routing` · `bugkiller` · `code-atlas` · `mcp-server-dev` · `oss-repo-ops` · `python-engineering`. These skills are reference manuals, not MCP tools or executable prompt surfaces. They contain no slash commands, agent profiles, starter templates, validators, or dispatch code. The lean runtime ZIP deliberately excludes them, but that packaging boundary does not make DevKit a runtime-only product. ## Documentation map Use this page as the entry point, then follow the contract links instead of re-reading the whole repository: - [Fast Lane contract](mcp-tools/devkit_fastlane/FASTLANE_CONTRACT.md) - [Efficiency automation reference and CLI details](mcp-tools/devkit_fastlane/references/efficiency-automation.md) - [Verification checklist](mcp-tools/devkit_fastlane/references/verification-checklist.md) - [Work-package and task-card rules](mcp-tools/devkit_fastlane/references/work-packages.md) - [Orchestration runtime contract](mcp-tools/devkit_fastlane/references/orchestration-runtime.md) - [Team and lane patterns](mcp-tools/devkit_fastlane/references/team-patterns.md) - [Repository automation and review](docs/governance/repository-automation.md) - [Contributing](CONTRIBUTING.md) · [Security reporting](SECURITY.md) · [Code of Conduct](CODE_OF_CONDUCT.md) - [Historical design records](docs/superpowers/README.md) — context only; they can mention retired components and are not the current implementation contract. - [Release history](CHANGELOG.md) For the current implementation entry point, see [the Fast Lane compiler](mcp-tools/devkit_fastlane/scripts/team_efficiency.py). Fast Lane has no account-usage coordinator contract; the public compiler and CLI do not read, coordinate, or infer account usage. ## Exact MCP surface The public server name is 2718lab-devkit. Every result uses the bounded 2718lab-devkit/tool-result-v1 envelope. The public surface is exactly: | Area | Tools | | --- | --- | | Project Index | project_index_register, project_index_sync, project_index_status, project_index_query | | Checkpoints | worktree_checkpoint_create, worktree_checkpoint_status, worktree_checkpoint_restore | | Atlas | atlas_query, atlas_prepare, atlas_render, atlas_accept | | Relay | relay_compile, relay_start, relay_status, relay_handoff, relay_integrate | | Fast Lane | fastlane_compile | The server has no prompt or resource surface. Tool inputs are structured and bounded; absolute worker paths, shell fragments, raw source, credentials, unbounded command output, and caller-forged acceptance evidence are rejected. ## Install from the Codex marketplace Add the repository's slim marketplace branch once, then install the plugin: codex plugin marketplace add 2718labs/2718lab-devkit --ref marketplace codex plugin add 2718lab-devkit@2718lab-marketplace For later releases, refresh the remote snapshot and reinstall from it: codex plugin marketplace upgrade 2718lab-marketplace codex plugin add 2718lab-devkit@2718lab-marketplace Start a new Codex task after installing or updating so the refreshed skills and MCP server are loaded. The `marketplace` branch is a distribution snapshot; the source of record remains `main` and immutable release tags. Maintainers build that snapshot with the dedicated marketplace allowlist: python .codex-plugin/build_main_artifact.py --plugin-root . --allowlist .codex-plugin/marketplace-artifact-allowlist.json --output <artifact-output-dir>/2718lab-devkit-marketplace-v1.2.1.zip ## Install and run locally Requirements: Python 3.11 or newer and uv. From the repository root: cd mcp-tools uv sync --locked --no-dev uv run --locked --no-dev python server.py The canonical host configuration is .mcp.json. It runs the locked command above with mcp-tools as the working directory. The configuration forwards two private host-bridge selector names and optional project/thread scope identifiers: - CODEX_DEVKIT_HOST_BRIDGE_FD - CODEX_DEVKIT_HOST_BRIDGE_HANDLE - CODEX_PROJECT_ROOT, CODEX_WORKSPACE_ROOT - CODEX_PROJECT_ID, CODEX_WORKSPACE_ID, CODEX_THREAD_ID These are selector or identity names, not values to invent or copy into a task message. The latter identifiers keep durable state scoped to one project or thread instead of leaking it into another workspace. On Windows, CODEX_DEVKIT_HOST_BRIDGE_HANDLE is intentionally named for compatibility but accepts only `pipe:codex-devkit-<launcher-pid>-<creation-filetime>-<high-entropy-token>` (a launcher PID, its 16-hex Windows creation FILETIME, and a launcher-generated 128-bit lowercase hex token). The runtime maps that opaque selector only into the local `\\.\pipe\` namespace, verifies that the connected pipe server has exactly the encoded launcher PID and process creation time before sending the session key, and rejects inherited numeric handles, paths, remote UNC names, and untagged values. The launcher remains responsible for CSPRNG generation, first-instance creation, remote-client rejection, and an owner-only ACL. Unix continues to accept only a numeric inherited descriptor through CODEX_DEVKIT_HOST_BRIDGE_FD. Relay lifecycle mutations that need the private host capability broker or proof registry fail closed when the host does not provide an attested capability, using RELAY_CAPABILITY_BROKER_UNAVAILABLE. The server never exposes raw handles or falls back to an unrelated local start. ## Build the primary artifact The allowlisted builder creates a deterministic ZIP outside the plugin source tree. Choose an output directory outside the source tree: python .codex-plugin/build_main_artifact.py --plugin-root . --output <artifact-output-dir>/2718lab-devkit-v1.2.1.zip The artifact contains the manifest, .mcp.json, LICENSE, the locked Python project, and the runtime files selected by .codex-plugin/main-artifact-allowlist.json. Its executable runtime surface is the MCP server. The ZIP also carries the Fast Lane contract, required references and policy assets, the `team_efficiency.py` compatibility entry point, its routing modules, and the exact `fast-lane-routing`, `code-atlas`, and `workflow-design` Skill directories whose `agents/openai.yaml` files require that MCP server. The builder only supports file and directory allowlist roots, so those three directories are named individually and archive tests reject any other Skill directory. Command helpers, hooks, CI files, host-private state, prompts, top-level static agents, and arbitrary repository files remain excluded. Run Fast Lane through its executable entry point to inspect its fail-closed result: python mcp-tools/devkit_fastlane/scripts/team_efficiency.py fast-lane --input <fast-lane-request.json> --reasoning-effort ultra Legacy host-only switches remain parse-compatible only. The current public CLI does not read or consume them and cannot activate work. It has no account-usage coordinator or cache contract. `CODEX_FASTLANE_TASK_ROOT` and worktree/cache placement are likewise reserved for a future host-owned execution bridge. The current public compiler neither creates nor executes a worktree and must not be used as evidence that a worktree configuration has been accepted. ## Runtime data and recovery Persistent data is local. RuntimeConfig resolves the data root in this order: 1. `CODEX_DEVKIT_DATA_ROOT`, when the host explicitly provides an absolute directory for this installation. 2. PLUGIN_DATA, when the host explicitly provides an absolute directory. 3. CODEX_HOME/data/2718lab-devkit. 4. The default Codex data directory: %USERPROFILE%\.codex\data\2718lab-devkit. For a portable local installation, set `CODEX_DEVKIT_DATA_ROOT` to a durable G: path (for example `G:\CodexData\.codex\data\2718lab-devkit`). This override is intentionally separate from the legacy `PLUGIN_DATA` root so an older checkout cannot open the stable runtime's database by accident. When the host provides CODEX_PROJECT_ROOT or CODEX_WORKSPACE_ROOT, the durable root is further scoped below `scoped-v1` by a SHA-256 identity of that project root. If a project root is unavailable, CODEX_PROJECT_ID, CODEX_WORKSPACE_ID, or CODEX_THREAD_ID provides a non-path fallback scope. The raw project path or identity is never written into the scope directory name. This prevents a long-lived plugin process from projecting one project's workflows, indexes, or receipts into another project. A command-line invocation with no scope keeps the unsuffixed root for backwards compatibility; the host integration should always provide a project or thread scope. For local DevKit work, set CODEX_TASK_TEMP and its TMPDIR/TEMP/TMP/ PYTHONPYCACHEPREFIX children under an isolated G: task root. A configured scratch base receives the same scope suffix as durable data. The runtime rejects unsafe, overlapping, missing, or reparse-point roots and does not write fallback state into the repository. Hosted Windows CI is the explicit exception: its workflow must require RUNNER_TEMP and derive CODEX_TASK_TEMP plus all task-local temporary/cache children below it. That host-provided exception does not prove an external host embedding. After a host interruption, resume from the durable workflow lease, endpoint, artifact references, snapshots, and bounded receipts. Rebind a valid current context before continuing. Do not reconstruct authority from chat history, raw logs, or an unrelated new start. Archive a completed independent task only after evidence, commit, integration, and acceptance have all succeeded. ### Retention and cleanup boundary Retention is an explicit host policy, not an inference from a successful or unverified run. After merge, a host may record `cleanup_candidate` only when the declared policy's `x` consecutive post-merge integration rounds have each been explicitly accepted by the coordinator, no rollback occurred in those rounds, a fresh host recheck is current, and durable evidence contains the candidate, base, and integration commits together with the required review, verification, and integration receipts. Pending, observed, inferred, or otherwise unverified results are not accepted rounds. `cleanup_candidate` is eligibility evidence only; it is not deletion authorization. No component automatically deletes a worktree, cache, receipt, evidence, or user data. If no retention strategy is declared, or if any gate or evidence is missing, retain the material permanently until an explicit, separately authorized cleanup policy exists. Derived project-index snapshots use a separate two-step maintenance command. Run `uv run python -m devkit_runtime.index_maintenance preview` first, inspect the exact candidate and protection sets, then pass its unchanged identity to `uv run python -m devkit_runtime.index_maintenance apply --preview-id <id>`. Apply holds the Orchestrator writer fence, rechecks cross-database snapshot references, keeps the newest two snapshots per workspace, and deletes at most 32 oldest candidates within fixed row and content-hash budgets. Parser-cache and blob rows are collected only when the approved batch made them unreachable. New stores use bounded incremental vacuuming; older stores without incremental auto-vacuum reuse freed SQLite pages internally. Run `uv run python -m devkit_runtime.index_maintenance compact` to inspect that boundary; a legacy store returns `RETENTION_FULL_REWRITE_REQUIRED` until the operator explicitly repeats it with `--allow-full-rewrite`. The one-time rewrite checks for at least twice the database size plus 64 MiB of free space and stops on active readers instead of gambling with a low-space database. Compaction reports observed database/WAL bytes before and after. Any stale preview, missing schema, budget overflow, lock failure, or invalid reference fails closed with zero deletion. Atlas data is never an index cleanup target. ## Deterministic Fast Lane The Fast Lane compiler is in mcp-tools/devkit_fastlane/scripts/fastlane_routing.py and mcp-tools/devkit_fastlane/scripts/team_efficiency.py. The MCP `fastlane_compile` entry returns `team-efficiency/fast-lane-plan-v3` for a model-neutral request only after a read-only RuntimeRoot unit of work resolves the registered workspace and snapshot. The snapshot must be current, `INDEX_READY`, bound to the repository Git HEAD, and its persisted `include_paths` must fully cover every writer `write_scope`. - `reasoning_effort` is required and accepts only `low`, `medium`, `high`, `xhigh`, or `max`; the MCP output never dispatches a worker. - `team-efficiency/fast-lane-plan-v3` fixes `plan_only=true`, `dispatch_state="not_dispatched"`, and `execution_authorized=false`. Assignments use `team-efficiency/local-writer-plan-v2`, with bounded `route_requirements` and coordinator-owned `selection.state="unselected"`; path-free `index_evidence` includes snapshot/binding hashes, `include_paths_hash`, and the compiled `scope_hash`. - `record_model_selection` binds `plan_item_id`, `requirement_hash`, the exact model ID and effort, and the coordinator's reason. It is a `selection_only`, `not_dispatched` record; the dispatch tool remains the availability gate. An explicit request intent cannot be replaced by a fallback model. - `INDEX_STALE` rejects filesystem or Git drift. `INDEX_PARTIAL` rejects either a partial snapshot or any snapshot whose include roots omit a writer scope. - Caller IDs are selectors, not authority material. The public MCP request and public `compile_fast_lane` Python API accept no local index root, Git HEAD, or private planning material. - The public Python compiler/CLI still does not consume host status, account usage, index evidence, or a worktree root and remains the blocked plan-v1 diagnostic boundary. ### Account-usage boundary Account usage is not a Fast Lane input or routing mechanism. This release has no account-usage coordinator, cache, or external collector contract. ## Safety and scope boundaries - Atlas is deterministic and local. It cannot currently connect to third-party sources; it does not call an LLM, vector store, network service, shell, or patch applier. - Relay compiles explicit packages and returns host actions; it does not fabricate successful spawns. The host owns the actual Codex dispatch. - Worktree, branch, lease, task, snapshot, receipt, and evidence identities are bound and fail closed on stale, forged, cross-workflow, or conflicting input. - stdio stdout is protocol-only. Diagnostics go to stderr. - Runtime data, task scratch, worktrees, caches, and verification evidence remain local and bounded. ## Verification Run the release verification from the revision being built: cd mcp-tools uv run --locked pytest -q uv lock --check uv run --locked ruff check devkit_atlas/service.py devkit_continuity devkit_runtime/atlas_acceptance.py orchestrator/service.py project_index/checkpoints.py project_index/service.py project_index/store.py uv run --locked python -m compileall -q devkit_atlas devkit_continuity devkit_runtime orchestrator project_index CI and fresh-artifact checks are the source of truth for current test counts. They verify the exact 17-tool inventory, empty prompt/resource lists, protocol-clean stdout, normal and rejected calls, missing-host capability failure, and source-checkout independence. This README intentionally does not freeze a transient regression count. ## Version This repository represents the versioned v1.2.1 package. Release notes are in [CHANGELOG.md](CHANGELOG.md); build and install from the checked-in manifest, artifact allowlist, and locked dependency set. A maintainer dispatches Release from current `main`; it validates all declared gates, creates the annotated tag, and publishes the matching GitHub Release. Pushing a tag alone does not publish. ## License [AGPL-3.0](LICENSE).