Skip to content

fix(crew): coordinate the crew through one rule module and a call token - #62

Merged
ancongui merged 52 commits into
mainfrom
fix/crew-coordination-26.11.27
Nov 20, 2026
Merged

ancongui merged 52 commits into
mainfrom
fix/crew-coordination-26.11.27

Conversation

@ancongui

Copy link
Copy Markdown
Collaborator

What and why

Release 26.11.27. The crew's coordination made several mistakes on 26.11.25: a main-session dev command was
credited to a crew member, a step assigned to a member was lost when its lane ended, a review the member reported ✓
stayed unverified (on Claude Code and on Codex), fix steps after a ✗ review could not start, and a local CI step was
cut off at 30 minutes. This release redesigns how the crew is coordinated and how devkit knows who runs each
command, so these mistakes cannot happen again.

Changes

  • Coordination rules in one module (lib/devkit/coord.py), with 13 invariants every change is checked
    against, and a model-based test that hunts for sequences that break them. Assigned steps outlive lanes and are
    claimed oldest first; a blocked step frees its lane; a lane's files are its running steps' scopes; a resumed
    member takes its step; a ✗ review lets the next step start without approving.
  • Caller identity. Each shell call carries a token that names its caller, pinned to the process its call runs
    in. A state change devkit cannot verify is refused. Codex threads follow the same rules. Project code devkit runs
    (CI steps, tests, git hooks of devkit's git commands) gets no token, and state changes through a token by commands
    the call's text does not run are audited.
  • Gates and CI evidence. The gates judge every stop, a member is sent back once per lane life, and Codex proofs
    are read without devkit's stamps. CI step limits come from timeout-minutes or local history; a job that never
    started is classed (not_started, budget, workflow_invalid); dev ci watch takes its limit from the
    workflows' chain of jobs.
  • Docs on the crew, agents, commands, CI, troubleshooting, the audit trail and SECURITY.md.

How to verify

  • dev ci --run, and /usr/bin/python3 -m unittest discover -s tests -t . for Python 3.9.
  • python3 -m unittest tests.test_coord_model tests.test_identity_runners tests.test_identity_redteam for the rules
    model hunt and the attacks on real processes.

What ran:

  • dev ci --run on 132c715: 8 steps green in 39m56s (unit tests 36m41s, gitleaks, semgrep, osv-scanner, trivy,
    zizmor).
  • The full suite on the macOS system Python 3.9 (/usr/bin/python3) on 064e048: 6036 tests OK, 3 skipped.
  • Code review approved after one round of fixes; security review approved the call token package after three
    red-team rounds on real processes.
  • Live check: Codex 0.167.2 gives each thread its own CODEX_THREAD_ID. In Claude Code's default and acceptEdits
    modes the change adds no permission prompt over 26.11.25.

Risk and rollback

  • Risk: a dev state change devkit cannot place is now refused instead of being made as the main session's; the
    refusal names the fix (run it as a command of its own). Rollback: dev install --version 26.11.26.

Not done:

  • The Codex half of the permission-prompt check and the sandbox check run on the installed release.
  • An allow rule for dev does not cover devkit's VAR= prefix outside bypass mode; this predates the release and
    is tracked.

Links

  • Release notes: the 26.11.27 section of CHANGELOG.md.

The crew hit nine coordination faults on 26.11.25 (steps that never close, lanes that take no queued step, blocked steps holding files, the tech lead's commands taken for a member's, CI causes left unnamed); the engineers who fix them need failing tests first, on Claude Code and Codex, and a model-based hunt for faults of the same kind.

Each fault has a test at the function or command that decides it, with that day's inputs; the Codex variants drive the real hooks with Codex rollouts. A seeded model-based test walks assign, launch, step, block, skip, reopen, resume, ask, answer, wait and stop on both hosts and reports each broken rule with its shrunk sequence (about 35 s).

Verified: the 23 tests fail on purpose on 26.11.26 for their fault's reason (python3 3.15 and /usr/bin/python3 3.9: 23 failures, 0 errors); dev test prove: all 23 fail without a fix; dev test audit: 0 high, 0 medium
A file glob such as docs/crew.md was read as a folder, so docs/**/bug*.md was refused as overlapping it; and the identity token needs its hash in the call entry's first write.

Root cause: progress._glob_segments appended an implicit ** to every glob, so a literal file name overlapped any recursive glob in its folder

coord.py holds the pure rules: held steps, derived scope, intents, claims, block and unblock, the invariant check and the glob overlap. call_opened takes an optional token_sha256 written in the same atomic write.

Verified: python3 -m unittest tests.test_progress tests.test_lanescope tests.test_scope tests.test_coord_kernel tests.test_coord_calltoken: OK; the QA glob clash test now passes
A reviewer the crew gates sent back once, who then recorded its step correctly and reported a clean check, still ended its review unverified, so the tech lead had to close the review and record the approval by hand, on Claude Code and on Codex.

Root cause: gates.check returned before judging any stop of a member already in crew_gated, after dropping its pass token, so no later stop of that session could ever pass

Every stop is judged by the current rules. A send-back is keyed by the lane's life (its start or last resume), so a resumed lane may be sent back once again. A stop let through with findings writes no token, is audited as let through, and keeps its findings for the tech lead (gates.let_through). check takes a judge for model-based tests.

Verified: python3 -m unittest tests.test_gates_judgment tests.test_crew_gates tests.test_gates_skills tests.test_gates_writes tests.test_approvals_token tests.test_hooks_codex: 99 tests OK
The Codex stop fixture wrote rollouts no gate could read (no folder on each command, no history ordinals, an untrusted dev), so a Codex review failed for the fixture's sake rather than devkit's.

Codex members' commands carry their folder and ordinals, the rollout says where the member's history starts, and the stop hook finds devkit's own bin/dev first. The resumed Codex reviewer approves on 26.11.26, so that test is removed; the model applies the review rule only to stops that end the lane.

Verified: on an export of 26.11.26 the Codex variants and the model fail for their fault's reason (16 failures, 0 errors); dev test audit 0 findings
dev ci --run stopped a green 36-minute unit-test step at 30 minutes with exit 124, so the local evidence for a push needed a second, longer run of the whole suite.

Root cause: run_local_ci gave every step a fixed limit (step_timeout=30 and the --step-timeout default of 30), unrelated to the timeout-minutes the workflow declares or the step's recorded duration

A step's limit is --step-timeout when given, else its own timeout-minutes, then its job's, else 1.5 times its longest whole pass recorded here when that is over 30 minutes, else 30. Step records keep the longest pass across partial reruns. A timeout keeps exit 124 and prints the limit and where it came from.

Verified: python3 -m unittest tests.test_ci_limits tests.test_coordination_ci.LocalStepLimitTests tests.test_gitx tests.test_gitx_ci_shortcuts tests.test_pipelines: all OK
A run whose jobs GitHub never started (an Actions budget, failed payments, no runner) was reported as 'failing log unavailable: log not found' by dev run view --failed and dev pr checks, and as class unknown by dev ci watch, so nobody saw that no code change or push could fix it.

Root cause: gitx._run_view and failing_logs only read the failed log, and ciwatch.diagnose classified by that log or the job names; none read the job's check-run annotations or noticed the job had no steps

One reader, ciwatch.never_started, reads a failed job's check-run annotation when the job has no steps or no log, and classes it not_started (subclass budget for an account limit) with the one next action. A run that failed at startup is workflow_invalid. The annotation is shown as one redacted line of at most 300 characters.

Verified: python3 -m unittest tests.test_ci_not_started tests.test_coordination_ci tests.test_ciwatch tests.test_ciwatch_sessions tests.test_acceptance_watch tests.test_dashnow tests.test_watch_e2e tests.test_watch_stop tests.test_gitx: 356 tests OK
devkit's test job allows 40 minutes for each half of the suite on a runner, but dev ci --run runs it once over the whole suite, which passed in 35.7 minutes here: a 12% margin before the green step ends with exit 124 again.

Root cause: a literal matrix is not expanded locally, so the step runs every leg's work in one run, while the job's timeout-minutes it was given is one leg's

For a job with a literal matrix, the step's limit is the larger of the job's timeout-minutes and 1.5 times the step's longest local pass; devkit's unit-test step gets 54 minutes. A job without a matrix keeps its declared timeout.

Verified: dev test run (test_ci_limits, test_coordination_ci, test_gitx, test_gitx_ci_shortcuts, test_pipelines, test_cli_ci, test_workflow_ci): 251 passed; dev test prove: the new test fails without the change
Members lost steps queued for them when their lane ended or resumed, kept the files of blocked and closed steps, and a member's ✓ without --step closed nothing while printing ✓.

Root cause: intent lived on short-lived lanes (waits_lane, dropped at lane end), scope was a stored lane copy counting blocked steps, and progress.step resolved a member's target only from --step

Steps keep an intent that a free lane claims oldest first; a blocked step frees its lane and its answer returns it first; scope derives from running steps; a member's record closes its single running step; the CLI prints ✓ only when a step changed. Existing tests that pinned the replaced behavior are updated, each with a comment.

Verified: copy with committed identity: 423 tests in 12 coordination and progress modules OK except the Codex message acknowledgment test, which the caller identity change covers; both model hunts pass my rules
These assertions pinned behavior the coordination fix replaced: queue entries in waits_lane, stored lane scope, read-only lanes after a reassignment, and a member's record that closed nothing.

Each changed assertion carries a comment naming the rule it now checks.

Verified: python3 -m unittest of the seven files in a copy with the committed identity module: OK
A review or --approves verdict the crew gates did not pass was dropped with a history line only, so nobody heard the work was still owed; reopen and begin also changed step states with no history entry.

Root cause: _lane_verdicts and _end_member_step recorded refused verdicts only in history and audit, and reopen, begin and assign moved steps without _log_change

One notice per lane end names the reviews and verdicts that do not count; the hook names the findings. The model test adds coord.check after every action of the QA hunt.

Verified: python3 -m unittest tests.test_coord_scenarios tests.test_codex_coord_parity tests.test_coord_calltoken: OK; DEVKIT_MODEL_SEEDS=60 tests.test_coord_model: 7 OK
A commit's CI watch gave up after a fixed 90 minutes, shorter than a chain of jobs that need each other can take, and a job that no runner took (a runs-on label no runner has) ended as a plain 'still running', so nobody learned why the run never finished.

Root cause: the watch's limit was the constant 90 in watch, start_background and cmd_wait, unrelated to the jobs' timeout-minutes, and nothing told a job waiting for a runner from one still at work

The limit is the longest needs-chain of job timeout-minutes in the GitHub workflows that run on a push or pull request, plus 30 minutes for the queue, between 90 and 360; the background watch after a push gets it. A GitHub job that has waited 30 minutes for a runner while nothing else of its commit runs is told once to an agent's wait with its next action, and named when the watch reaches its limit. cistatus keeps GitHub's own status, so a job waiting for an environment's approval is never taken for one.

Verified: dev test run (test_ci_watch_limits, test_ci_not_started, test_coordination_ci, test_ciwatch, test_ciwatch_sessions, test_cistatus, test_watch_e2e, test_watch_stop, test_dashnow, test_codex_watch, test_watch_gate_wiring, test_gitx): 360 passed; dev test prove: 4 new tests fail without the change
The tech lead's commands were refused as a crew member's while a member's open call held the same words (dev progress begin while a member waited on a question quoting it), and dev crew ack with a nested dev crew read was refused as not_recipient: devkit guessed the caller from command text.

Root cause: identity._find took any open call whose text held the command's words in order (progress._names_args) as the caller, and could not see words an expansion produced, so a member's quoting call outranked the tech lead's own and a nested substitution matched nobody

The PreToolUse hook gives every shell call a token (DEVKIT_CALL=<tool_use_id>.<nonce>) once its ledger entry holds the nonce's SHA-256 and the session record lists the call; a dev command with a token is the entry's caller when the token is this session's, its agent's and its call shell's (pinned on first use, O_EXCL), the call is open and the process is not detached. A session that stamps tokens refuses a tokenless state change; on Codex a tokenless command may name its lane by CODEX_THREAD_ID, and the root thread maps to the tech lead only after a member's token call showed per-agent thread ids. Without a token, text matching drops a call that provably runs another command and matches nested substitutions whole. Detached spawns drop the token, audit.redact hides it, and identity records carry fixed fields, never the nonce.

Verified: dev test run (10 files): 143 passed; dev test prove: the new identity and Codex token tests fail without the change
Every shell call now carries its call token in front of the command, so two tests that compared the whole rewritten command failed although the lane route they check still holds.

Each test checks that the token prefix is there and compares the command without it (identity.strip_token).

Verified: python3 -m unittest tests.test_hooks_wiring.FailOpenTests tests.test_caller_identity: 38 passed
A follow-up launch whose description named a step its member had already finished was rewritten to take the member's next waiting step, so the follow-up took work the tech lead had not given it.

Root cause: hooks._launch_naming scored the description only against open steps, so a description naming a done step named none of them, and the one waiting step was put in its place

The description is scored against the member's done steps too: naming one leaves the launch as it is, binding no step. A step waits for a launch only when its intent binds it to no lane, read through progress._queued_lanes.

Verified: python3 -m unittest tests.test_hooks_launch: 8 passed; dev test prove: both new tests fail without the change
A member the crew gates sent back once and then let through with findings ended its review unverified, and the tech lead did not hear what was still missing.

Root cause: subagent_stop never read the findings gates.check keeps for a stop it lets through (gates.let_through), so they reached nobody

After the gates let a stop through, the hook reads those findings and posts one devkit notice to the tech lead, naming the member by role and up to six findings.

Verified: python3 -m unittest tests.test_hooks_gate_findings: 1 passed; dev test prove: it fails without the change
Under the approved threat review a compound dev crew ack gets a call token only where Codex never asks; the test ran under an asking policy and read the receipt from the raw run file, where the messaging store's receipt does not show.

Where Codex never asks (config.toml approval_policy never, as dev setup writes it) the ack succeeds and the receipt is read from the messaging store; where Codex may ask, the refusal must name the plain-call fix.

Verified: before 3c4a549 both cases fail (not_recipient); on the branch the never-asks case passes and the asking case still fails: the ack's refusal drops identity's plain-call reason; dev test audit 0 findings
devkit's code and tests never name a client, and work item ids point into the private handoff repository; the comments already say what each test reproduces

Verified: dev test run on the three files: 11 passed
A run a newer push cancelled, or a matrix leg fail-fast stopped, was reported as a job that never started with the advice to rerun it; a failed test named test_billing read as an account limit; and dev run view exited 0 on a run GitHub could not start.

Root cause: never_started counted every job without steps, cancelled ones too, diagnose ran it for stopped runs, NOT_STARTED_RE and BUDGET_RE matched the bare words billing and budget, and _run_view only looked at failed jobs, which a startup failure has none of

A stopped run skips the never-started check; a cancelled job counts only when its annotation says it was not started; dev run view leaves cancelled jobs out of that check. The patterns match only GitHub's own phrases. dev run view classes a startup failure as workflow_invalid, with its next action, and exits 1.

Verified: python3 -m unittest tests.test_ci_not_started tests.test_coordination_ci tests.test_ciwatch tests.test_gitx tests.test_ci_watch_limits: 252 tests OK
A slow step that ran past its limit never earned a longer one, since a timed-out run records no pass, and --step-timeout 0 was ignored while -5 ended every step at once with exit 124.

Root cause: the timeout line named only the limit, and --step-timeout was a plain int that step_limit skipped at 0 and used as given below it

The timeout line names dev ci --run --resume --step-timeout with twice the limit. --step-timeout takes a whole number of minutes of 1 or more; argparse refuses anything else.

Verified: python3 -m unittest tests.test_ci_limits tests.test_coordination_ci.LocalStepLimitTests tests.test_gitx_ci_shortcuts: all OK
A watch's limit counted a job without timeout-minutes as no time at all and skipped the jobs of a local reusable workflow, a run waiting for its concurrency group was taken for one waiting for a runner, and the detached watcher kept the call token of the call that started it.

Root cause: watch_minutes added only declared timeouts from gitx.plan, which leaves a job that calls a reusable workflow without one; RUNNER_WAIT held GitHub's pending; start_background passed no environment of its own to Popen

watch_minutes reads the workflows: a job counts its timeout-minutes or GitHub's 360 without one, a local reusable workflow counts its own longest chain and a remote one 360, still between 90 and 360. Only queued and requested wait for a runner. The watcher starts with identity.detached_env().

Verified: dev test run (17 files: test_ci_watch_limits, test_ci_not_started, test_ci_limits, test_coordination_ci, test_ciwatch, test_ciwatch_sessions, test_cistatus, test_watch_e2e, test_watch_stop, test_dashnow, test_codex_watch, test_watch_gate_wiring, test_gitx, test_gitx_ci_shortcuts, test_pipelines, test_cli_ci, test_workflow_ci): 455 passed
The cancelled-leg, billing-test and startup-failure cases sat inside the class of the never-started tests, so a change to them read as a change to those tests.

They move to GitxStoppedRunTests, with the same fake gh; no test changes what it checks.

Verified: python3 -m unittest tests.test_ci_not_started: 11 tests OK
identity.STATE_CHANGING named a progress order command dev does not have and missed commands that change crew, session, task and plan records, so a tokenless call of those fell back to text matching in a session whose calls carry tokens.

Root cause: the set was written from the design's list instead of from dev's parser, and nothing checked it against the commands dev runs

A test walks dev's parser over progress, crew, session, task and plan and runs every subcommand twice, in a fresh fixture: once stopped where it asks who calls, once as the tech lead with a snapshot of the records before and after. A subcommand that changes records must be in STATE_CHANGING, one that only asks who calls in the new READS, and every listed name must exist.

Verified: dev test run (7 files): 164 passed; dev test prove: both coverage tests fail without the change
A refused compound ack told the tech lead only not_recipient, not that it must run as one plain dev command.

Root cause: _readable_message raised a fixed not_recipient text and dropped the reason identity gave progress.caller as why

Verified: committed tree plus this change: python3 -m unittest tests.test_coordination_codex OK, the compound ack test included
Three Codex lifecycle tests pinned a resumed child that stays shut out and takes no role step, which the coordination fix replaced.

They now check that the resumed child takes no closed step, that a reopened step goes to its exact owner, and that a role step goes to the member's resumed lane.

Verified: committed tree plus this change: python3 -m unittest tests.test_codex_lifecycle OK
A review recorded with ✗ stayed unverified and blocked the step after it, so the fix waited for nothing and the tech lead closed the review by hand.

Root cause: deps_open counted an unverified review as open whatever its verdict, though a review that asked for changes is finished work

A review that ends with ✗ or ⚠ keeps verdict changes; the step after it is ready while the reviewed work stays unapproved. The model hunt adds a reviewer that asks for changes and a fix step after the review.

Verified: committed tree plus this change: tests.test_coord_scenarios, tests.test_coord_kernel OK; DEVKIT_MODEL_SEEDS=60 tests.test_coord_model 8 OK
The threat review asked that every step change say how devkit found its caller and which call made it, and that a dev process resolve its caller once before anything else runs.

cli.main resolves the caller once when the call token is present (progress.mark_calls); each history entry carries how and tid. The background sync starts with identity.detached_env(), so it never acts for the call that started it.

Verified: committed tree plus this change: 632 tests in 16 modules OK, except a workdir test that only fails in a copy without the repository and passes here
A crew member could act as the tech lead or as another member: on Codex by dropping its token and setting CODEX_THREAD_ID, on Claude Code by reading the tech lead's token from the process list and using it first from its own shell, and below a nested agent started through node that devkit did not recognize.

Root cause: the Codex thread rule trusted CODEX_THREAD_ID, which any child process sets, before refusing a tokenless state change; the token was pinned to whichever shell used it first; and core.is_agent_process knew only claude and codex by their own executable name

The thread rule no longer decides a state change where the hook stamps every call (stamps_all), and elsewhere takes a lane or the root only when that caller's own open call holds the command; every resolution is audited (caller.thread). A token holds only when the call shell closest to the agent carries it in its own command line where the hook writes it, or, when that shell replaced itself with the command, the call's text runs this very dev command. Agents run through node, Gemini CLI and opencode count as agents, a Claude Code token carrying a Codex thread id is refused, and a Codex member's rewrite no longer carries the root thread's id.

Verified: dev test run (10 files): 317 passed; the red team's probes now print refusals; 9 of the 10 red team tests fail against the previous commit
It pinned the manual relink a free lane needed once its step's dependency closed, which the claim rule replaced.

Verified: python3 -m unittest tests.test_plan_dag OK
On live Codex, review lanes that ran dev progress step and reported favorably still ended unverified, with the gate finding 'proofs: dev progress step', so every Codex review needed the tech lead to close it by hand; design and tooling steps hid it, since they close on the member's own call.

Root cause: a Codex CommandExecution item records the command as it ran, with the DEVKIT_SESSION, DEVKIT_FROM_AGENT and call-token stamps devkit's hooks write in front of it, and gates._receipt_words took the first of those assignments for the program, so it found no dev command

_receipt_words reads the command without the call token (identity.strip_token) and without the lane and session variables, inline or exported. Any other assignment in front of dev, such as a PATH of its own, still keeps it from counting. A Claude Code transcript records the command as the model wrote it, so its path is unchanged.

Verified: dev test run (test_gates_codex_proofs, test_gates_judgment, test_crew_gates, test_gates_skills, test_gates_writes, test_approvals_token, test_execution_receipts, test_skillguard, test_readonly_attribution, test_crew_codex_diagnostics): 146 passed; dev test prove: 7 of 7 fail without the change; the faithful Codex review test fails on HEAD's gates.py and passes with the fix
A route that bypassed assign left the tech lead's running step his, so the member's free lane could not take it.

Root cause: the running-to-pending hand-over lived in assign, not in _route_to_lane, which reopen and direct routes also use

Verified: committed tree plus this change: 419 tests in 8 modules OK except the copy-only workdir test
These pinned replaced behavior: a launch naming none of its member's steps took none, a free lane kept a closed step's files, and a stopped member's waiting step went back to the tech lead.

Each changed assertion carries a comment naming the rule it checks now.

Verified: python3 -m unittest tests.test_modes tests.test_roles tests.test_messaging on the committed tree: OK
The model's clean stop carried no receipt the gates accept (no folder for the Claude Code call, a Codex rollout older than 0.167.2), so the gates sent it back for a missing dev progress step and the review rule failed for the fixture's sake.

A clean stop's transcript holds each dev progress step as it ran: a Claude Code Bash call with its result and exit code, or a Codex 0.167.2 rollout whose CommandExecution items carry devkit's lane and session stamps, as tests/test_gates_codex_proofs.py writes them; the members work in a real checkout. An unclean stop holds no step and is still sent back.

Verified: on the branch the 6 model rules hold (python3 3.15 and /usr/bin/python3 3.9); before d0030c5 the review rule fails on Codex: the crew gates did not pass the resumed reviewer's clean report; the gates find the unclean stop's missing dev progress step on both hosts; dev test audit 0 findings
A resumed Codex reviewer's clean report after a send-back was never judged on 26.11.25, so review lanes ended unverified; the Codex case was removed after a check against a baseline that already held the gates fix.

The member's rollout has Codex 0.167.2's shape: a session_meta that is not a fork, turn_context and task_started, and per command the code-mode exec call and the CommandExecution item of the command as it ran, devkit's stamps in front of it, with its thread, folder, exit code and ordinal. The reviewer resumes through the SubagentStart hook.

Verified: before d0030c5 the case fails: the crew gates did not pass the resumed reviewer's report (with the 0.167.2 or the 0.167.0 fork rollout, stamped or bare); on the committed branch the 7 Codex tests pass; dev test audit 0 findings
Members and the tech lead need to know how devkit names the caller of a dev command, which step a free lane takes, that a blocked step frees its lane, how the crew gates judge every stop, and why a local CI step or a CI watch stops when it does.

The crew page, the agents page, and the crew skill describe the call token, the claim order, blocked steps, scopes that follow running steps, filename scopes, and gates that judge every stop. The CI pages and the cicd skill give the local step limit, the watch limit, the runner wait line, and the never-started job classes. The audit page lists the caller identity records; SECURITY.md says what the call token protects and what it does not; the bug registry page says how to avoid its notification mail.

Verified: dev docs check on the 11 pages: 0 markdownlint issues, all links resolve, 0 Vale errors (6 earlier warnings on unchanged lines); dev test run tests/test_consistency.py tests/test_crew.py tests/test_skillguard.py tests/test_lessonlint.py (204 passed) and tests/test_install.py (34 passed)
dev crew rules did not show the coordination rules devkit now enforces, still called the gate-findings rule planned and the caller check the call ledger, and a member whose guided decision freed its lane for its next step was told to stop.

Root cause: the rules catalog in crew.ENFORCEMENT and the guided-decision message in _ask_decision were written before a blocked step freed its lane and before the call token and the judged stops existed

The catalog adds E-claim (coord.claim), E-call-token (identity.speaker) and E-blocked-frees (coord.block), rewords E-caller for the call token, and marks E-gate-findings enforced by gates.let_through. A member whose lane takes its next step after a guided decision is told that step and how to record it, and only a member with nothing else to do is told to stop.

Verified: python3 -m unittest tests.test_crew_rules tests.test_crew tests.test_consistency: 108 tests OK
A member's command that carried another caller's Codex thread was audited as a plain change with severity info, so dev audit's security views never listed it.

Root cause: identity records it through _audit_identity, which the test that every recorded action is registered did not scan, and audit.ACTIONS had no entry for it

audit.ACTIONS registers codex.thread-shared as security, notice, and the registry test now scans _audit_identity calls too.

Verified: python3 -m unittest tests.test_audit: 126 tests OK
dev ci watch in a terminal still gave up after a fixed 90 minutes, while the background watch after a push and --wait used the repository's own limit, and three doc rows said the default was 90.

Root cause: the dev ci watch parser set --timeout default=90 and cmd_ci_watch fell back to 90, so ciwatch.watch never got None to derive its limit from

--timeout defaults to None with help naming the derived limit, cmd_ci_watch passes it as given, and docs/commands.md, docs/ci-cd.md and docs/troubleshooting.md say all three watches follow the same limit unless --timeout gives minutes of its own.

Verified: dev test run (test_ci_watch_limits, test_cli_ci, test_ci_commands, test_ciwatch, test_consistency, test_crew, test_crew_rules, test_audit, test_cli, test_docs_check): 329 passed; dev docs check clean
A crew member that read the tech lead's call token from ps could still use it: it exec'd its call shell into python, set a fake argv[0] with exec -a, or ran zsh -c "$(cat payload)" with the stolen stamp, and devkit accepted the shell's command line as proof of which call ran the dev command.

Root cause: The token's binding read the command lines of the dev process's ancestors, which the caller writes itself, and relaxed the check further for an exec'd dev matched by text and for programs that run no script.

Each stamped call is now bound to one process by a pin:
- where the agent never asks (Claude Code in bypassPermissions, Codex with approval_policy never) and the shell is sh, bash or zsh, the stamp's first action writes the shell's own pid under noclobber into a per-user 0700 folder under $TMPDIR, before the token is exported; a write that finds a pin already there marks the call contested, and a contested call names nobody;
- elsewhere (a permission mode that checks rules, a Codex that asks, fish or nushell) only one plain dev call carries the token, in the variable-list form, and its dev process writes the pin with O_EXCL, naming the call's own process below the agent or below the loop that launches its calls;
- a dev command resolves by the token only at or below the pinned process, whose parent is the agent (or its launcher), which started after the call opened and within its ttl, and whose pid and start time match its first use (pid reuse); a malformed pin fails closed;
- a call whose agent process is not known no longer binds by its session alone: it refuses state changes (caller.token-unpinned) and leaves reads to the ledger's rules;
- where Codex asks, a thread claim takes a lane for a state change only when the lane's own open call is exactly that one dev command, and such a change is audited as flagged;
- when a call ends, its pin is audited: calls.pin-contested, calls.pin-late (born more than 30 s after the call opened), calls.pin-replaced (another inode than its first use saw), and caller.token-unexplained-use (a tech-lead call that runs no dev command had its token used);
- the pin folder is named by a hash of the session id, so a member's stamped command never shows the root thread's id, and strip_token removes the new prefix from every stored text.

The command-line matching (_call_shell, _runs_this, _stamped) and its relaxations (an exec'd dev matched by text, non-script programs skipped) are gone.

Verified: dev test run on 22 files (identity, token, red team, real-process theft on Claude and Codex, Codex launch, gates, coordination, parity): 606 of 606 passed; dev test prove --since HEAD: 28 new tests fail without the change.
the token is bound to the process its call pins, and an unplaced lane call's state change is refused; the guides still described a shell binding and a fallback to the main session

Verified: dev docs check on the four pages: 0 issues, all links resolve
A crew member could plant a dev command in a workflow step, a test or a git hook, and when the tech lead ran dev ci --run, dev test or dev commit, that command inherited the tech lead's call token and acted as the tech lead with no record. Two smaller pin gaps let a call be taken silently: a pin written in advance beside a dangling .contested link, and a pid reused after an interrupted call whose token was never used.

Root cause: devkit's runners passed their own environment, call token and lane marks included, to the project's code (gitx's step env, testx's test env, core.GIT_ENV for git and its hooks); the contested marker was checked with Path.exists, which is False for a dangling link, while the stamp only tried to create the marker; and nothing tied the pin file to the moment its pinned process started.

- identity.runner_env drops DEVKIT_CALL, DEVKIT_FROM_AGENT and DEVKIT_SPEAKER; dev ci --run's steps, dev test's and dev test prove's test commands, and every git command devkit runs (core.GIT_ENV) start with it, so a dev command there names nobody and its state change is refused (caller.no-token).
- Each verified use appends its arguments' hash, whether it changes state, and whether the call's text runs it to .<tid>.uses; when the call ends, state changes its text does not run are audited as caller.token-unlisted-use (flagged, allowed: the tech lead's own scripts do this).
- The stamp moves a pin already there onto the contested name (mv -f replaces a planted link) and checks the marker with os.path.lexists, so a call is contested rather than taken.
- A pin must be born within 20 s after its pinned process started, so a pid given to a newer process is not the call's.
- SECURITY.md says which project code devkit runs without the token and that crew code the tech lead runs by a raw command still acts as the tech lead, recorded in the audit trail.
- Test repairs for the pin form: the member wait route asserts its lane and its token; a member call whose rewrite is dropped is refused and lands nowhere.

Verified: dev test run on 47 identity, runner, git, CI and coordination files: 1500 of 1500 passed; then test_watch_requests, test_acceptance_crew_sessions, test_progress and test_identity_redteam: 270 of 270; dev test prove --since HEAD: 11 new tests fail without the change.
the call token's pin and the runners' tokenless environment added audit actions the reference did not list, and two rows described the older shell binding and a wrong category

Verified: dev docs check on both pages: 0 issues, all links resolve; action names and categories checked against identity.py, hooks.py and audit.py
test fixtures named a real organization and its copy-release step; a neutral name keeps the same cases without naming anyone

Verified: dev test run on the seven files: 193 tests, all passed after the audit test's masked length followed the shorter name
a watch with --timeout 0 ended at once, while 0 meant the default before the limit was derived from the workflows

Root cause: the derived limit made the option default None, and cmd_ci_watch passed any given value through, so 0 became a zero-minute limit instead of falling back as the old 'or 90' did

Verified: new test failed first ([0.0, -5.0] != [None, None]), then dev test run tests/test_ci_watch_limits.py: 9 passed; /usr/bin/python3 3.9 OK
After a reassignment, the old lane's edit of the new owner's file got no hook advice, and dev commit refused its staged files with the empty text "your step's scope ()".

Root cause: hooks._lane_scope_miss skipped empty scope layers, so a crew lane whose only layer is empty (it runs no step, progress.lane_scope) held every path; gitx._lane_refusal printed that empty layer as ()

An empty layer now holds nothing in the edit check. The edit and the commit each say the lane runs no step and how to ask the tech lead for one. The reassignment tests check the hook's advice again.

Verified: python3 -m unittest tests.test_coord_kernel_fixes tests.test_lane_binding tests.test_commit_lanes: 55 tests OK; dev test prove: the 3 reassignment tests and the commit text test fail without the fix
A launch such as "Seraph: review the release" after a finished "review" became a follow-up of it, so "review-27", waiting for the Code reviewer, stayed pending and the lane could not write.

Root cause: progress._bind_step and hooks._launch_naming made a launch a follow-up whenever a done step scored best, even when its description also named a step waiting for its member

A launch is a follow-up only when it names none of the steps waiting for its member; otherwise it is scored by the waiting steps alone and claims as usual, and a tie among them gets the tech lead the dev progress assign line. The model hunt gains a launch that names a finished step and a word of a waiting one.

Verified: python3 -m unittest tests.test_coord_kernel_fixes tests.test_launch_naming tests.test_hooks_launch tests.test_coord_scenarios tests.test_coord_model: 38 tests OK; the new tests and the hunt's rule fail without the fix
An OSError while the call token was stamped made the PreToolUse hook raise, so the member's call ran without its lane route, its advice and its lessons.

Root cause: hooks._pre_tool called _stamped_token outside any try, and each progress.call_note and call_entry inside it can raise

A failure while stamping now costs the call its token only: it is logged and audited as calls.token-skipped with the reason, and the call still goes out with its route.

Verified: python3 -m unittest tests.test_pre_tool_hook.TokenStampFailureTests tests.test_identity_token tests.test_codex_identity_token: 44 tests OK; dev test prove: the new test fails without the fix
dev crew delegate set the step running in a free lane with no history entry, so the coordination check reported that its last history entry said pending.

Root cause: dispatch.delegate changed the step's owner and state itself instead of giving it an intent for the lane and letting coord.claim start it

The delegated step gets an intent for its member's working lane, and _claim_free_lanes starts it there when the lane is free, or once its step closes. The delegation's own notice is the lane's only one: the claim sends none for a step its caller tells the lane about.

Verified: python3 -m unittest tests.test_crew_delegate tests.test_dispatch tests.test_dispatch_busy_lane tests.test_lane_binding tests.test_plan_dag tests.test_raci: 99 tests OK; dev test prove: the new test fails without the fix
A stop the crew gates let through sent the tech lead two notices at once: what the gates still found, and which reviews of that stop count for nothing.

Root cause: hooks._tell_lead_findings and progress._tell_uncounted each posted their own notice for the same lane's end

The hook words the findings (hooks._findings_told) and passes them to the lane's end as a parameter, which posts one notice with both. A stop that meets a busy session lock keeps them in its pending file, like its stop time.

Verified: python3 -m unittest tests.test_coord_kernel_fixes tests.test_hooks_gate_findings tests.test_hook_capture tests.test_approvals_token: 28 tests OK; dev test run of the 53 stop-path test files: 1154 passed, 1 skipped
the tech lead's notice said such a launch takes none of the member's steps, while the claim rule gives its lane the oldest step waiting for that member

Root cause: the notice was written before claims went first-in first-out, and no test checked what it says the launch takes

Verified: dev test run tests/test_hooks_launch.py tests/test_launch_naming.py: 9 passed
a stop under the conversation's newer session id, whose run does not list the lane, told the tech lead that 'a member stopped'

Root cause: the single gates notice took the member's name only from the run's lane record, and the earlier fallback to the stop's agent type went with the second notice

Verified: new test failed first ('a member stopped'), then dev test run of the coordination fix, lane binding and kernel tests: 45 passed; /usr/bin/python3 3.9 OK
the guide said a launch naming a done step takes no step and that an unassigned lane's edit gets the out-of-scope advice; both changed with the latest fixes

Verified: dev docs check docs/crew.md: 0 issues, all links resolve
crew coordination redesigned and the call token pinned to its process, with the CI step and watch limits taken from the workflows; the changelog entry and the version files for the release

Verified: dev docs check CHANGELOG.md: 0 issues; dev test run of the consistency tests and the 5 files that read the version files: 30 and 91 passed
@ancongui
ancongui merged commit b72ab90 into main Nov 20, 2026
5 checks passed
@ancongui
ancongui deleted the fix/crew-coordination-26.11.27 branch November 20, 2026 12:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant