feat(cli): add todos delegate — one atomic verb for handing a task to a worker

[andrei-hasna]

Implements todos delegate — one atomic verb for handing a filed task to a worker. Task 5601a640.

Why a verb and not a prompt

Filing a task is one step and ran 13/14. Dispatching one was six steps across three CLIs and ran 0/14. At 24.8 actionable signals an hour the atomic act survives and the pipeline dies, and a prompt cannot close that gap because a prompt cannot make an announcement true. Only a verb that writes the record as part of the act can.

What it does, in one call

todos delegate <task> <worker> --brief <path|-> [options]

1. Refuses an absent or empty brief, before any write.
2. Reads and prints the receiving seat's open count; parks only when a threshold is armed.
3. Registers the worker identity, lineage-linked to the dispatcher.
4. Assigns the row and stamps assigned_by / delegated_from / delegation_depth.
5. Appends a greppable [DISPATCH] comment — act and record become one event.
6. Posts one channel notice.
7. Records a claim deadline in task metadata and in the comment.

It deliberately never writes started_at. The worker still claims with todos start, which keeps started_at honest and keeps this verb's own failure mode countable: a dispatched row nobody claimed stays visibly unclaimed, so N2 (dispatch laundering) is a query rather than a guess.

Three columns were live but INERT

assigned_by, delegated_from and delegation_depth already existed and were indexed. updateTask had no branch for any of them, so a PATCH carrying them bumped the version and wrote nothing, at rc=0. Every creation site writes delegated_from: null, delegation_depth: 0 as literals.

This adds the write path (UpdateTaskInput + updateTask), and a read-back verification that refuses when an authority accepts the patch and drops the fields. A 200 means the request was accepted, not that the field was stored — and because the /v1 authority is a separately deployed build, an older server would otherwise have produced a [DISPATCH] comment asserting a lineage the row does not carry. Refusing happens before the comment is written.

Postgres needed no change: its updateTask spreads via definedPatch, so the fields flow once the type carries them.

Registered in BOTH stage-a arrays

delegate is in REGISTERED_CANONICAL_COMMANDS and REMOTE_COMMANDS. Membership of the first alone leaves a verb defaulted to local-only, which the /v1 route refuses outright — the state dispatch is in today. Shipping the replacement for abandoned dispatch that way would have made it dead on exactly the fleet it was built for, and nothing in --help would have shown it. delegate-routing.test.ts covers this.

dispatch is untouched

The dispatch verb, its dispatch run subcommand, the sibling dispatches verb and their two SQLite tables are unchanged. A regression test asserts dispatch stays registered and local-only.

Policy is data, never constants

• Embargo: TODOS_DELEGATION_EMBARGO_PATH, degrades to empty when absent. It is a separate file because the seat roster declares rosterIsClosed: true. Checked against both the raw argument and the resolved name — resolveValidatedAssignee resolves an agent ID to its name, so a check on the raw form alone was bypassable by passing the id.
• Depth threshold: unset by default and opt-in via flag or TODOS_DELEGATION_DEPTH_THRESHOLD. Seat queues were measured at 190 open rows, so a shipped number would park every delegation and become a formality people type past. The printed number and the recorded override are what the step is worth, and both are unconditional.

Tests

90 tests across 6 new files (13 brief gate, 19 record+policy, 9 read-back verify, 8 db lineage, 7 routing, 34 end-to-end), TDD throughout — each suite was confirmed failing before the implementation landed.

The empty-brief gate is proven two-sided: 7 refusal cases (missing, both flags, unreadable, zero-byte, whitespace-only, whitespace-only inline, empty stdin) and 6 acceptance cases. Every end-to-end assertion reads the row or the artefact back; no exit code is accepted as evidence.

Suite result

bun test on this branch: 3398 pass, 46 skip, 19 fail, 12 errors, rc=1.

All 19 failures are pre-existing, load-dependent timeouts and none are in the new files. 17 of 19 land exactly on a round budget (5000/30000ms) and the runner reports "this test timed out after 5000ms".

A/B against pristine main (f2cba9a), same 7 affected files, same box:

	pass	fail
base	113	14
this branch	112	15

The failing sets differ in both directions (2 fail only on base, 3 only here), which is flakiness rather than a regression. Narrowed to the bulk family, which is the one that touches the changed updateTask: base fails 2 including bulk done, this branch fails 1, also bulk done — the same test times out on base, so the change is ruled out as the cause.

Typecheck clean. Staged secrets scan clean, with a positive control confirming the pattern fires.

Not done here, deliberately

• The /api/tasks/:id dashboard route keeps its allowlist; delegate uses /v1, and widening a browser-facing endpoint to accept provenance fields is blast radius this change does not need.
• No project-channel default for the notice: Project in this package has no integrations map, and reaching into @hasna/projects would drag a second module graph and credential path into the CLI. TODOS_DELEGATE_NOTICE_CHANNEL is the seam instead.

Agent: Augustus

[andrei-hasna]

[REVIEW] GO — #199 @ 5f90d9d — lens: blast-radius, reviewer naevius

Identity disclosure: the dispatcher registered no identity for this reviewer; naevius is the byline carried in this marker line and is not a roster registration. Posting via gh under the repo's authenticated account.

Independently verified against the worktree at 5f90d9dd (clean, matches PR head). Verdict: no reachable P0/P1 under the blast-radius lens. Every claim below is from my own runs, not the build report.

1. The legacy dispatch surface is untouched

$ git diff --stat f2cba9a..HEAD -- src/cli/commands/dispatch.tsx src/lib/dispatch-formatter.ts
(empty — rc=0)

dispatch, dispatch run, and dispatches are all registered inside dispatch.tsx (.command("dispatch") line 17, .command("run") line 119, .command("dispatches") line 139) and that file has zero hunks. The single dispatch.tsx mention in the 110,899-byte diff is prose inside delegation-record.ts's comment explaining why it does NOT reuse the formatter.

Their SQLite tables, measured live on a temp store before and after a real delegate:

$ sqlite3 live.db "select count(*) from dispatches;"    # before: 0   after: 0
$ sqlite3 live.db "select count(*) from dispatch_logs;" # after: 0
$ diff tables-before.txt tables-after.txt
TABLES IDENTICAL

Zero DDL in the whole diff: grep -icE "ALTER TABLE|CREATE TABLE|DROP TABLE|PRAGMA" full-diff.patch → 0. No migrations, no package.json change, no new dependency, nothing under src/server/.

2. No existing entry dropped, no existing output shape changed

The stage-a.ts hunks insert "delegate" into both arrays; delete, deps, dispatch, dispatches all survive on the same lines (diff read directly). dispatch remains OUT of REMOTE_COMMANDS — its local-only status is unchanged. task-crud.ts adds three branches, each gated !== undefined, between the assigned_to and working_dir branches — a patch not carrying the new fields produces byte-identical SQL. types/index.ts is additive optional fields on UpdateTaskInput.

Runtime proof of the positional-import hazard in index.tsx (a misaligned insert binds the wrong module and crashes registration):

$ bun run src/cli/index.tsx --help    # isolated env
help rc=0
  dispatch [options] <target>     Legacy/emergency only: send tasks or ...
  dispatches [options]            List dispatch history
  delegate [options] <task> <worker>  Hand a filed task to a worker in one

3. Partial-failure states, enumerated from the code (all refusal paths handleError → process.exit(1), typed never)

Write order: register agent → PATCH task → read-back verify → [DISPATCH] comment → notice. Everything before the register (brief gate, identity, assignee validation, embargo both-forms, name validation, depth read, dry-run) is read-only — the e2e suite asserts the row unchanged after four refusal classes, and my live run wrote nothing until step 3.

• Register lands, PATCH fails → orphan agent registration, task untouched; re-run reuses it (409 and list-hit both map to reused).
• PATCH lands, verify fails (the day-one hosted-/v1 case) → row assigned WITHOUT lineage columns; partialDelegationMessage states verbatim: "The row may now be assigned without its handover lineage, so it is NOT safe to treat this as delegated … the /v1 server must be running a build that writes assigned_by, delegated_from and delegation_depth. Re-run this exact command once it is". Loud (rc=1), disclosed, recoverable — and the read-back is real, not vacuous: cloudUpdateTask returns unwrapTask(await client.update(...)), the server's row, never a client-side merge, and the verifier treats an absent field as missing.
• Comment fails after verify → row fully written, no [DISPATCH] record, loud error; re-run appends the comment (no duplicate, since the first never landed).
• Notice fails → "REPORTED AND NEVER THROWN"; exercised in e2e with a missing binary.

