@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/dist/bundled-resources/extensions/tmux-agent-manager/index.js

@@ -4,9 +4,117 @@ import * as fs from "node:fs";
 import { homedir } from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { getProcessWorkRun } from "@caupulican/pi-adaptative";
+import { getProcessWorkRun, PI_ORCHESTRATION_AGENT_ID_ENV, } from "@caupulican/pi-adaptative";
 import { Type } from "typebox";
+import { buildGrant, buildGrantUsageEntry, buildLaunchProfileFlags, buildTombstone, countGrantUsages, DEFAULT_READ_BIASED_TOOLS, decodeTmuxWorkerUsageClaim, describeGrant, GRANT_CUSTOM_TYPE, GRANT_USAGE_CUSTOM_TYPE, grantCovers, isTmuxDispatchGrant, isTmuxDispatchGrantTombstone, launchProfileSourceFromGrant, ONE_SHOT_LAUNCH_PROFILE_SOURCE, } from "./dispatch-grant.js";
 export const piConfig = { tools: ["tmux_agent_manager"] };
+function agentLaneId(jobId, agentId) {
+    return `tmux:${jobId}:${agentId}`;
+}
+function managedDispatch(job, agent) {
+    const sequence = agent.currentTurn ?? 1;
+    const instructions = agent.dispatchInstructions ?? job.task;
+    const authorizationId = agent.dispatchAuthorizationId ?? `legacy-job:${job.id}:turn:${sequence}`;
+    return {
+        sequence,
+        instructions,
+        profileId: `tmux:${agent.provider}`,
+        provider: agent.provider,
+        authorizationId,
+        authorizationKind: agent.dispatchAuthorizationKind ?? "legacy-recovery",
+        allowedTools: agent.dispatchAllowedTools ?? DEFAULT_READ_BIASED_TOOLS,
+        writePaths: agent.dispatchWritePaths ?? [],
+        ...(agent.dispatchMaxCostUsd !== undefined ? { maxCostUsd: agent.dispatchMaxCostUsd } : {}),
+        leaseTtlMs: agent.dispatchLeaseTtlMs ?? job.deadlineSeconds * 1_000,
+    };
+}
+function managedAuthorization(grant, fallbackId) {
+    const launchSource = grant ? launchProfileSourceFromGrant(grant) : ONE_SHOT_LAUNCH_PROFILE_SOURCE;
+    return {
+        authorizationId: grant?.grantId ?? fallbackId,
+        authorizationKind: grant ? "standing-grant" : "one-shot-owner-approval",
+        launchSource,
+        allowedTools: [...(launchSource.allowedTools?.length ? launchSource.allowedTools : DEFAULT_READ_BIASED_TOOLS)],
+        writePaths: [...(launchSource.writePaths ?? [])],
+        ...(grant?.budget.maxUsdAdvisory !== undefined ? { maxCostUsd: grant.budget.maxUsdAdvisory } : {}),
+    };
+}
+function applyManagedAuthorization(agent, authorization, args) {
+    agent.dispatchAuthorizationId = authorization.authorizationId;
+    agent.dispatchAuthorizationKind = authorization.authorizationKind;
+    agent.dispatchAllowedTools = [...authorization.allowedTools];
+    agent.dispatchWritePaths = [...authorization.writePaths];
+    if (authorization.maxCostUsd !== undefined)
+        agent.dispatchMaxCostUsd = authorization.maxCostUsd;
+    else
+        delete agent.dispatchMaxCostUsd;
+    agent.dispatchInstructions = args.instructions;
+    agent.dispatchGoalId = args.goalId;
+    agent.dispatchLeaseTtlMs = args.leaseTtlMs;
+}
+function reportManagedDispatchReservations(bridge, job, agents) {
+    if (!bridge.reportManagedLane)
+        return;
+    const attemptedLaneIds = [];
+    try {
+        for (const agent of agents) {
+            const laneId = agentLaneId(job.id, agent.id);
+            attemptedLaneIds.push(laneId);
+            bridge.reportManagedLane({
+                laneId,
+                phase: "dispatch",
+                goalId: agent.dispatchGoalId,
+                worktreeLaneKey: agent.worktreeLane,
+                dispatch: managedDispatch(job, agent),
+            });
+        }
+    }
+    catch (error) {
+        for (const laneId of attemptedLaneIds) {
+            try {
+                bridge.reportManagedLane({
+                    laneId,
+                    phase: "terminal",
+                    status: "failed",
+                    reasonCode: "managed_process_launch_reservation_failed",
+                });
+            }
+            catch {
+                // Preserve the reservation error; durable leases fence any compensation failure.
+            }
+        }
+        throw error;
+    }
+}
+function reportManagedLaunchFailure(bridge, job, reasonCode) {
+    if (!bridge.reportManagedLane)
+        return;
+    for (const agent of job.agents) {
+        reportManagedAgentFailure(bridge, job.id, agent.id, reasonCode);
+    }
+}
+function reportManagedAgentFailure(bridge, jobId, agentId, reasonCode) {
+    if (!bridge.reportManagedLane)
+        return;
+    try {
+        bridge.reportManagedLane({
+            laneId: agentLaneId(jobId, agentId),
+            phase: "terminal",
+            status: "failed",
+            reasonCode,
+        });
+    }
+    catch {
+        // Preserve the launch failure; durable leases fence any terminal-report failure.
+    }
+}
+function sameStringValues(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const sortedLeft = [...left].sort();
+    const sortedRight = [...right].sort();
+    return sortedLeft.every((value, index) => value === sortedRight[index]);
+}
 const EXTENSION_ROOT = path.dirname(fileURLToPath(import.meta.url));
 export function getTmuxAgentManagerDataRoot() {
     const agentDir = process.env.PI_ADAPTATIVE_CODING_AGENT_DIR ||
@@ -161,6 +269,10 @@ function runTmux(args, timeoutMs = 5_000) {
         args: [tmux, ...args],
     };
 }
+function requireTmuxRun(result, action) {
+    if (!result.ok)
+        throw new Error(`${action} failed: ${result.error || result.stderr || `exit ${result.status}`}`);
+}
 function detectTmux() {
     const tmuxBin = process.env.PI_TMUX_MANAGER_TMUX_BIN || findExecutable("tmux");
     const errors = [];
@@ -343,7 +455,7 @@ function normalizeAgents(params) {
             throw new Error(`agent ${name} needs command when provider=custom`);
         const tools = Array.isArray(agent.tools) && agent.tools.length > 0 ? agent.tools : undefined;
         const command = tools ? `${baseCommand} --tools ${tools.join(",")}` : baseCommand;
-        return { provider, name, command, cwd: agent.cwd, tools };
+        return { provider, name, command, cwd: agent.cwd, tools, worktreeLane: agent.worktreeLane };
     });
 }
 function defaultProviderInvocation(provider) {
@@ -543,6 +655,7 @@ function buildFireTaskPlan(ctx, params) {
             promptPath: path.join(jobDir, `${slug}.prompt.md`),
             logPath: path.join(jobDir, `${slug}.log`),
             resultPath: path.join(jobDir, `${slug}.result.json`),
+            worktreeLane: agent.worktreeLane,
         };
     });
     const job = {
@@ -613,9 +726,76 @@ function targetDisplayName(agent, index) {
 function tmuxSessionExists(name) {
     return runTmux(["has-session", "-t", name], 2_000).ok;
 }
+function tmuxPaneExists(sessionName, paneId) {
+    const result = runTmux(["list-panes", "-t", sessionName, "-F", "#{pane_id}"], 2_000);
+    if (!result.ok)
+        return false;
+    return result.stdout
+        .split(/\s+/)
+        .map((line) => line.trim())
+        .includes(paneId);
+}
+/** True when tmux already has a pipe-pane consumer attached to this pane (tmux's own `#{pane_pipe}`
+ * format flag). Session-level reconcile MUST check this before re-arming: a pane that still has an
+ * active pipe already has a live watcher; replacing it would close that watcher's stdin and race its
+ * own EOF-triggered `finish(failed, pane-stream-ended)` against the real marker that may be about to
+ * arrive, possibly recording a false failure for a job that was about to succeed on its own. Re-arming
+ * is only safe (and only useful) when tmux reports no pipe is currently attached. */
+function tmuxPaneHasPipe(paneId) {
+    const result = runTmux(["display-message", "-p", "-t", paneId, "#{pane_pipe}"], 2_000);
+    return result.ok && result.stdout.trim() === "1";
+}
+function turnMarkers(job, agent, turn) {
+    if (turn <= 1)
+        return { doneMarker: agent.doneMarker, blockedMarker: agent.blockedMarker };
+    const base = `TMUX_${crypto.createHash("sha1").update(`${job.id}:${agent.id}:${turn}`).digest("hex").slice(0, 10).toUpperCase()}`;
+    return { doneMarker: `${base}_DONE`, blockedMarker: `${base}_BLOCKED` };
+}
+function turnResultPath(jobDir, agentId, turn, baseResultPath) {
+    return turn <= 1 ? baseResultPath : path.join(jobDir, `${agentId}.turn-${turn}.result.json`);
+}
+function turnPromptPath(jobDir, agentId, turn, basePromptPath) {
+    return turn <= 1 ? basePromptPath : path.join(jobDir, `${agentId}.turn-${turn}.prompt.md`);
+}
+function turnWatcherPath(job, turn) {
+    return turn <= 1 ? job.watcherPath : path.join(job.jobDir, `pane-watcher.turn-${turn}.sh`);
+}
+/** The result-file path the CURRENT turn's watcher will write to for this agent (turn 1 keeps the
+ * fixed back-compat path). Stop handling must target this path, not the fixed one, or a stop signal
+ * issued mid-follow-up would land on a stale turn's file that nothing is watching anymore. */
+function currentResultPath(job, agent) {
+    return turnResultPath(job.jobDir, agent.id, agent.currentTurn ?? 1, agent.resultPath);
+}
+function persistAgentTurnFailure(jobId, agentId, turn, reason) {
+    persistJobPatch(jobId, (current) => {
+        const agent = current.agents.find((entry) => entry.id === agentId);
+        if (!agent || agent.currentTurn !== turn)
+            return undefined;
+        const result = {
+            status: "failed",
+            detectedAt: new Date().toISOString(),
+            reason,
+        };
+        fs.writeFileSync(currentResultPath(current, agent), `${JSON.stringify(result, null, 2)}\n`, { mode: 0o600 });
+        agent.result = result;
+        delete agent.pendingTurn;
+        return current;
+    });
+}
+/** Atomically read-modify-write job.json, always from a FRESH read (never from a caller's possibly
+ * stale in-memory copy), mirroring the temp+rename pattern the original notify path used. */
+function persistJobPatch(jobId, mutate) {
+    const jobPath = path.join(jobsRoot(), jobId, "job.json");
+    const current = JSON.parse(fs.readFileSync(jobPath, "utf8"));
+    const mutated = mutate(current) ?? current;
+    const temporaryPath = `${jobPath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(mutated, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    fs.renameSync(temporaryPath, jobPath);
+    return mutated;
+}
 function sendCommandToPane(paneId, command) {
-    runTmux(["send-keys", "-t", paneId, "-l", command]);
-    runTmux(["send-keys", "-t", paneId, "Enter"]);
+    requireTmuxRun(runTmux(["send-keys", "-t", paneId, "-l", command]), `tmux command injection for ${paneId}`);
+    requireTmuxRun(runTmux(["send-keys", "-t", paneId, "Enter"]), `tmux command submit for ${paneId}`);
 }
 function launchTmuxSession(sessionName, cwd, panes) {
     if (tmuxSessionExists(sessionName))
@@ -627,33 +807,102 @@ function launchTmuxSession(sessionName, cwd, panes) {
     runs.push(create);
     if (!create.ok)
         throw new Error(`tmux new-session failed: ${create.error || create.stderr || `exit ${create.status}`}`);
-    const firstPane = create.stdout.trim();
-    paneIds.push(firstPane);
-    sendCommandToPane(firstPane, first.command);
-    for (const pane of panes.slice(1)) {
-        const split = runTmux(["split-window", "-d", "-P", "-F", "#{pane_id}", "-t", `${sessionName}:0`, "-c", pane.cwd || cwd], 5_000);
-        runs.push(split);
-        if (!split.ok)
-            throw new Error(`tmux split-window failed: ${split.error || split.stderr || `exit ${split.status}`}`);
-        const paneId = split.stdout.trim();
-        paneIds.push(paneId);
-        sendCommandToPane(paneId, pane.command);
+    try {
+        const firstPane = create.stdout.trim();
+        paneIds.push(firstPane);
+        sendCommandToPane(firstPane, first.command);
+        for (const pane of panes.slice(1)) {
+            const split = runTmux(["split-window", "-d", "-P", "-F", "#{pane_id}", "-t", `${sessionName}:0`, "-c", pane.cwd || cwd], 5_000);
+            runs.push(split);
+            if (!split.ok)
+                throw new Error(`tmux split-window failed: ${split.error || split.stderr || `exit ${split.status}`}`);
+            const paneId = split.stdout.trim();
+            paneIds.push(paneId);
+            sendCommandToPane(paneId, pane.command);
+        }
+        runs.push(runTmux(["select-layout", "-t", `${sessionName}:0`, "tiled"], 3_000));
+        return { runs, paneIds };
+    }
+    catch (error) {
+        runTmux(["kill-session", "-t", sessionName], 5_000);
+        throw error;
     }
-    runs.push(runTmux(["select-layout", "-t", `${sessionName}:0`, "tiled"], 3_000));
-    return { runs, paneIds };
 }
 function injectPromptToPane(paneId, prompt, provider) {
     const text = interactivePromptText(prompt);
     if (provider === "claude") {
         const bufferName = `pi-tmux-${crypto.randomBytes(4).toString("hex")}`;
-        runTmux(["set-buffer", "-b", bufferName, text], 10_000);
-        runTmux(["paste-buffer", "-b", bufferName, "-t", paneId], 10_000);
-        runTmux(["send-keys", "-t", paneId, "Enter"], 3_000);
-        runTmux(["delete-buffer", "-b", bufferName], 3_000);
+        requireTmuxRun(runTmux(["set-buffer", "-b", bufferName, text], 10_000), "tmux prompt buffer creation");
+        try {
+            requireTmuxRun(runTmux(["paste-buffer", "-b", bufferName, "-t", paneId], 10_000), `tmux prompt injection for ${paneId}`);
+            requireTmuxRun(runTmux(["send-keys", "-t", paneId, "Enter"], 3_000), `tmux prompt submit for ${paneId}`);
+        }
+        finally {
+            runTmux(["delete-buffer", "-b", bufferName], 3_000);
+        }
         return;
     }
-    runTmux(["send-keys", "-t", paneId, "-l", text], 10_000);
-    runTmux(["send-keys", "-t", paneId, provider === "agy" ? "C-m" : "Enter"], 3_000);
+    requireTmuxRun(runTmux(["send-keys", "-t", paneId, "-l", text], 10_000), `tmux prompt injection for ${paneId}`);
+    requireTmuxRun(runTmux(["send-keys", "-t", paneId, provider === "agy" ? "C-m" : "Enter"], 3_000), `tmux prompt submit for ${paneId}`);
+}
+/** Write a fresh per-turn prompt + single-agent watcher script and arm `pipe-pane -O` for it. Used by
+ * send_followup to open a NEW turn on an already-live pane. Does not inject the prompt text into the
+ * pane itself — callers do that separately via injectPromptToPane, after this has armed the watcher,
+ * so the completion contract is listening before the worker can possibly reply. */
+function dispatchAgentTurn(job, agent, turn, promptText) {
+    if (!agent.paneId)
+        throw new Error(`tmux agent ${agent.name} has no recorded pane id`);
+    const markers = turnMarkers(job, agent, turn);
+    const resultPath = turnResultPath(job.jobDir, agent.id, turn, agent.resultPath);
+    const promptPath = turnPromptPath(job.jobDir, agent.id, turn, agent.promptPath);
+    const watcherPath = turnWatcherPath(job, turn);
+    fs.writeFileSync(promptPath, `${promptText}\n`, { mode: 0o600 });
+    const turnSpec = {
+        id: job.id,
+        sessionName: job.sessionName,
+        deadlineSeconds: job.deadlineSeconds,
+        agents: [
+            { ...agent, doneMarker: markers.doneMarker, blockedMarker: markers.blockedMarker, resultPath, promptPath },
+        ],
+    };
+    fs.writeFileSync(watcherPath, makePaneWatcherScript(turnSpec), { mode: 0o700 });
+    fs.chmodSync(watcherPath, 0o700);
+    const armed = runTmux([
+        "pipe-pane",
+        "-O",
+        "-t",
+        agent.paneId,
+        `sh ${quoteShell(watcherPath)} ${quoteShell(agent.id)}`,
+    ]);
+    if (!armed.ok)
+        throw new Error(`Failed to arm completion watcher for turn ${turn}: ${armed.error || armed.stderr || armed.stdout}`);
+    return { promptPath, resultPath, watcherPath };
+}
+/** Session-level reconcile's resume step: re-arm `pipe-pane` for an agent whose current turn is still
+ * pending on a pane tmux confirms is alive AND has no pipe already attached (see tmuxPaneHasPipe). Only
+ * regenerates the watcher SCRIPT file if it is missing (e.g. this is the first reconcile after a reload
+ * whose disk state predates a crash) — the prompt was already injected once and is not re-sent. */
+function rearmAgentWatcher(job, agent) {
+    if (!agent.paneId)
+        return;
+    const turn = agent.currentTurn ?? 1;
+    const markers = turnMarkers(job, agent, turn);
+    const resultPath = turnResultPath(job.jobDir, agent.id, turn, agent.resultPath);
+    const promptPath = turnPromptPath(job.jobDir, agent.id, turn, agent.promptPath);
+    const watcherPath = turnWatcherPath(job, turn);
+    if (!fs.existsSync(watcherPath)) {
+        const turnSpec = {
+            id: job.id,
+            sessionName: job.sessionName,
+            deadlineSeconds: job.deadlineSeconds,
+            agents: [
+                { ...agent, doneMarker: markers.doneMarker, blockedMarker: markers.blockedMarker, resultPath, promptPath },
+            ],
+        };
+        fs.writeFileSync(watcherPath, makePaneWatcherScript(turnSpec), { mode: 0o700 });
+        fs.chmodSync(watcherPath, 0o700);
+    }
+    runTmux(["pipe-pane", "-O", "-t", agent.paneId, `sh ${quoteShell(watcherPath)} ${quoteShell(agent.id)}`]);
 }
 function stopTmuxSession(sessionName, dryRun, confirm) {
     if (!sessionName)
@@ -675,10 +924,11 @@ function isAlreadyExistsError(error) {
 }
 function markStopRequested(job) {
     for (const agent of job.agents) {
-        if (fs.existsSync(agent.resultPath))
+        const resultPath = currentResultPath(job, agent);
+        if (fs.existsSync(resultPath))
             continue;
         try {
-            fs.writeFileSync(`${agent.resultPath}.stop-requested`, `${new Date().toISOString()}\n`, {
+            fs.writeFileSync(`${resultPath}.stop-requested`, `${new Date().toISOString()}\n`, {
                 encoding: "utf8",
                 mode: 0o600,
                 flag: "wx",
@@ -692,11 +942,12 @@ function markStopRequested(job) {
 }
 function clearStopRequested(job) {
     for (const agent of job.agents)
-        fs.rmSync(`${agent.resultPath}.stop-requested`, { force: true });
+        fs.rmSync(`${currentResultPath(job, agent)}.stop-requested`, { force: true });
 }
 function persistStoppedResults(job) {
     for (const agent of job.agents) {
-        if (!fs.existsSync(agent.resultPath)) {
+        const resultPath = currentResultPath(job, agent);
+        if (!fs.existsSync(resultPath)) {
             const result = {
                 jobId: job.id,
                 agentId: agent.id,
@@ -709,7 +960,7 @@ function persistStoppedResults(job) {
                 notifiedBy: "stop-action-event",
             };
             try {
-                fs.writeFileSync(agent.resultPath, `${JSON.stringify(result, null, 2)}\n`, {
+                fs.writeFileSync(resultPath, `${JSON.stringify(result, null, 2)}\n`, {
                     encoding: "utf8",
                     mode: 0o600,
                     flag: "wx",
@@ -720,7 +971,7 @@ function persistStoppedResults(job) {
                     throw error;
             }
         }
-        fs.rmSync(`${agent.resultPath}.stop-requested`, { force: true });
+        fs.rmSync(`${resultPath}.stop-requested`, { force: true });
     }
 }
 function stopTmuxSessionWithJobSignals(sessionName, jobs, dryRun, confirm) {
@@ -769,8 +1020,10 @@ function loadJob(id) {
     if (!Array.isArray(parsed.agents))
         throw new Error(`tmux job has invalid agents: ${id}`);
     for (const agent of parsed.agents) {
+        // Read from the CURRENT turn's result path (turn 1 is the fixed back-compat path) so a job
+        // mid-follow-up is correctly seen as non-terminal until the NEW turn settles.
         try {
-            agent.result = JSON.parse(fs.readFileSync(agent.resultPath, "utf8"));
+            agent.result = JSON.parse(fs.readFileSync(currentResultPath(parsed, agent), "utf8"));
         }
         catch {
             delete agent.result;
@@ -815,7 +1068,13 @@ function listJobs() {
                     workspaceName: job.workspaceName,
                     sessionName: job.sessionName,
                     createdAt: job.createdAt,
-                    agents: job.agents.map((agent) => ({ name: agent.name, status: agent.result?.status || "pending" })),
+                    orphaned: Boolean(job.orphanedAt),
+                    dismissed: Boolean(job.dismissedAt),
+                    agents: job.agents.map((agent) => ({
+                        name: agent.name,
+                        status: agent.result?.status || "pending",
+                        turn: agent.currentTurn ?? 1,
+                    })),
                 };
             }
             catch (error) {
@@ -845,7 +1104,112 @@ function setVariable(jobId, name, value) {
     fs.writeFileSync(job.varsPath, `${JSON.stringify(current, null, 2)}\n`, { mode: 0o600 });
     return { varsPath: job.varsPath, variables: current.variables, updatedAt: current.updatedAt };
 }
-async function executeTool(_toolCallId, params, _signal, _onUpdate, ctx) {
+// ---------------------------------------------------------------------------
+// STANDING GRANT — approval-gated tmux dispatch. The pure decode/decision logic lives in
+// dispatch-grant.ts; the functions below are the session-access GLUE: read the latest grant custom
+// entry (skipping past malformed payloads, but stopping DEAD on a tombstone — never resurrecting an
+// older grant beneath a revocation), count spend, and gate a real launch.
+// ---------------------------------------------------------------------------
+/** Most recent VALID `tmux-dispatch-grant` entry on the active branch, or undefined when there is
+ * none, it was revoked (a tombstone is a hard stop — never skipped to find an older grant), or every
+ * entry found fails to decode. Mirrors the branch-walk idiom used by goal/task session state. */
+function resolveLatestGrantEntry(ctx) {
+    let fromId;
+    for (;;) {
+        const entry = ctx.sessionManager.getLatestCustomEntryOnBranch(GRANT_CUSTOM_TYPE, fromId);
+        if (!entry)
+            return undefined;
+        if (isTmuxDispatchGrantTombstone(entry.data))
+            return undefined;
+        if (isTmuxDispatchGrant(entry.data))
+            return entry.data;
+        if (!entry.parentId)
+            return undefined;
+        fromId = entry.parentId;
+    }
+}
+/** Decoded `data` payloads of every custom entry of `customType` on the active branch (root→leaf
+ * order), for spend-counting — a single `getLatestCustomEntryOnBranch` call only ever returns ONE
+ * entry, but budget spend requires ALL of them. */
+function collectCustomEntryData(ctx, customType) {
+    const result = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+        const loose = entry;
+        if (loose.type === "custom" && loose.customType === customType)
+            result.push(loose.data);
+    }
+    return result;
+}
+/** Gate a REAL tmux dispatch (fire_task non-dryRun, send_followup) per the standing-grant doctrine:
+ * a valid covering grant dispatches UNATTENDED (spending one usage); absent that, an
+ * interactive host may approve a ONE-SHOT launch; absent BOTH, this REFUSES — never a silent launch.
+ * Returns the covering grant when one authorized this launch (so the caller can derive launch-profile
+ * flags from its envelope), or `{}` for a one-shot approval (no envelope to derive from — the caller
+ * falls back to the conservative default profile). */
+async function authorizeLaunch(bridge, ctx, request) {
+    if (request.agents.length === 0)
+        throw new Error("tmux dispatch refused: launch has no agents");
+    const grant = resolveLatestGrantEntry(ctx);
+    // A standing grant names one provider. It must cover every child and spend one unit for every
+    // child process; a matching first pane must never authorize an unrestricted mixed team.
+    if (grant && request.agents.every((agent) => grantCovers(grant, { agent, goalId: request.goalId }))) {
+        const used = countGrantUsages(grant.grantId, collectCustomEntryData(ctx, GRANT_USAGE_CUSTOM_TYPE));
+        if (grant.budget.maxLaunches - used >= request.agents.length) {
+            if (!bridge.appendEntry)
+                throw new Error("this host does not support session custom entries; cannot spend the tmux dispatch grant.");
+            for (let index = 0; index < request.agents.length; index++) {
+                bridge.appendEntry(GRANT_USAGE_CUSTOM_TYPE, buildGrantUsageEntry(grant.grantId, `${request.jobId}:${index}`));
+            }
+            return { grant };
+        }
+    }
+    if (ctx.hasUI) {
+        const approved = await ctx.ui.confirm("tmux dispatch approval", [
+            `No standing grant currently authorizes every child of: ${request.description}.`,
+            `Agents: ${request.agents.join(", ")}${request.goalId ? `, goal: ${request.goalId}` : ""}.`,
+            "Approve this ONE-SHOT launch? Run tmux_agent_manager action=grant_dispatch to authorize future launches without this prompt.",
+        ].join("\n"));
+        if (!approved)
+            throw new Error(`tmux dispatch declined by the owner: ${request.description}`);
+        return {};
+    }
+    throw new Error(`no standing grant for tmux dispatch; run grant_dispatch first: every child must be covered. ${request.description}. Refusing to launch without a grant or interactive approval.`);
+}
+/** Render grant/one-shot-derived launch-profile flags into a pi child's start command. Values
+ * are shell-quoted; flags are not (they're fixed literals, never user input). */
+function appendLaunchProfileFlags(command, flags) {
+    const rendered = flags.map((flag) => flag.value !== undefined ? `${flag.flag} ${quoteShell(flag.value)}` : flag.flag);
+    return [command, ...rendered].join(" ");
+}
+/** Apply the launch profile to every provider="pi" agent in the job (fire_task only — send_followup
+ * reuses an already-launched pane, so there is no new child command to configure). Non-pi agents are
+ * bounded by the grant only at the launch layer (agent/budget/count); their internal tool-loop
+ * enforcement is the target CLI's own responsibility (documented limitation, not a hidden gap). */
+function applyLaunchProfile(job, source) {
+    for (const agent of job.agents) {
+        if (agent.provider !== "pi")
+            continue;
+        // Per-agent flags: `worktreeLane` is a per-agent property (only a lane-first goal->tmux
+        // dispatch sets it), so the shared `source` envelope is extended with it just for this agent's
+        // flag build -- every other agent in a multi-agent team keeps the plain grant-derived profile.
+        const flags = buildLaunchProfileFlags(agent.worktreeLane ? { ...source, worktreeLane: agent.worktreeLane } : source);
+        const profiledCommand = appendLaunchProfileFlags(agent.command || defaultProviderInvocation(agent.provider), flags);
+        agent.command = `env ${PI_ORCHESTRATION_AGENT_ID_ENV}=${quoteShell(agentLaneId(job.id, agent.id))} ${profiledCommand}`;
+    }
+}
+/** Read an OPTIONAL, cooperative worker-reported usage claim for the turn that just went terminal (a
+ * sibling `<result-path>.usage.json` file next to the watcher's own result file). Absent file ⇒ no
+ * claim was offered ⇒ nothing is reported (never fabricated). */
+function readWorkerUsageClaim(job, agent) {
+    const usagePath = `${currentResultPath(job, agent)}.usage.json`;
+    try {
+        return decodeTmuxWorkerUsageClaim(JSON.parse(fs.readFileSync(usagePath, "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function executeTool(_toolCallId, params, _signal, _onUpdate, ctx, bridge) {
     const action = params.action || "status";
     const detection = detectTmux();
     if (action === "status")
@@ -901,6 +1265,62 @@ async function executeTool(_toolCallId, params, _signal, _onUpdate, ctx) {
             details: { action, jobId: params.jobId, variableName: params.variableName, result },
         };
     }
+    if (action === "grant_dispatch") {
+        if (!params.agent)
+            throw new Error("grant_dispatch requires agent");
+        if (!Object.hasOwn(PROVIDER_COMMANDS, params.agent))
+            throw new Error(`grant_dispatch: unsupported agent: ${params.agent}`);
+        const grantParams = {
+            agent: params.agent,
+            goalId: params.goalId,
+            allowedTools: params.allowedTools,
+            resourceProfile: params.resourceProfile,
+            writePaths: params.writePaths,
+            maxLaunches: typeof params.maxLaunches === "number" ? params.maxLaunches : Number.NaN,
+            expiresInMinutes: params.expiresInMinutes,
+            maxUsdAdvisory: params.maxUsdAdvisory,
+        };
+        const grant = buildGrant(grantParams);
+        const summary = describeGrant(grant);
+        // OWNER-AUTHORIZED, NEVER SILENT: an interactive host must explicitly confirm the exact
+        // grant details; a non-interactive host (print/rpc, or the unattended goal loop) has no confirm
+        // surface, so it needs an explicit opt-in flag instead — absent either, refuse to create the grant.
+        if (ctx.hasUI) {
+            const approved = await ctx.ui.confirm("Authorize tmux dispatch grant", summary);
+            if (!approved)
+                throw new Error("grant_dispatch was declined by the owner.");
+        }
+        else if (bridge.getFlag?.("allow-tmux-dispatch") !== true) {
+            throw new Error("grant_dispatch requires interactive approval; no UI is available in this mode. Pass --allow-tmux-dispatch to authorize grant creation non-interactively.");
+        }
+        if (!bridge.appendEntry)
+            throw new Error("this host does not support session custom entries; cannot persist a tmux dispatch grant.");
+        bridge.appendEntry(GRANT_CUSTOM_TYPE, grant);
+        return {
+            content: [{ type: "text", text: `Created tmux dispatch grant ${grant.grantId}.\n${summary}` }],
+            details: { action, grant },
+        };
+    }
+    if (action === "revoke_grant") {
+        const activeGrant = resolveLatestGrantEntry(ctx);
+        const targetGrantId = firstString(params.grantId) || activeGrant?.grantId;
+        if (!targetGrantId)
+            throw new Error("revoke_grant: no active tmux dispatch grant to revoke.");
+        if (activeGrant && activeGrant.grantId !== targetGrantId)
+            throw new Error(`revoke_grant: grantId ${targetGrantId} is not the active grant (active: ${activeGrant.grantId}).`);
+        if (!bridge.appendEntry)
+            throw new Error("this host does not support session custom entries; cannot revoke a tmux dispatch grant.");
+        bridge.appendEntry(GRANT_CUSTOM_TYPE, buildTombstone(targetGrantId));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Revoked tmux dispatch grant ${targetGrantId}. Future launches need a new grant_dispatch or interactive/opt-in approval.`,
+                },
+            ],
+            details: { action, grantId: targetGrantId },
+        };
+    }
     const guard = await guardTmux(ctx, detection, `tmux ${action}`);
     if (!guard.allowed)
         return { content: [{ type: "text", text: guard.text }], details: { action, detection, guard, skipped: true } };
