codetools / Deploy

codetools deploy

codetools deploys itself with its own deploy engine, the deploy package (SPEC-012). The deployed copy lives in /opt/codetools. Every other consumer runs that copy, never the checkout: Claude's MCP server, the codebase-map hook, orchestrata's realize output and the packages/contracts tests. The checkout is ~/workspace/orchestrata.codetools. This page describes the engine, the launcher that drives it, and the state measured on 2026-10-23. For how this deployment sits among the others on the host, see Deployment.

Sources:

• codetools deploy --help;
• the deploy module docstrings at a5c419f5, read through the AST toolkit;
• ~/bin/ct-install and ~/bin/ct-smoke;
• /opt/codetools/audit.log and the install logs reports/ct8-install69..75.log;
• ls, du and readlink of /opt/codetools.

Release layout on disk

The engine: codetools deploy install

install(repo, ref, prefix, python="python3.14t") "deploys the committed content of a git ref - never the working tree - into prefix/releases/<hash>, with a uv venv built and smoke-checked at that final release path before current ever points at it, then links prefix/.venv, prefix/VERSION and prefix/bin through current/...; an already-current sha is a no-op" (deploy/install.py).

The pipeline has four phases, each a stage with its own gate (deploy/pipeline.py):

• build: a hash-pinned artifact with a deterministic content hash.
• verify: a real SPEC-005 pytest run and SPEC-006 coverage capture against the artifact. It blocks promotion on red tests or on a coverage regression. The full suite is the default; --affected-scope opts into affected-set selection, which is marked EXPERIMENTAL.
• promote: "atomic: a fully-built staging directory moves into releases/<hash> with one os.rename and the current symlink flips with one more os.rename; nothing is ever streamed into the live tree; exactly one audit line per switch". A flipped current also renders the .mcp.json fragment (REQ-007-007).
• rollback: "restores the exact previous artifact (from the audit log) and re-verifies its content hash".

More rules from the docstrings:

• A verifying promote first checks the source repo's declared toolchain (REQ-012-019, prerequisites.assert_verify_requires).
• Every uv subprocess crosses an explicit environment allowlist (ADR-0008), so "ambient toolchain pollution and secrets never reach a build".
• A prefix's first release skips verify, because there is no baseline (REQ-012-018, ADR-0003).
• An installed prefix never verifies under sys.executable (D14).

Identity: codetools deploy verify-identity

"Health is not identity: a unit can report active mid-restart race; verify_identity proves the running units ARE the deployed release" (deploy/identity.py). It checks:

• that VERSION agrees with the audit log;
• the entry-point shas;
• the live /proc identity of each unit;
• oneshot units, through a sibling timer;
• that no path leaks into /home/*/workspace.

Every check reports its own name and reason. With --mcp-json, it also requires the registered codetools command to resolve inside the current release.

The launcher: ct-install (the Hermes model, 2026-10-22)

~/bin/ct-install <label> [ref] is the approved way to deploy codetools. It runs without a permission prompt through an allow rule in settings.local.json. On 2026-10-22, Mohamed said "make the installer like hermes". Since then, the launcher builds the release from its lockfile and promotes it with --no-verify, so no test-suite gate runs at deploy time. It then proves the result through the installed command, and rolls the promote back if either proof fails.

What the launcher does, step by step:

1. Refusals. It refuses when a codetools deploy install process is already running (RUL-032: one run per code state), when reports/ct8-install<label>.log already exists, or when the working tree is dirty. Its own logs and .claude/ are the only exceptions to the clean-tree rule.
2. Environment. It unsets PYTHONPATH and PYTEST_ADDOPTS. Install 68 died because the scope inherited PYTHONPATH=/opt/orchestrata-tools/shim from the Claude shell, and the suite's import-shadow guard rejected it (commit 6979a4ad). It sets PYINFRA_VENV, CC=/usr/bin/gcc and CXX=/usr/bin/g++.
3. Install. It runs uv run codetools deploy install --repo . --ref <sha> --prefix /opt/codetools --python python3.14t --no-verify inside a detached systemd-run --user --scope, logging to reports/ct8-install<label>.log.
4. Proof. It runs /opt/codetools/bin/codetools deploy verify-identity --prefix /opt/codetools --expect-commit <sha>, then ct-smoke <sha>.
5. Rollback. If either proof fails, it runs codetools deploy rollback --prefix /opt/codetools, prints ROLLED-BACK after a failed post-promote check, and exits 12.
6. Markers. The log ends with WALL <seconds>s and INSTALL-EXIT <code>.

ct-smoke <commit> makes three live calls through the installed command:

• codetools --version must name the commit;
• ast map of a two-class scratch repo must report "symbols": 3 and write class Child(Base) into CODEBASE_MAP_FULL.md;
• mcp list must carry an ast map tool.

It prints SMOKE-OK <commit>, or SMOKE-FAIL <check> and exits 1.

The suite-gated verify is still available: run codetools deploy install by hand, without --no-verify. The launcher's comment gives the reason for skipping it: the full verify takes minutes, and on install 72 even --affected-scope "spent 60 s selecting, then ran 8 shards for 3+ min".

Install record, 2026-10-22 and 2026-10-23

The audit log holds 52 promote lines. The last three promotes record verify=skipped. The last two verified baseline entries (2026-10-18) were full-scope and red, with 20 and 28 failed tests.

How the codetools deploy relates to orchestrata

• The templates generate orchestrata's components. codetools realize scaffolds the component packages of orchestrata's packages/ tree into .realize-out* directories. In wt-MAP-PRECOMMIT at 8a2cb42ad, 2,882 tracked files sit under .realize-out paths: contracts 766, kernel 744, volks 447, governance 423, knowledge_graph 270, gateway 134, session 98. packages/contracts/pyproject.toml says it was "scaffolded from codetools realize's .realize-out/pyproject.toml".
• Generated code imports codetools. The generated tests carry @traces from codetools.rtm (from codetools.rtm import traces; the decorator is SPEC-015 REQ-015-015). The AST toolkit's who-imports codetools.rtm over wt-MAP-PRECOMMIT/packages found 2,114 import sites. 2,041 of them are in .realize-out* directories; the other 73 are in packages/contracts (design 26, tests 46, increments 1).
• orchestrata depends on the deployed copy by path. The packages/contracts test group lists codetools, with codetools = { path = "/opt/codetools/current", editable = true }. It is an editable install of whatever release current points at.
• codetools no longer depends on orchestrata (commit a5c419f5, 2026-10-23 00:01). read_requirements takes the OpenSpec provider as a parameter and defaults to resolve_openspec(). That function imports orchestrata_tools.openspec, then orchestrata_ultimate.openspec, and refuses with a message naming codetools[openspec] when neither is installed. orchestrata-ultimate moved from a hard dependency to the openspec extra and the dev group. The commit message records that in an environment without the extra, "codetools --version and ast map both run with 0 orchestrata packages installed".
• orchestrata's config deploy registers codetools. install-claude-config.sh renders the MCP fragment, registers it and proves identity (see codetools MCP).
• Every project's codebase map comes from codetools. The user-level hook codemap_refresh.sh (SessionStart and SubagentStart) runs env -u PYTHONPATH /opt/codetools/bin/codetools ast map <root> --with-full in a repo that opts in with a [tool.codetools.map] table. It logs to ~/.local/state/codetools/codemap-hook.log.

Open question: where codetools is hosted

The codetools repository has no git remote (git remote -v is empty on 2026-10-23). Everything that consumes it reaches it by local path:

• the plugin marketplace is a directory source at ~/workspace/orchestrata.codetools;
• ct-install installs from --repo ., and VERSION records repo .;
• orchestrata's packages/contracts pins /opt/codetools/current.

Nothing is backed up off this machine, and no other machine can install codetools from a ref. The question is open and has not been ruled:

Recommendation: A. It keeps codetools project-agnostic, matches the existing GitLab-sourced deployments, and closes the no-remote gap without moving code. This is a recommendation only. It becomes a decision when Mohamed rules on it, and then an ADR in docs/adr/.

Related

• codetools
• codetools verbs
• codetools MCP
• codetools plugin
• codetools runbooks
• codetools blockers
• Deployment
• Deployment inventory