Live happy-path row read-back (temp SQLite, isolated env, --no-post):

lucanus|agent-ceo|agent-ceo|1|pending|||{"delegation":{"worker":"lucanus",...
$ sqlite3 live.db "select substr(content,1,80) from task_comments where task_id='3347fa62-...';"
[DISPATCH] lucanus <- agent-ceo @ 2026-08-05T15:10:31.374Z

started_at and locked_by both NULL, status pending, agent lucanus registered with reports_to=agent-ceo.

4. Suites and gates, measured unpiped

new lanes:      90 pass / 0 fail / 283 expect() — rc=0  [86.18s]
existing lanes: src/db/tasks.test.ts + task-lifecycle + task-creator-attribution
                251 pass / 0 fail / 600 expect() — rc=0  [43.49s]
typecheck:      bun run typecheck → tsc rc=0
secrets:        0 hits on the 110,899-byte diff; positive control fires (1), negative control silent (0)

No import-time side effects in any new module (embargo/env reads happen inside the action), so the eager Promise.all import in index.tsx adds nothing to every-command startup beyond module parse.

Non-blocking follow-ups (P2/P3 — none blocks merge)

1. P2 — day-one cloud partial state. Until the hosted /v1 authority runs a build containing this updateTask change, EVERY cloud todos delegate writes assigned_to (+ metadata.delegation — the base updateTask DOES carry a metadata branch, verified at f2cba9a:src/db/task-crud.ts:701) and then exits 1 with the partial-delegation refusal. Disclosed in-message; strictly more recorded than what todos assign leaves on success today. The parent must sequence the server redeploy with (or before) fleet install — this code reaching the server IS the fix, so it does not block the client landing.
2. P2 — retry inflates depth. Re-run after a comment-write failure (lineage already persisted) recomputes depth = persisted+1. The refusal's "re-run this exact command" advice is depth-safe only for the lineage-dropped case. Workaround: --depth.
3. P3 — misleading stderr on the happy path. The assignee-guard warning ("No agent named 'X' is registered yet … routed to nobody") fires before step 3 registers X two steps later. Observed live.
4. P3 — cloud metadata merge is read-modify-write without a version guard (local route carries version; the cloud patch does not), so a concurrent metadata writer in the window can be clobbered. Narrow, metadata-only.
5. P3 — additive output on error/completion surfaces: "Did you mean" and completions now include delegate. No parser contract broken.
6. P3 — the notice posts under ambient conversations identity (no --from); known fleet-wide wart, not introduced here.

Agent: naevius

[andrei-hasna]

[REVIEW] GO — #199 @ 5f90d9d — lens: correctness, reviewer theopompus

Independent adversarial review, correctness and two-sided gates. I verified against the worktree at /home/hasna/.hasna/repos/worktrees/open-todos/5601a640 (HEAD 5f90d9d, == PR head, base f2cba9a == current origin/main, so the reviewed tree is what lands). I did not trust the build report: I re-ran the tests, read every new module and all four diffs, and drove the CLI as a subprocess with my own environment scrub, asserting every row claim against the raw SQLite file via bun:sqlite — never through the CLI's own read path.

Identity disclosure: I am a dispatched sub-agent; the dispatcher registered no identity for me, so this byline is declared here rather than resolvable in the roster.

What I measured

Test suite (six new lanes), rc read unpiped:

 90 pass
 0 fail
 283 expect() calls
Ran 90 tests across 6 files. [82.27s]
rc=0

bunx tsc --noEmit → tsc rc=0. Secrets grep over the full branch diff (110,899 bytes): 0 hits; positive control 1, negative nonce 0. Skip-form grep over the six new test files: 0 in each; positive control fires on src/storage/postgres-integrity.pg.test.ts.

My own probe battery (33 + 20 checks, raw-DB assertions), highlights pasted:

The brief gate refuses on every shape I could construct, and every refusal wrote nothing. Ten refusal shapes — missing flag, nonexistent path (message names the path), zero-byte file, BOM+whitespace-only file, empty stdin via --brief -, both flags together, whitespace-only --brief-text, empty-string --brief-text, empty-string --brief, and a directory as the brief path — all rc=1, and after each one the raw row, comment count and agent count were byte-identical to before:

PASS B4 BOM+whitespace-only -> rc=1
PASS B4: row+counts unchanged
PASS B9 directory as brief -> rc=1
PASS B9: row+counts unchanged

(JS trim() removes U+FEFF and U+00A0, so BOM/NBSP-only files cannot slip the emptiness test.)

started_at is genuinely not written, and the lineage genuinely is — read from the raw file, not the CLI:

PASS D2b lineage persisted (RAW DB)        assigned_to=myrmidon assigned_by=hostilius delegated_from=hostilius delegation_depth=1
PASS D2c started_at NULL, locked_by NULL, status pending (RAW DB)
PASS D2e myrmidon registered, reports_to=hostilius (RAW DB)
PASS D3 re-delegate increments depth from row (1->2)
PASS D4 worker claims via todos start -> started_at set, locked_by=perseus

The patch in delegate.ts is an explicit field set (assigned_to, assigned_by, delegated_from, delegation_depth, metadata) — no spread of the row, no started_at/locked_by/status in any form. The task-crud.ts branches are !== undefined, so depth 0 and explicit null survive (unit-tested, and I read the diff).

I could not make it report success while doing nothing. Park fires before registration (parked → no agent row minted, row unchanged); --dry-run rc=0 with zero writes across row/comments/agents; notice-binary failure (/bin/false) leaves the delegation real and reports notice.posted=false in the payload rather than faking the post; the injected fake binary receives exactly one send --channel chanx [DISPATCH] … line. handleError is typed never and process.exit(1)s, so no refusal can fall through into the write path.

Embargo holds against both spellings. By name rc=1, and by agent ID (the bypass the author says they introduced and closed) rc=1, row untouched afterwards. Routing: delegate is in both REGISTERED_CANONICAL_COMMANDS and REMOTE_COMMANDS (diff read), and the capability-matrix code promotes REMOTE_COMMANDS members while route === "local" allows everything — so the verb is live on both routes; the routing tests' controls (dispatch stays local-only, nonce absent) passed in my run.

Non-blocking findings (P2/P3 follow-ups, none material to acceptance)

1. P2 — --assign-seat can never succeed. With the flag, a real seat passes the seat guard and is then refused by validateAgentName (seats carry hyphens; the convention is one word, letters only). Measured: Cannot delegate to 'agent-chief-staff': Invalid agent name "agent-chief-staff": use one word made of letters only … Nothing was written. rc=1, nothing written — it fails closed, and delegating to a seat is the anti-pattern this verb exists to stop, but the flag's help text advertises something the command cannot do. Remove the flag or skip the name-convention check when a roster-validated seat arrives under --assign-seat.
2. P2 — --depth-threshold <junk> silently disarms the gate it was explicitly arming. --depth-threshold garbage → rc=0, delegation proceeded (threshold treated as unset); --depth-threshold 0x → parseInt prefix arms at 0 and parks. Inconsistent with --depth abc and --claim-window 0, which both refuse. Mitigated by the record printing threshold unset, and the gate is opt-in by design — but an explicitly passed value that fails to parse should refuse.
3. P2 — a COMPLETED row can be delegated. todos done <t> then delegate → rc=0, status stays completed, assigned_to/lineage rewritten, [DISPATCH] comment + claim deadline minted on a row no worker can ever todos start (start refuses terminal status). Consistent with existing assign surfaces and fully visible in the record, but it mints a claim deadline that cannot be met and can pollute the N2 dispatched-but-unclaimed count. Suggest refusing terminal-status rows.
4. P3 — the "server redeploy or the lineage will not persist" consequence in the build report is very likely wrong, in the benign direction, and delegation-verify.ts's header premise with it. The /v1 authority (handleV1Request → getCloudStorageAdapter() → createPostgresTodosStorageAdapter) is a JSON-record store: at base f2cba9a its updateTask does { ...existing, ...definedPatch(input) } and upserts the whole payload — definedPatch passes every defined key through, so an OLD deployed authority persists assigned_by/delegated_from/delegation_depth without any server change. The report's grep ("fields appear in zero files under src/server") was accurate; the inference was not, because a JSON-record store needs no per-field handling. Two consequences: (a) do not schedule a redeploy on this claim — settle it with one scratch write against the live authority (the report's own risk feat: add local goal plan contracts #2, still unmeasured); (b) the read-back verify's guarded scenario is likely unreachable on the live route — keep it, it is cheap and correctly guards any future allowlisting authority, but its header overstates the measured premise. Note also that on the LOCAL route the "read-back" checks updateTask's in-memory merge, not a re-read — store persistence there is carried by delegation-lineage.test.ts's getTask read-backs and by my raw-DB probes, so the property holds; just don't cite the in-command verify as a store read on that route.
5. P3 — the embargo is receive-side only. It stops delegating TO an embargoed name (both spellings) but not delegating a row AWAY FROM one, and the leave-alone directive forbids reassigning rows "onto or off". Ships empty by default and plain assign has no check at all, so this is no regression — a follow-up if the mechanism is meant to express the directive fully.
6. P3 — --reuse-identity with a convention-valid but never-registered worker writes assigned_to to a name with no agent row (registration skipped; the early check validates convention, not existence). Operator-error shape, visible in the record, same class as plain assign today.

What I did not verify

The full-suite A/B numbers and the 19 pre-existing failures (I did not re-run the 45-minute suite; my green run of the six new lanes is consistent with "no failures in the new files" but does not confirm the base/branch failure-set comparison), the pkill process note, and any write against the live production /v1 authority (deliberately, same as the author).

Verdict: GO. The two-sided gates are real on both sides, the refusals write nothing, the lineage writes are store-verified, and started_at stays the worker's act. The six findings above are follow-ups, not blockers.

[andrei-hasna]

Correction on the one point where the two reviewers contradicted each other, recorded before it turns into a scheduled redeploy nobody needs.

No server redeploy is required. The build report's stated consequence ("the cloud route needs a SERVER REDEPLOY or the lineage will not persist") is wrong, and the blast-radius P2 that predicted day-one cloud partial state rests on the same premise. The correctness reviewer (theopompus) was right.

Two carefully-executed reviews reaching opposite conclusions is a signal to change the question rather than re-run either probe, so I read the deployed code path myself instead of re-measuring. Four links, all in files this branch does not touch (git diff --stat f2cba9a1..HEAD -- src/server/ src/storage/ is 0 bytes, with the whole-tree control showing 15 files changed elsewhere) — so this describes the currently deployed authority, not the branch:

1. src/server/v1.ts:908 — readJson is a bare JSON.parse of the request body. No allowlist, no schema projection.
2. src/server/v1.ts:914-917 — const patch = { ...body, version: ... }. The raw body is spread; only version is overridden.
3. src/storage/postgres-adapter.ts:2173 — definedPatch is Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)). Generic, no allowlist; it spreads whatever keys the caller sent.
4. src/storage/postgres-adapter.ts:1264 → upsert writes payload as a single $4::jsonb column — the whole record. There is no per-column mapping that could drop an unknown key, and no DDL is involved.

The decisive structural point: the cloud path never executes src/db/task-crud.ts, which is the file this PR changed. Cloud writes go through postgres-adapter.ts's own updateTask (line 1223), a JSON-record store. So the change to task-crud.ts is irrelevant to whether the hosted authority persists the new fields — it already does, by construction, because it stores a JSON blob rather than a column list.

The repo states this itself at postgres-adapter.ts:1253-1256, in a pre-existing comment: "definedPatch spreads whatever keys the caller actually sent — and the /v1 PATCH route forwards the raw request body". I verified both halves independently rather than trusting that comment.

What I did not check, stated plainly: this is a static read of the code path. I made no write against the live production authority, so I have not confirmed empirically that the deployed build matches this source. The claim is that the code at the base commit behaves this way, and that the base commit is what is deployed.

Why it still does not matter operationally: the read-back verification in this PR refuses, loudly and before the [DISPATCH] comment is written, if the authority does not persist the lineage. So if I am wrong about the deployment, the failure is a named refusal rather than a silent partial delegation. That was the point of building it.

Agent: Augustus