Merge pull request #730 from corbitsdev/cl-7265-make-resume_agent-start-retained-turns-and-delete

Start retained worker turns from resume_agent immediately

Author: TheGreatAxios

CHANGELOG.md

@@ -19,6 +19,10 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
   `advance_workflow` is gone. Already-complete and not-current ids are
   acknowledged without advancing. The unused `autoAdvance` workflow field is
   removed.
+- `resume_agent(target, message)` starts the next turn on a retained completed
+  or interrupted worker and returns immediately. `wait_agents` collects the
+  reply. `send_input` steers only an in-flight running turn. Closed workers
+  stay closed.
 
 ### Fixed
 

docs/ARCHITECTURE.md

@@ -130,7 +130,7 @@ The ChatDirector counts consecutive assistant turns that contain tool calls and
 
 #### Sub-agent stall management
 
-`SubAgentDirector` tracks `lastActivityAt`, updated on every real `inference.done` and `tool.done`. Directors are pure `decide(event, ...)` functions with no timer of their own and the reactor has no proactive "idle" event, so a genuinely silent leaf (e.g. parked on a long-running background command with nothing else to do) produces no event for the director to react to. `runSubAgent` (`src/subagent/index.ts`) arms an external interval, at `subAgentStallTimeoutMs`, that pings the same content-less continuation channel the compaction governor uses to re-enter an idle reactor (`requestContinuation`). The director only acts on a ping if the elapsed time since `lastActivityAt` has crossed the timeout — a ping delivered while a tool call is still executing simply queues until that cycle finishes, so "no pending harness-tracked work" falls out of when the check can run at all rather than needing separate bookkeeping. The first stall past the timeout gets one continuation nudge (asking the leaf to check on the background work or report status); a second **consecutive** stall (no activity since that nudge) escalates to the existing salvage path, returning a `stalled` `forcedStopReport` with the same structured shape (summary/findings/blockers) as `turn-budget` and `cancelled`. Any real activity between pings resets the streak, so a leaf that is genuinely working through a slow single turn is never penalized. After the leaf has already replied with a terminal report (complete envelope or salvage), further empty continuations — idle-compact meter sync or stall pings — return `wait` instead of falling through to `DefaultDirector.infer`; only a non-empty parent message (`followup_task` / `send_input`) re-opens the brief.
+`SubAgentDirector` tracks `lastActivityAt`, updated on every real `inference.done` and `tool.done`. Directors are pure `decide(event, ...)` functions with no timer of their own and the reactor has no proactive "idle" event, so a genuinely silent leaf (e.g. parked on a long-running background command with nothing else to do) produces no event for the director to react to. `runSubAgent` (`src/subagent/index.ts`) arms an external interval, at `subAgentStallTimeoutMs`, that pings the same content-less continuation channel the compaction governor uses to re-enter an idle reactor (`requestContinuation`). The director only acts on a ping if the elapsed time since `lastActivityAt` has crossed the timeout — a ping delivered while a tool call is still executing simply queues until that cycle finishes, so "no pending harness-tracked work" falls out of when the check can run at all rather than needing separate bookkeeping. The first stall past the timeout gets one continuation nudge (asking the leaf to check on the background work or report status); a second **consecutive** stall (no activity since that nudge) escalates to the existing salvage path, returning a `stalled` `forcedStopReport` with the same structured shape (summary/findings/blockers) as `turn-budget` and `cancelled`. Any real activity between pings resets the streak, so a leaf that is genuinely working through a slow single turn is never penalized. After the leaf has already replied with a terminal report (complete envelope or salvage), further empty continuations — idle-compact meter sync or stall pings — return `wait` instead of falling through to `DefaultDirector.infer`; only a non-empty parent message (`resume_agent` / `send_input`) re-opens the brief.
 
 **Intervention log**: every stop and nudge is appended as one JSONL record to `interventions.jsonl` in the firing leaf's trace dir (`src/subagent/intervention-log.ts`), carrying the trigger's measured value beside the threshold it crossed, the provider/model/family it fired on, and the run state at that moment (turns used vs budget, tool calls, read/edit counts). A refused parent re-dispatch is recorded on the parent side, where no leaf run exists to record it. The parent also appends one `outcome` record per completed dispatch — the salvage kind `classifyBriefSalvage` assigned, or a clean-complete marker, plus the dispatch count — so the log carries dispatch outcomes as well as interventions, and a stop record can later be read alongside what the dispatch it touched actually produced. Writes are fire-and-forget and swallow their own errors — a diagnostic must not be able to fail a run. `scripts/intervention-forensics.ts` aggregates these across local sessions: per-intervention counts by model family, the measured-value distribution against the threshold, two context columns (stops that fired on runs which had already edited files; stops that fired before half the turn budget was spent — neither is a measured false-positive rate, since either is equally consistent with a correct stop or a wrong one), and outcome counts by kind. This exists because every threshold in this tree was set by judgment and four of those judgments were later reverted — a threshold change is expected to cite this data (CL-6938).
 