@@ -965,40 +1385,222 @@ async function executeTool(_toolCallId, params, _signal, _onUpdate, ctx) {
             };
         if (tmuxSessionExists(job.sessionName))
             throw new Error(`tmux session already exists: ${job.sessionName}. Use stop_job/stop_session first or choose a different workspaceName.`);
-        const archivedJobDir = prepareJobDirForLaunch(job, params.force);
-        const panes = job.agents.map((agent) => ({
-            title: agent.name,
-            cwd: agent.cwd,
-            command: agent.command || defaultProviderInvocation(agent.provider),
-        }));
-        const launch = launchTmuxSession(job.sessionName, job.cwd, panes);
-        job.agents.forEach((agent, index) => {
-            agent.paneId = launch.paneIds[index];
+        // APPROVAL-GATED LAUNCH: resolved before any tmux/FS side effect. A standing grant must
+        // authorize every child provider and spend its budget per child process.
+        const authorization = await authorizeLaunch(bridge, ctx, {
+            agents: job.agents.map((agent) => agent.provider),
+            goalId: params.goalId,
+            jobId: job.id,
+            description: `fire_task launch of job ${job.id} (${job.agents.length} child process${job.agents.length === 1 ? "" : "es"}: ${job.agents.map((agent) => `${agent.name}/${agent.provider}`).join(", ")})`,
         });
-        writeFireTaskFiles(job);
-        const watcherPanes = startPaneWatchers(job);
+        const managedAuthority = managedAuthorization(authorization.grant, `one-shot:${job.id}:turn:1`);
         for (const agent of job.agents) {
-            if (!agent.paneId)
-                continue;
-            injectPromptToPane(agent.paneId, fs.readFileSync(agent.promptPath, "utf8"), agent.provider);
+            agent.currentTurn = 1;
+            applyManagedAuthorization(agent, managedAuthority, {
+                instructions: job.task,
+                goalId: params.goalId,
+                leaseTtlMs: job.deadlineSeconds * 1_000,
+            });
+        }
+        applyLaunchProfile(job, {
+            ...managedAuthority.launchSource,
+            ...(params.goalId ? { taskRef: params.goalId } : {}),
+            // Process-matrix parent identity: the dispatched child self-registers as a worker of THIS
+            // session and winds down gracefully if this session disappears (see dispatch-grant.ts's
+            // `LaunchProfileSource.parentPid`/`parentSession` doc).
+            parentPid: process.pid,
+            parentSession: ctx.sessionManager.getSessionId?.() ?? ctx.sessionManager.getSessionFile(),
+        });
+        // The host commits the full execution grant and starts the durable lease before any child
+        // process, job artifact, watcher, or prompt side effect occurs.
+        reportManagedDispatchReservations(bridge, job, job.agents);
+        let sessionCreated = false;
+        try {
+            const archivedJobDir = prepareJobDirForLaunch(job, params.force);
+            const panes = job.agents.map((agent) => ({
+                title: agent.name,
+                cwd: agent.cwd,
+                command: agent.command || defaultProviderInvocation(agent.provider),
+            }));
+            const launch = launchTmuxSession(job.sessionName, job.cwd, panes);
+            sessionCreated = true;
+            job.agents.forEach((agent, index) => {
+                agent.paneId = launch.paneIds[index];
+            });
+            writeFireTaskFiles(job);
+            const watcherPanes = startPaneWatchers(job);
+            for (const agent of job.agents) {
+                if (!agent.paneId)
+                    continue;
+                injectPromptToPane(agent.paneId, fs.readFileSync(agent.promptPath, "utf8"), agent.provider);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `Launched tmux interactive fire-and-forget job ${job.id}.`,
+                            `Session: ${job.sessionName}`,
+                            `Attach: tmux attach -t ${job.sessionName}`,
+                            `Job state: ${job.jobPath}`,
+                            archivedJobDir ? `Archived previous job dir: ${archivedJobDir}` : undefined,
+                            "Completion: event-driven pane output watchers armed (no polling).",
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+                details: {
+                    action,
+                    detection,
+                    job,
+                    runs: launch.runs,
+                    paneIds: launch.paneIds,
+                    watcherPanes,
+                    archivedJobDir,
+                },
+            };
+        }
+        catch (error) {
+            if (sessionCreated)
+                runTmux(["kill-session", "-t", job.sessionName], 5_000);
+            reportManagedLaunchFailure(bridge, job, "managed_process_launch_failed");
+            throw error;
+        }
+    }
+    if (action === "send_followup") {
+        if (!params.jobId)
+            throw new Error("send_followup requires jobId");
+        const followupTask = firstString(params.task, params.body);
+        if (!followupTask)
+            throw new Error("send_followup requires task (or body) with the follow-up objective");
+        const job = loadJob(params.jobId);
+        if (job.dismissedAt)
+            throw new Error(`tmux job ${job.id} was dismissed; use fire_task to relaunch instead of send_followup`);
+        if (job.agents.length === 0)
+            throw new Error(`tmux job has no agents: ${job.id}`);
+        const targetAgent = params.agentId ? job.agents.find((agent) => agent.id === params.agentId) : job.agents[0];
+        if (!targetAgent)
+            throw new Error(`tmux job ${job.id} has no agent ${params.agentId}`);
+        if (!targetAgent.paneId)
+            throw new Error(`tmux agent ${targetAgent.name} has no recorded pane id; cannot send a follow-up`);
+        if (targetAgent.pendingTurn !== undefined)
+            throw new Error(`send_followup refused: turn ${targetAgent.pendingTurn} for ${targetAgent.id} is pending reconciliation; refusing to risk a duplicate prompt`);
+        const turn = (targetAgent.currentTurn ?? 1) + 1;
+        const markers = turnMarkers(job, targetAgent, turn);
+        const promptText = managedPrompt(followupTask, job.id, targetAgent, markers.doneMarker, markers.blockedMarker, job.varsPath);
+        if (params.dryRun === true)
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `DRY RUN tmux send_followup\nJob: ${job.id}\nAgent: ${targetAgent.name}\nTurn: ${turn}`,
+                    },
+                ],
+                details: { action, detection, dryRun: true, jobId: job.id, agentId: targetAgent.id, turn },
+            };
+        if (!tmuxSessionExists(job.sessionName))
+            throw new Error(`tmux session is gone: ${job.sessionName}. The worker pane cannot receive a follow-up; use fire_task to relaunch.`);
+        if (!tmuxPaneExists(job.sessionName, targetAgent.paneId))
+            throw new Error(`tmux pane ${targetAgent.paneId} for ${targetAgent.name} is gone. The worker cannot receive a follow-up; use fire_task to relaunch.`);
+        // APPROVAL-GATED LAUNCH (doctrine-regression mandatory): a follow-up dispatches a fresh
+        // turn into an already-running child, so there is no new child command to profile — only the
+        // grant/one-shot authorization is resolved here (no applyLaunchProfile call).
+        const authorization = await authorizeLaunch(bridge, ctx, {
+            agents: [targetAgent.provider],
+            goalId: params.goalId,
+            jobId: `${job.id}:turn:${turn}`,
+            description: `send_followup turn ${turn} to ${targetAgent.name} in job ${job.id}`,
+        });
+        const managedAuthority = managedAuthorization(authorization.grant, `one-shot:${job.id}:turn:${turn}`);
+        const launchAllowedTools = targetAgent.dispatchAllowedTools ?? [...DEFAULT_READ_BIASED_TOOLS];
+        const launchWritePaths = targetAgent.dispatchWritePaths ?? [];
+        if (!sameStringValues(launchAllowedTools, managedAuthority.allowedTools) ||
+            !sameStringValues(launchWritePaths, managedAuthority.writePaths)) {
+            throw new Error(`send_followup refused: authorization scope differs from the already-running process for ${targetAgent.name}; relaunch the worker to apply a new tool or write-path scope.`);
+        }
+        // Reserve before watcher/prompt side effects. Reconcile re-arms a reserved turn but never
+        // re-injects it, so crash recovery cannot duplicate a provider prompt.
+        const reserved = persistJobPatch(job.id, (current) => {
+            const agent = current.agents.find((entry) => entry.id === targetAgent.id);
+            if (!agent || agent.pendingTurn !== undefined)
+                return undefined;
+            agent.currentTurn = turn;
+            agent.pendingTurn = turn;
+            agent.result = undefined;
+            applyManagedAuthorization(agent, managedAuthority, {
+                instructions: followupTask,
+                goalId: params.goalId,
+                leaseTtlMs: job.deadlineSeconds * 1_000,
+            });
+            current.currentTurn = turn;
+            return current;
+        });
+        const reservedAgent = reserved.agents.find((agent) => agent.id === targetAgent.id);
+        if (!reservedAgent || reservedAgent.pendingTurn !== turn)
+            throw new Error(`send_followup refused: failed to reserve turn ${turn} for ${targetAgent.id}`);
+        try {
+            reportManagedDispatchReservations(bridge, reserved, [reservedAgent]);
+        }
+        catch (error) {
+            persistAgentTurnFailure(job.id, reservedAgent.id, turn, "managed_process_launch_reservation_failed");
+            throw error;
+        }
+        let written;
+        try {
+            written = dispatchAgentTurn(reserved, reservedAgent, turn, promptText);
+            injectPromptToPane(reservedAgent.paneId, promptText, reservedAgent.provider);
+            persistJobPatch(job.id, (current) => {
+                const agent = current.agents.find((entry) => entry.id === reservedAgent.id);
+                if (!agent || agent.pendingTurn !== turn)
+                    return undefined;
+                delete agent.pendingTurn;
+                return current;
+            });
+        }
+        catch (error) {
+            persistAgentTurnFailure(job.id, reservedAgent.id, turn, "managed_process_followup_failed");
+            reportManagedAgentFailure(bridge, job.id, reservedAgent.id, "managed_process_followup_failed");
+            throw error;
         }
         return {
             content: [
                 {
                     type: "text",
                     text: [
-                        `Launched tmux interactive fire-and-forget job ${job.id}.`,
+                        `Sent follow-up turn ${turn} to ${targetAgent.name} in job ${job.id}.`,
                         `Session: ${job.sessionName}`,
-                        `Attach: tmux attach -t ${job.sessionName}`,
-                        `Job state: ${job.jobPath}`,
-                        archivedJobDir ? `Archived previous job dir: ${archivedJobDir}` : undefined,
-                        "Completion: event-driven pane output watchers armed (no polling).",
-                    ]
-                        .filter(Boolean)
-                        .join("\n"),
+                        `Prompt: ${written.promptPath}`,
+                        `Completion: event-driven pane watcher re-armed for turn ${turn} (no polling).`,
+                    ].join("\n"),
                 },
             ],