@@ -218,8 +218,8 @@ Every director package carries a required `tier: SubagentTier` field (`src/agent
 
 Enforcement is runtime code at the existing tool-mount point, not prompt wording — this is the fix for four prior mechanisms (`writePaths`, `report.requiredSections`, a `--config` comment, the thrash matcher) that were documented-as-enforced while enforcing nothing:
 
-- **Mount-time gate — live today, and fails closed.** `task-tool.ts` resolves the caller's tier at dispatch time — a closed director's `DirectorPackage.tier` — and forwards it as `RunSubAgentParams.orchestratorTier`. `runSubAgent` (`src/subagent/run.ts`) then calls `assertTierMayMountFleetVerb(tier, toolName)` (`src/subagent/authority.ts`) before installing fleet verbs, treating a **missing** `orchestratorTier` as `"leaf"` — deny, not skip. This is the case that matters most: a project-local or plugin `AgentProfile` with `orchestrator: true` is outside the closed director set and is **not** trusted with fleet verbs just because `orchestrator: true` is set — there is no profile-level opt-in today, so the mount always throws `FleetAuthorityError` for a profile-sourced orchestrator. `FLEET_VERBS` in `authority.ts` names the live verbs (`task`, `spawn_agent`, `wait_agents`, `list_agents`, `send_input`, `interrupt_agent`, `close_agent`, `resume_agent`, `followup_task`, `read_agent_trace`, `search_agents`) so every mount site inherits the same gate. `list_agents` is the non-blocking mailbox-scoped list of this install's own `spawn_agent` workers (same scope as `wait_agents`); nested orchestrators may mount it. Fleet discovery (`search_agents`) remains Tier 1 only.
-- **Subtree authority — wired for addressing verbs.** `assertCanTargetAgent(actor, targetId, nodes)` implements the "root owns its tree; a child manages only its own descendants" rule over the `{id, parentSessionId}` shape `SubAgentSessionStore` already tracks. Production call sites: `read_agent_trace`, `send_input`, `interrupt_agent`, `close_agent`, `resume_agent`, and `followup_task`. Nested mounts pass `{actorId, tier, getNodes}` from `run.ts`; a missing `actorId` fails closed. Tier-1 primary omits authority and stays unrestricted. `spawn_agent` records `parentSessionId` on nested workers so `close_agent`'s descendant walk can see them. `wait_agents` with omitted targets waits only on that caller's own `fleetRecords`, not every running session in the shared store. `list_agents` reports that same mailbox without blocking. `interrupt_agent` / `send_input` with `interrupt:true` terminalize the wait mailbox immediately; the soft-interrupt wait path collects so a later followup cannot resurrect an already-observed interrupt. `close_agent` also terminalizes the wait mailbox before teardown.
+- **Mount-time gate — live today, and fails closed.** `task-tool.ts` resolves the caller's tier at dispatch time — a closed director's `DirectorPackage.tier` — and forwards it as `RunSubAgentParams.orchestratorTier`. `runSubAgent` (`src/subagent/run.ts`) then calls `assertTierMayMountFleetVerb(tier, toolName)` (`src/subagent/authority.ts`) before installing fleet verbs, treating a **missing** `orchestratorTier` as `"leaf"` — deny, not skip. This is the case that matters most: a project-local or plugin `AgentProfile` with `orchestrator: true` is outside the closed director set and is **not** trusted with fleet verbs just because `orchestrator: true` is set — there is no profile-level opt-in today, so the mount always throws `FleetAuthorityError` for a profile-sourced orchestrator. `FLEET_VERBS` in `authority.ts` names the live verbs (`task`, `spawn_agent`, `wait_agents`, `list_agents`, `send_input`, `interrupt_agent`, `close_agent`, `resume_agent`, `read_agent_trace`, `search_agents`) so every mount site inherits the same gate. `list_agents` is the non-blocking mailbox-scoped list of this install's own `spawn_agent` workers (same scope as `wait_agents`); nested orchestrators may mount it. Fleet discovery (`search_agents`) remains Tier 1 only.
+- **Subtree authority — wired for addressing verbs.** `assertCanTargetAgent(actor, targetId, nodes)` implements the "root owns its tree; a child manages only its own descendants" rule over the `{id, parentSessionId}` shape `SubAgentSessionStore` already tracks. Production call sites: `read_agent_trace`, `send_input`, `interrupt_agent`, `close_agent`, and `resume_agent`. Nested mounts pass `{actorId, tier, getNodes}` from `run.ts`; a missing `actorId` fails closed. Tier-1 primary omits authority and stays unrestricted. `spawn_agent` records `parentSessionId` on nested workers so `close_agent`'s descendant walk can see them. `wait_agents` with omitted targets waits only on that caller's own `fleetRecords`, not every running session in the shared store. `list_agents` reports that same mailbox without blocking. `interrupt_agent` / `send_input` with `interrupt:true` terminalize the wait mailbox immediately; the soft-interrupt wait path collects so a later followup cannot resurrect an already-observed interrupt. `close_agent` also terminalizes the wait mailbox before teardown.
 - `task()` remains the deprecated fused spawn+wait fallback. `spawn_agent` + `wait_agents` is the supported parallel path. The tier check still gates which packages may mount any fleet verb.
 
 #### Closed director fleet (`src/agent/directors/`)

src/agent/fleet-verbs-mount.test.ts

@@ -17,7 +17,6 @@ const FLEET_VERBS = [
   "close_agent",
   "resume_agent",
   "interrupt_agent",
-  "followup_task",
   "send_input",
 ] as const;
 

src/agent/tool-search.test.ts

@@ -92,7 +92,6 @@ describe("createToolIndex", () => {
       "close_agent",
       "resume_agent",
       "interrupt_agent",
-      "followup_task",
       "send_input",
     ] as const) {
       expect(CORE_TOOL_NAMES).toContain(name);
@@ -243,7 +242,6 @@ describe("advertisedTools", () => {
       "close_agent",
       "resume_agent",
       "interrupt_agent",
-      "followup_task",
       "send_input",
     ] as const) {
       expect(prefix).toContain(name);

src/agent/tool-search.ts

@@ -49,7 +49,6 @@ export const CORE_TOOL_NAMES: readonly string[] = [
   "close_agent",
   "resume_agent",
   "interrupt_agent",
-  "followup_task",
   "send_input",
 ];
 
@@ -62,7 +61,6 @@ const ORCHESTRATOR_ONLY_TOOL_NAMES: readonly string[] = [
   "close_agent",
   "resume_agent",
   "interrupt_agent",
-  "followup_task",
   "send_input",
 ];
 

src/agent/tools.ts

@@ -51,7 +51,6 @@ import {
   createCloseAgentTool,
   createResumeAgentTool,
   createInterruptAgentTool,
-  createFollowupTaskTool,
   createSendInputTool,
 } from "../subagent/lifecycle-tools.js";
 import { parseManageTasksArgs } from "./tasks.js";
@@ -398,9 +397,8 @@ export async function createAgentToolset(args: AgentToolsetArgs): Promise<AgentT
         createWaitAgentsTool({ sessions: fleetSessions, fleetRecords }),
         createListAgentsTool({ sessions: fleetSessions, fleetRecords }),
         createCloseAgentTool({ sessions: fleetSessions, fleetRecords }),
-        createResumeAgentTool({ sessions: fleetSessions }),
+        createResumeAgentTool({ sessions: fleetSessions, fleetRecords }),
         createInterruptAgentTool({ sessions: fleetSessions, fleetRecords }),
-        createFollowupTaskTool({ sessions: fleetSessions }),
         createSendInputTool({ sessions: fleetSessions, fleetRecords }),
       );
     }

src/subagent/agent-fleet.test.ts

@@ -211,7 +211,7 @@ describe("spawn_agent + wait_agents", () => {
     // the store itself had already evicted and released the earliest
     // session, because a retained session shared the 20-item display cap
     // with every other finished session — exactly the shipped defect this
-    // ticket fixes (resume_agent/followup_task failed with a bare
+    // ticket fixes (resume_agent failed with a bare
     // "not_found" past 20 spawned workers, blaming the caller for nothing).
     // Open retained sessions now have their own cap (`maxRetained`, default
     // 50), so 25 of them all stay resumable; fleetRecords/wait_agents is

src/subagent/agent-fleet.ts

@@ -704,7 +704,7 @@ export function createSpawnAgentTool(deps: AgentFleetDeps): AgentTool {
         // store a bounded close for close_agent to call later.
         // Worktree cleanup is deferred until that close when the session
         // stays alive for followup (agentRetained / interrupt keep-alive) —
-        // matching run.ts's persisting gate so followup_task does not hit a
+        // matching run.ts's persisting gate so resume_agent does not hit a
         // removed cwd.
         persist: deps.persist !== false,
         onAgentReady: ({ close, interrupt, followup, deliver }) => {
@@ -802,7 +802,7 @@ interface WaitAgentsDeps {
 function isSoftInterrupted(
   session: ReturnType<SubAgentSessionStore["get"]>,
 ): session is NonNullable<ReturnType<SubAgentSessionStore["get"]>> {
-  // interrupt_agent keeps strip status "running" so followup_task can reuse
+  // interrupt_agent keeps strip status "running" so resume_agent can reuse
   // the session. cancel() also sets lifecycleStatus "interrupted" but flips
   // status to "cancelled" — that path still owes wait_agents a salvage
   // report via fleetRecords, so it is not wait-terminal on its own.

src/subagent/authority.test.ts

@@ -14,11 +14,11 @@ describe("assertTierMayMountFleetVerb", () => {
     // The reusable-session verbs are gated the same way.
     expect(() => assertTierMayMountFleetVerb("leaf", "close_agent")).toThrow(FleetAuthorityError);
     expect(() => assertTierMayMountFleetVerb("leaf", "resume_agent")).toThrow(FleetAuthorityError);
-    // Interrupt_agent / followup_task are gated the same way.
+    // Interrupt_agent / send_input are gated the same way.
     expect(() => assertTierMayMountFleetVerb("leaf", "interrupt_agent")).toThrow(
       FleetAuthorityError,
     );
-    expect(() => assertTierMayMountFleetVerb("leaf", "followup_task")).toThrow(FleetAuthorityError);
+    expect(() => assertTierMayMountFleetVerb("leaf", "send_input")).toThrow(FleetAuthorityError);
   });
 
   test("leaves may still mount non-fleet tools", () => {

src/subagent/authority.ts

@@ -6,7 +6,7 @@
  *
  *  - assertTierMayMountFleetVerb: a Tier 3 leaf may never mount a fleet verb
  *    (task, spawn_agent, wait_agents, list_agents, interrupt_agent, close_agent,
- *    resume_agent, followup_task, send_input, read_agent_trace, search_agents).
+ *    resume_agent, send_input, read_agent_trace, search_agents).
  *    Fleet *discovery* of the director catalog (search_agents) is Tier 1 only
  *    (CL-7051). list_agents is not catalog discovery — it lists this install's
  *    own spawn_agent workers, the same scoped mailbox wait_agents uses, so
@@ -38,7 +38,6 @@ export const FLEET_VERBS = new Set([
   "close_agent",
   "resume_agent",
   "read_agent_trace",
-  "followup_task",
 ]);
 
 /**
@@ -114,7 +113,7 @@ function isDescendant(
  * always fails closed here too.
  *
  * Production call sites: `read_agent_trace`, `send_input`, `interrupt_agent`,
- * `close_agent`, `resume_agent`, and `followup_task` (nested mounts pass
+ * `close_agent`, and `resume_agent` (nested mounts pass
  * authority from run.ts; Tier-1 primary omits it and stays unrestricted).
  */
 export function assertCanTargetAgent(