-            details: { action, detection, job, runs: launch.runs, paneIds: launch.paneIds, watcherPanes, archivedJobDir },
+            details: { action, detection, jobId: job.id, agentId: targetAgent.id, turn, ...written },
+        };
+    }
+    if (action === "dismiss") {
+        if (!params.jobId)
+            throw new Error("dismiss requires jobId");
+        const job = loadJob(params.jobId);
+        if (job.dismissedAt)
+            return {
+                content: [{ type: "text", text: `tmux job ${job.id} was already dismissed.` }],
+                details: { action, jobId: job.id, alreadyDismissed: true },
+            };
+        persistJobPatch(job.id, (current) => {
+            current.dismissedAt = new Date().toISOString();
+            return current;
+        });
+        for (const agent of job.agents)
+            bridge.reportManagedLane?.({ laneId: agentLaneId(job.id, agent.id), phase: "terminal", status: "dismissed" });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Dismissed tmux job ${job.id}. Session '${job.sessionName}' left running (not killed); attach with: tmux attach -t ${job.sessionName}. Use stop_session/stop_job to terminate it.`,
+                },
+            ],
+            details: { action, jobId: job.id, sessionName: job.sessionName },
         };
     }
     if (action === "notify") {
@@ -1082,18 +1684,73 @@ function formatFireTaskHandoff(job) {
         "This event woke the parent; do not poll. Continue safe scoped work from the bounded handoff and inspect terminal artifacts only if needed for a material claim.",
     ].join("\n");
 }
-function markFireTaskNotified(job) {
-    const current = JSON.parse(fs.readFileSync(job.jobPath, "utf8"));
-    current.notifiedAt = new Date().toISOString();
-    const temporaryPath = `${job.jobPath}.tmp-${process.pid}-${Date.now()}`;
-    fs.writeFileSync(temporaryPath, `${JSON.stringify(current, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-    fs.renameSync(temporaryPath, job.jobPath);
-    job.notifiedAt = current.notifiedAt;
+/** Diff live tmux sessions against this session's job records. Mirrors the invariant behind
+ * `LocalRuntimeController.reconcile` (local-runtime-controller.ts): reconcile only ever OBSERVES —
+ * it never kills a session it did not provably start. A job whose tmux session is gone is marked
+ * orphaned (informational, one-shot); a job whose session is alive but current turn is still
+ * pending is resumed by re-arming its watcher, but ONLY when tmux confirms no pipe is already
+ * attached to that pane (see tmuxPaneHasPipe) — otherwise a live watcher would be raced and could
+ * be made to report a false failure. */
+function reconcileTmuxSessions(ctx, bridge) {
+    const sessionFile = ctx.sessionManager.getSessionFile();
+    const jobs = loadJobPlans().filter((job) => job.parentSessionFile === sessionFile && !job.dismissedAt);
+    if (jobs.length === 0)
+        return;
+    const detection = detectTmux();
+    if (!detection.cliAvailable)
+        return;
+    const liveSessions = new Set(detection.sessions);
+    for (const job of jobs) {
+        if (!liveSessions.has(job.sessionName)) {
+            if (!isFireTaskTerminal(job) && !job.orphanedAt) {
+                persistJobPatch(job.id, (current) => {
+                    current.orphanedAt = new Date().toISOString();
+                    return current;
+                });
+                if (ctx.hasUI)
+                    ctx.ui.notify(`tmux job ${job.id} is orphaned: session '${job.sessionName}' is gone and the job never reached a terminal state. Nothing was killed; this is informational only.`, "warning");
+                // Nothing is killed here — only the LANE record is released. A dead session means the
+                // worker itself can no longer report its own terminal state, so a goal bound to it would
+                // wait forever without this: release the managed lane per non-terminal agent so the goal's
+                // continuation stops waiting on a worker that will never report back.
+                for (const agent of job.agents) {
+                    if (agent.result !== undefined)
+                        continue;
+                    bridge.reportManagedLane?.({
+                        laneId: agentLaneId(job.id, agent.id),
+                        phase: "terminal",
+                        status: "orphaned",
+                        reasonCode: "tmux_session_orphaned",
+                    });
+                }
+            }
+            continue;
+        }
+        if (isFireTaskTerminal(job))
+            continue;
+        for (const agent of job.agents) {
+            if (agent.result !== undefined)
+                continue;
+            if (!agent.paneId || !tmuxPaneExists(job.sessionName, agent.paneId))
+                continue;
+            if (tmuxPaneHasPipe(agent.paneId))
+                continue;
+            reportManagedDispatchReservations(bridge, job, [agent]);
+            rearmAgentWatcher(job, agent);
+        }
+    }
 }
 export default function tmuxAgentManagerExtension(pi) {
     let handoffContext;
     let handoffTail = Promise.resolve();
     const jobWatchers = new Map();
+    const bridge = pi;
+    // Non-interactive opt-in for grant_dispatch: optional-chained so a lightweight test double
+    // that doesn't implement registerFlag still loads the extension; a real host always has it.
+    bridge.registerFlag?.("allow-tmux-dispatch", {
+        type: "boolean",
+        description: "Authorize tmux_agent_manager grant_dispatch to create a standing tmux dispatch grant without interactive approval (print/rpc/non-interactive mode only).",
+    });
     const closeJobWatchers = () => {
         for (const watcher of jobWatchers.values())
             watcher.close();
@@ -1101,21 +1758,61 @@ export default function tmuxAgentManagerExtension(pi) {
     };
     const refreshJobHandoffs = async (ctx) => {
         const sessionFile = ctx.sessionManager.getSessionFile();
-        const jobs = loadJobPlans().filter((job) => !job.parentSessionFile || job.parentSessionFile === sessionFile);
+        const jobs = loadJobPlans().filter((job) => (!job.parentSessionFile || job.parentSessionFile === sessionFile) && !job.dismissedAt);
         for (const job of jobs) {
-            if (!isFireTaskTerminal(job) || job.notifiedAt)
+            if (!isFireTaskTerminal(job))
                 continue;
-            pi.sendMessage({
-                customType: "tmux-background-completion",
-                content: formatFireTaskHandoff(job),
-                display: true,
-                details: {
-                    jobId: job.id,
-                    sessionName: job.sessionName,
-                    agents: job.agents.map((agent) => ({ id: agent.id, name: agent.name, status: agent.result?.status })),
-                },
-            }, { triggerTurn: true, deliverAs: "followUp" });
-            markFireTaskNotified(job);
+            // Per-turn notify: a job is not permanently "closed" after its first terminal turn — a
+            // follow-up reopens it, so the gate is per-agent (notifiedTurn < currentTurn), not a
+            // single whole-job notifiedAt flag.
+            const pendingAgents = job.agents.filter((agent) => (agent.notifiedTurn ?? 0) < (agent.currentTurn ?? 1));
+            if (pendingAgents.length === 0)
+                continue;
+            for (const agent of pendingAgents) {
+                // Advisory-only, and only ever reported when the worker itself chose to write the
+                // claim file — never fabricated, never a hard cross-process cap.
+                const usage = readWorkerUsageClaim(job, agent);
+                bridge.reportManagedLane?.({
+                    laneId: agentLaneId(job.id, agent.id),
+                    phase: "terminal",
+                    status: agent.result?.status,
+                    usage,
+                });
+                if (usage) {
+                    bridge.reportSpawnedUsage?.(usage, {
+                        label: "tmux-worker",
+                        reportId: `tmux-worker:${job.sessionName}:${job.id}:${agent.currentTurn ?? 1}`,
+                    });
+                }
+            }
+            // Production hosts own the sole durable wake path through reportManagedLane. The direct
+            // message remains only for lightweight/standalone hosts that omit that bridge entirely.
+            if (!bridge.reportManagedLane) {
+                pi.sendMessage({
+                    customType: "tmux-background-completion",
+                    content: formatFireTaskHandoff(job),
+                    display: true,
+                    details: {
+                        jobId: job.id,
+                        sessionName: job.sessionName,
+                        agents: job.agents.map((agent) => ({
+                            id: agent.id,
+                            name: agent.name,
+                            status: agent.result?.status,
+                        })),
+                    },
+                }, { triggerTurn: true, deliverAs: "followUp" });
+            }
+            // reportManagedLane persisted the terminal result + outbox synchronously before returning.
+            // This marker only suppresses duplicate extension reports; it is not notification truth.
+            persistJobPatch(job.id, (current) => {
+                current.notifiedAt = new Date().toISOString();
+                for (const agent of current.agents) {
+                    const inMemoryAgent = job.agents.find((entry) => entry.id === agent.id);
+                    agent.notifiedTurn = inMemoryAgent?.currentTurn ?? agent.currentTurn ?? 1;
+                }
+                return current;
+            });
             if (ctx.hasUI)
                 ctx.ui.notify(`tmux background task ${job.id} completed.`, "info");
         }
@@ -1163,6 +1860,7 @@ export default function tmuxAgentManagerExtension(pi) {
     pi.on("session_start", async (_event, ctx) => {
         handoffContext = ctx;
         closeJobWatchers();
+        reconcileTmuxSessions(ctx, bridge);
         await queueJobHandoffRefresh(ctx);
     });
     pi.on("session_shutdown", async () => {
@@ -1180,9 +1878,14 @@ export default function tmuxAgentManagerExtension(pi) {
             "Prefer action=fire_task for interactive worker batches. It returns after event watchers and prompts are armed; do not wait, poll, or peek for completion.",
             "Use action=list_templates/show_template before assembling repeated teams; pass teamTemplate when a built-in team fits.",
             "Use action=workspace_plan before launch_workspace when designing a pane layout.",
+            "Use action=send_followup to re-inject a new prompt into a live fire_task job's pane mid-run, without relaunching. It re-arms the completion watcher for a fresh turn and reuses the same event-driven handoff.",
+            "Use action=dismiss to stop tracking a job without killing its tmux session; the pane keeps running and can still be attached to or stopped later with stop_job/stop_session.",
             "Use stop_job/stop_session dry-run first, then confirm=yes-tmux-stop for real cleanup.",
             "Do not put secrets in task text or command strings; prompts, commands, and logs persist under ~/.pi/agent/work/background/tmux-agent-manager/state/jobs.",
             "tmux display/status actions are metadata only; validate worker result/log files before claiming task completion.",
+            "fire_task and send_followup are APPROVAL-GATED: a real (non-dryRun) dispatch needs either a standing grant (action=grant_dispatch, once per session/goal) or a one-shot interactive approval. With no grant and no UI available, the dispatch is refused, never silent — run grant_dispatch first.",
+            "Use action=grant_dispatch to authorize repeated unattended dispatch: set agent, maxLaunches, and optionally goalId/allowedTools/resourceProfile/writePaths/expiresInMinutes. Requires interactive confirmation, or the --allow-tmux-dispatch flag when no UI is available. Use action=revoke_grant to end it early.",
+            "A grant-covered pi child launches with a RESTRICTED profile (--tools/--resource-profile or --no-extensions --no-skills, plus a scoped --append-system-prompt naming the grant and its hard stops) — the envelope lives in the CHILD's own launch config, not an in-process sandbox. Non-pi agents (agy/claude/codex/opencode/custom) are bounded by the grant at launch only; their internal tool loop is that CLI's own responsibility.",
         ],
         parameters: Type.Object({
             action: Type.Optional(Type.Union([
@@ -1195,6 +1898,8 @@ export default function tmuxAgentManagerExtension(pi) {
                 Type.Literal("workspace_plan"),
                 Type.Literal("launch_workspace"),
                 Type.Literal("fire_task"),
+                Type.Literal("send_followup"),
+                Type.Literal("dismiss"),
                 Type.Literal("job_status"),
                 Type.Literal("list_jobs"),
                 Type.Literal("set_variable"),
@@ -1203,8 +1908,10 @@ export default function tmuxAgentManagerExtension(pi) {
                 Type.Literal("show_template"),
                 Type.Literal("stop_job"),
                 Type.Literal("stop_session"),
+                Type.Literal("grant_dispatch"),
+                Type.Literal("revoke_grant"),
             ], {
-                description: "status, setup_help, guard, notify, set_status, clear_status, workspace_plan, launch_workspace, fire_task, job_status, list_jobs, set_variable, list_variables, list_templates, show_template, stop_job, or stop_session. Default status.",
+                description: "status, setup_help, guard, notify, set_status, clear_status, workspace_plan, launch_workspace, fire_task, send_followup, dismiss, job_status, list_jobs, set_variable, list_variables, list_templates, show_template, stop_job, stop_session, grant_dispatch, or revoke_grant. Default status.",
             })),
             title: Type.Optional(Type.String({ description: "Notification title or workspace title context." })),
             body: Type.Optional(Type.String({ description: "Notification body/status text, or fallback task text for fire_task." })),
@@ -1225,10 +1932,13 @@ export default function tmuxAgentManagerExtension(pi) {
                 description: "Built-in team template name for workspace/fire_task, or target for show_template. Use list_templates first. Current templates include provider-prompt-smoke, full-provider-review, builder-validator, plus JSON templates under templates/.",
             })),
             task: Type.Optional(Type.String({
-                description: "Fire-and-forget worker objective. Required for fire_task unless body is provided.",
+                description: "Fire-and-forget worker objective. Required for fire_task unless body is provided. Also used as the follow-up objective for send_followup.",
             })),
             jobId: Type.Optional(Type.String({
-                description: "Job id for fire_task (optional), job_status/list_variables/set_variable (required).",
+                description: "Job id for fire_task (optional), job_status/list_variables/set_variable/send_followup/dismiss (required).",
+            })),
+            agentId: Type.Optional(Type.String({
+                description: "Target agent id for send_followup. Defaults to the job's first (primary) agent. Multi-agent-per-turn follow-up is not supported; only one agent's pane receives each follow-up.",
             })),
             variableName: Type.Optional(Type.String({
                 description: "For set_variable: named condition/decision variable workers read only at the decision point.",
@@ -1261,9 +1971,43 @@ export default function tmuxAgentManagerExtension(pi) {
                 description: "For fire_task only: archive an existing job directory with the same jobId before launch. Existing tmux sessions are still refused; stop them first.",
             })),
             confirm: Type.Optional(Type.String({ description: "Required for real stop_job/stop_session: yes-tmux-stop." })),
+            goalId: Type.Optional(Type.String({
+                description: "Goal this dispatch/grant is scoped to. For grant_dispatch: an unscoped grant (omitted) covers any goal; a scoped grant covers only launches naming the same goalId. For fire_task/send_followup: tags the request for grant-coverage matching.",
+            })),
+            agent: Type.Optional(Type.Union([
+                Type.Literal("pi"),
+                Type.Literal("codex"),
+                Type.Literal("agy"),
+                Type.Literal("claude"),
+                Type.Literal("opencode"),
+                Type.Literal("custom"),
+            ], { description: "grant_dispatch: the provider this standing grant authorizes." })),
+            allowedTools: Type.Optional(Type.Array(Type.String(), {
+                description: "grant_dispatch: tool allowlist pushed into the child pi's own --tools flag. Defaults to a read-biased safe set (read, grep, find, ls) when omitted.",
+            })),
+            resourceProfile: Type.Optional(Type.String({
+                description: "grant_dispatch: resource profile name pushed into the child pi's own --resource-profile flag. When omitted, the child launches with --no-extensions --no-skills instead.",
+            })),
+            writePaths: Type.Optional(Type.Array(Type.String(), {
+                description: "grant_dispatch: write paths named in the child's scoped --append-system-prompt role text.",
+            })),
+            maxLaunches: Type.Optional(Type.Number({
+                description: "grant_dispatch: number of real fire_task/send_followup dispatches this grant authorizes.",
+                minimum: 1,
+            })),
+            expiresInMinutes: Type.Optional(Type.Number({
+                description: "grant_dispatch: grant validity window from creation. Omit for a grant that never expires (until revoke_grant).",
+                minimum: 1,
+            })),
+            maxUsdAdvisory: Type.Optional(Type.Number({
+                description: "grant_dispatch: advisory USD ceiling. Never enforced across the process boundary (the child bills under its own auth) — a claim to review only.",
+            })),
+            grantId: Type.Optional(Type.String({
+                description: "revoke_grant: grant id to revoke. Omit to revoke whichever grant is currently active.",
+            })),
         }),
         async execute(toolCallId, params, signal, onUpdate, ctx) {
-            const result = await executeTool(toolCallId, params, signal, onUpdate, ctx);
+            const result = await executeTool(toolCallId, params, signal, onUpdate, ctx, bridge);
             await queueJobHandoffRefresh(ctx);
             return result;
         },