@caupulican/pi-adaptative 0.81.38 → 0.81.40

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

@@ -4,9 +4,37 @@ import * as fs from "node:fs";
 import { homedir } from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { type ExtensionAPI, type ExtensionContext, getProcessWorkRun } from "@caupulican/pi-adaptative";
+import {
+	type ExtensionAPI,
+	type ExtensionContext,
+	getProcessWorkRun,
+	PI_ORCHESTRATION_AGENT_ID_ENV,
+} from "@caupulican/pi-adaptative";
 import type { AgentToolResult } from "@caupulican/pi-agent-core";
+import type { Usage } from "@caupulican/pi-ai";
 import { Type } from "typebox";
+import {
+	buildGrant,
+	buildGrantUsageEntry,
+	buildLaunchProfileFlags,
+	buildTombstone,
+	countGrantUsages,
+	DEFAULT_READ_BIASED_TOOLS,
+	decodeTmuxWorkerUsageClaim,
+	describeGrant,
+	GRANT_CUSTOM_TYPE,
+	GRANT_USAGE_CUSTOM_TYPE,
+	type GrantDispatchParams,
+	grantCovers,
+	isTmuxDispatchGrant,
+	isTmuxDispatchGrantTombstone,
+	type LaunchProfileFlag,
+	type LaunchProfileSource,
+	launchProfileSourceFromGrant,
+	ONE_SHOT_LAUNCH_PROFILE_SOURCE,
+	type Provider,
+	type TmuxDispatchGrant,
+} from "./dispatch-grant.ts";
 
 export const piConfig = { tools: ["tmux_agent_manager"] };
 
@@ -20,6 +48,8 @@ type Action =
 	| "workspace_plan"
 	| "launch_workspace"
 	| "fire_task"
+	| "send_followup"
+	| "dismiss"
 	| "job_status"
 	| "list_jobs"
 	| "set_variable"
@@ -27,10 +57,25 @@ type Action =
 	| "list_templates"
 	| "show_template"
 	| "stop_job"
-	| "stop_session";
-type Provider = "pi" | "codex" | "agy" | "claude" | "opencode" | "custom";
+	| "stop_session"
+	| "grant_dispatch"
+	| "revoke_grant";
 
-type AgentSpec = { provider?: Provider; name?: string; command?: string; cwd?: string; tools?: string[] };
+type AgentSpec = {
+	provider?: Provider;
+	name?: string;
+	command?: string;
+	cwd?: string;
+	tools?: string[];
+	/**
+	 * Worktree-sync lane key this agent is bound to (core-internal only -- set by the goal->tmux
+	 * lane-first dispatch adapter, `tmux-dispatch.ts`'s `dispatchTmuxWorker`, never by the model's own
+	 * `fire_task` params). A `provider:"pi"` agent carrying this launches with `--worktree-lane <key>`
+	 * appended and one extra lane-doctrine sentence in its scoped `--append-system-prompt` -- see
+	 * `applyLaunchProfile`/`dispatch-grant.ts`'s `buildLaunchProfileFlags`.
+	 */
+	worktreeLane?: string;
+};
 type TeamTemplate = {
 	name: string;
 	description: string;
@@ -53,12 +98,33 @@ type Params = {
 	teamTemplate?: string;
 	task?: string;
 	jobId?: string;
+	agentId?: string;
 	variableName?: string;
 	variableValue?: string;
 	deadlineSeconds?: number;
 	dryRun?: boolean;
 	force?: boolean;
 	confirm?: string;
+	/** Goal this dispatch/grant is scoped to. Goal-bound dispatch wires this through to grant
+	 * coverage, managed-lane ownership, and the child process's task-recovery fence. */
+	goalId?: string;
+	/** grant_dispatch: target agent for the standing grant. revoke_grant: unused (the active grant's own
+	 * agent is used for its tombstone; this field is not required to revoke). */
+	agent?: Provider;
+	/** grant_dispatch: allowlisted tool names pushed into the child `pi`'s own --tools flag. */
+	allowedTools?: string[];
+	/** grant_dispatch: resource profile name pushed into the child `pi`'s own --resource-profile flag. */
+	resourceProfile?: string;
+	/** grant_dispatch: write paths the grant's scoped system prompt tells the child worker to stay within. */
+	writePaths?: string[];
+	/** grant_dispatch: number of real launches (fire_task/send_followup dispatches) this grant authorizes. */
+	maxLaunches?: number;
+	/** grant_dispatch: grant validity window from creation time. Omit for a grant that never expires (until revoke_grant). */
+	expiresInMinutes?: number;
+	/** grant_dispatch: advisory USD ceiling. Never enforced across the process boundary — a claim to review only. */
+	maxUsdAdvisory?: number;
+	/** revoke_grant: grantId to revoke. Optional — omitted means "revoke whichever grant is currently active". */
+	grantId?: string;
 };
 
 type RunResult = { ok: boolean; status: number | null; stdout: string; stderr: string; error?: string; args: string[] };
@@ -92,6 +158,25 @@ type FireAgentPlan = {
 	resultPath: string;
 	paneId?: string;
 	result?: AgentResult;
+	/** Last turn dispatched to this agent's pane via fire_task (1) or send_followup (>=2). Absent means 1. */
+	currentTurn?: number;
+	/** Last turn whose terminal handoff was delivered to the parent. Absent means 0 (never notified). */
+	notifiedTurn?: number;
+	/** A follow-up turn durably reserved before its prompt is injected. Reconciliation may re-arm its
+	 * watcher, but never re-injects it: a retry must not duplicate an uncertain external side effect. */
+	pendingTurn?: number;
+	/** Mirrors `AgentSpec.worktreeLane` -- carried onto the plan so `applyLaunchProfile` (per-agent
+	 * flags) and the dispatch-phase `reportManagedLane` call can both read it after `buildFireTaskPlan`. */
+	worktreeLane?: string;
+	/** Durable host-lifecycle metadata for the current turn. */
+	dispatchAuthorizationId?: string;
+	dispatchAuthorizationKind?: "standing-grant" | "one-shot-owner-approval" | "legacy-recovery";
+	dispatchAllowedTools?: string[];
+	dispatchWritePaths?: string[];
+	dispatchMaxCostUsd?: number;
+	dispatchInstructions?: string;
+	dispatchGoalId?: string;
+	dispatchLeaseTtlMs?: number;
 };
 type FireTaskPlan = {
 	id: string;
@@ -111,7 +196,185 @@ type FireTaskPlan = {
 	agents: FireAgentPlan[];
 	launchCommands: string[];
 	variables?: VariableState;
+	/** Mirrors the follow-up target agent's currentTurn, for external observability (job_status). */
+	currentTurn?: number;
+	/** Set when session-level reconcile finds the tmux session gone while the job was not terminal. Informational only; nothing is ever killed to produce this state. */
+	orphanedAt?: string;
+	/** Set by action=dismiss: the manager stops tracking/re-arming this job. The tmux session is left running. */
+	dismissedAt?: string;
+};
+/** The subset of FireTaskPlan the pane watcher generator actually reads — narrow on purpose so a
+ * synthesized single-agent, single-turn spec (send_followup, reconcile resume) can reuse it without
+ * fabricating unrelated FireTaskPlan fields (createdAt, jobPath, task, ...). */
+type PaneWatcherJobSpec = Pick<FireTaskPlan, "id" | "sessionName" | "deadlineSeconds" | "agents">;
+type ManagedLaneDispatchBridge = {
+	sequence: number;
+	instructions: string;
+	profileId: string;
+	provider: string;
+	authorizationId: string;
+	authorizationKind: "standing-grant" | "one-shot-owner-approval" | "legacy-recovery";
+	allowedTools: readonly string[];
+	writePaths: readonly string[];
+	maxCostUsd?: number;
+	leaseTtlMs: number;
 };
+type ManagedLaneBridgeEventBase = {
+	laneId: string;
+	goalId?: string;
+	worktreeLaneKey?: string;
+};
+type ManagedLaneBridgeEvent =
+	| (ManagedLaneBridgeEventBase & { phase: "dispatch"; dispatch: ManagedLaneDispatchBridge })
+	| (ManagedLaneBridgeEventBase & {
+			phase: "terminal";
+			status?: string;
+			reasonCode?: string;
+			changedFiles?: string[];
+			usage?: Usage;
+	  });
+/** The subset of `ExtensionAPI` this file calls through a narrow local type instead of the full
+ * `ExtensionAPI`, so a lightweight test double only needs to implement what a given test path actually
+ * exercises. Production hosts provide `reportManagedLane`, making its pre-launch durable reservation a
+ * hard gate. The optional shape only preserves standalone extension-test hosts; without the bridge,
+ * lifecycle durability is explicitly unavailable. `reportSpawnedUsage` remains an advisory claim sink.
+ * `appendEntry`/`getFlag`/`registerFlag` back the STANDING GRANT itself (session persistence + the
+ * non-interactive opt-in flag); `registerFlag` is called unconditionally at extension load so it stays
+ * optional-chained too, while `appendEntry`/`getFlag` are asserted present at the point a grant action
+ * actually needs them (a host that can't persist a grant should fail that action clearly, not pretend). */
+type HostBridge = {
+	reportManagedLane?: (event: ManagedLaneBridgeEvent) => void;
+	reportSpawnedUsage?: (usage: Usage, opts?: { label?: string; sourceSessionId?: string; reportId?: string }) => void;
+	appendEntry?: (customType: string, data?: unknown) => void;
+	getFlag?: (name: string) => boolean | string | undefined;
+	registerFlag?: (
+		name: string,
+		options: { description?: string; type: "boolean" | "string"; default?: boolean | string },
+	) => void;
+};
+function agentLaneId(jobId: string, agentId: string): string {
+	return `tmux:${jobId}:${agentId}`;
+}
+
+function managedDispatch(job: FireTaskPlan, agent: FireAgentPlan): ManagedLaneDispatchBridge {
+	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: TmuxDispatchGrant | undefined,
+	fallbackId: string,
+): {
+	authorizationId: string;
+	authorizationKind: "standing-grant" | "one-shot-owner-approval";
+	launchSource: LaunchProfileSource;
+	allowedTools: string[];
+	writePaths: string[];
+	maxCostUsd?: number;
+} {
+	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: FireAgentPlan,
+	authorization: ReturnType<typeof managedAuthorization>,
+	args: { instructions: string; goalId?: string; leaseTtlMs: number },
+): void {
+	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: HostBridge,
+	job: FireTaskPlan,
+	agents: readonly FireAgentPlan[],
+): void {
+	if (!bridge.reportManagedLane) return;
+	const attemptedLaneIds: string[] = [];
+	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: unknown) {
+		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: HostBridge, job: FireTaskPlan, reasonCode: string): void {
+	if (!bridge.reportManagedLane) return;
+	for (const agent of job.agents) {
+		reportManagedAgentFailure(bridge, job.id, agent.id, reasonCode);
+	}
+}
+
+function reportManagedAgentFailure(bridge: HostBridge, jobId: string, agentId: string, reasonCode: string): void {
+	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: readonly string[], right: readonly string[]): boolean {
+	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(): string {
@@ -266,6 +529,9 @@ function runTmux(args: string[], timeoutMs = 5_000): RunResult {
 		args: [tmux, ...args],
 	};
 }
+function requireTmuxRun(result: RunResult, action: string): void {
+	if (!result.ok) throw new Error(`${action} failed: ${result.error || result.stderr || `exit ${result.status}`}`);
+}
 function detectTmux(): TmuxDetection {
 	const tmuxBin = process.env.PI_TMUX_MANAGER_TMUX_BIN || findExecutable("tmux");
 	const errors: string[] = [];
@@ -431,7 +697,7 @@ function normalizeAgents(params: Params): AgentSpec[] {
 		if (!baseCommand) 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: Provider): string {
@@ -500,7 +766,7 @@ function buildWorkspacePlan(ctx: ExtensionContext, params: Params) {
 	);
 	return { workspaceName, sessionName, cwd, agents, launchCommands };
 }
-export function makePaneWatcherScript(job: FireTaskPlan): string {
+export function makePaneWatcherScript(job: PaneWatcherJobSpec): string {
 	const agentCases = job.agents.flatMap((agent) => [
 		`  ${agent.id})`,
 		`    agent_name=${quoteShell(agent.name)}`,
@@ -639,6 +905,7 @@ function buildFireTaskPlan(ctx: ExtensionContext, params: Params): FireTaskPlan
 			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: FireTaskPlan = {
@@ -731,9 +998,78 @@ function targetDisplayName(agent: AgentSpec, index: number): string {
 function tmuxSessionExists(name: string): boolean {
 	return runTmux(["has-session", "-t", name], 2_000).ok;
 }
+function tmuxPaneExists(sessionName: string, paneId: string): boolean {
+	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: string): boolean {
+	const result = runTmux(["display-message", "-p", "-t", paneId, "#{pane_pipe}"], 2_000);
+	return result.ok && result.stdout.trim() === "1";
+}
+function turnMarkers(
+	job: PaneWatcherJobSpec,
+	agent: FireAgentPlan,
+	turn: number,
+): { doneMarker: string; blockedMarker: string } {
+	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: string, agentId: string, turn: number, baseResultPath: string): string {
+	return turn <= 1 ? baseResultPath : path.join(jobDir, `${agentId}.turn-${turn}.result.json`);
+}
+function turnPromptPath(jobDir: string, agentId: string, turn: number, basePromptPath: string): string {
+	return turn <= 1 ? basePromptPath : path.join(jobDir, `${agentId}.turn-${turn}.prompt.md`);
+}
+function turnWatcherPath(job: FireTaskPlan, turn: number): string {
+	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: FireTaskPlan, agent: FireAgentPlan): string {
+	return turnResultPath(job.jobDir, agent.id, agent.currentTurn ?? 1, agent.resultPath);
+}
+
+function persistAgentTurnFailure(jobId: string, agentId: string, turn: number, reason: string): void {
+	persistJobPatch(jobId, (current) => {
+		const agent = current.agents.find((entry) => entry.id === agentId);
+		if (!agent || agent.currentTurn !== turn) return undefined;
+		const result: AgentResult = {
+			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: string, mutate: (current: FireTaskPlan) => FireTaskPlan | undefined): FireTaskPlan {
+	const jobPath = path.join(jobsRoot(), jobId, "job.json");
+	const current = JSON.parse(fs.readFileSync(jobPath, "utf8")) as FireTaskPlan;
+	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: string, command: string): void {
-	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: string,
@@ -754,36 +1090,114 @@ function launchTmuxSession(
 	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: unknown) {
+		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: string, prompt: string, provider: Provider): void {
 	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: FireTaskPlan,
+	agent: FireAgentPlan,
+	turn: number,
+	promptText: string,
+): { promptPath: string; resultPath: string; watcherPath: string } {
+	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: PaneWatcherJobSpec = {
+		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: FireTaskPlan, agent: FireAgentPlan): void {
+	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: PaneWatcherJobSpec = {
+			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: string,
@@ -804,9 +1218,10 @@ function isAlreadyExistsError(error: unknown): boolean {
 }
 function markStopRequested(job: FireTaskPlan): void {
 	for (const agent of job.agents) {
-		if (fs.existsSync(agent.resultPath)) continue;
+		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",
@@ -817,11 +1232,12 @@ function markStopRequested(job: FireTaskPlan): void {
 	}
 }
 function clearStopRequested(job: FireTaskPlan): void {
-	for (const agent of job.agents) fs.rmSync(`${agent.resultPath}.stop-requested`, { force: true });
+	for (const agent of job.agents) fs.rmSync(`${currentResultPath(job, agent)}.stop-requested`, { force: true });
 }
 function persistStoppedResults(job: FireTaskPlan): void {
 	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,
@@ -834,7 +1250,7 @@ function persistStoppedResults(job: FireTaskPlan): void {
 				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",
@@ -843,7 +1259,7 @@ function persistStoppedResults(job: FireTaskPlan): void {
 				if (!isAlreadyExistsError(error)) throw error;
 			}
 		}
-		fs.rmSync(`${agent.resultPath}.stop-requested`, { force: true });
+		fs.rmSync(`${resultPath}.stop-requested`, { force: true });
 	}
 }
 function stopTmuxSessionWithJobSignals(
@@ -888,8 +1304,10 @@ function loadJob(id: string): FireTaskPlan {
 	const parsed = JSON.parse(fs.readFileSync(jobPath, "utf8")) as FireTaskPlan;
 	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")) as AgentResult;
+			agent.result = JSON.parse(fs.readFileSync(currentResultPath(parsed, agent), "utf8")) as AgentResult;
 		} catch {
 			delete agent.result;
 		}
@@ -930,7 +1348,13 @@ function listJobs(): unknown[] {
 						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: unknown) {
 					return { id: d.name, error: errorMessage(error) };
@@ -957,12 +1381,130 @@ function setVariable(jobId: string, name: string, value: string) {
 	fs.writeFileSync(job.varsPath, `${JSON.stringify(current, null, 2)}\n`, { mode: 0o600 });
 	return { varsPath: job.varsPath, variables: current.variables, updatedAt: current.updatedAt };
 }
+// ---------------------------------------------------------------------------
+// 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: ExtensionContext): TmuxDispatchGrant | undefined {
+	let fromId: string | undefined;
+	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: ExtensionContext, customType: string): unknown[] {
+	const result: unknown[] = [];
+	for (const entry of ctx.sessionManager.getBranch()) {
+		const loose = entry as unknown as { type?: string; customType?: string; data?: unknown };
+		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: HostBridge,
+	ctx: ExtensionContext,
+	request: { agents: readonly Provider[]; goalId?: string; jobId: string; description: string },
+): Promise<{ grant?: TmuxDispatchGrant }> {
+	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: string, flags: LaunchProfileFlag[]): string {
+	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: FireTaskPlan, source: LaunchProfileSource): void {
+	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: FireTaskPlan, agent: FireAgentPlan): Usage | undefined {
+	const usagePath = `${currentResultPath(job, agent)}.usage.json`;
+	try {
+		return decodeTmuxWorkerUsageClaim(JSON.parse(fs.readFileSync(usagePath, "utf8")));
+	} catch {
+		return undefined;
+	}
+}
+
 async function executeTool(
 	_toolCallId: string,
 	params: Params,
 	_signal: AbortSignal | undefined,
 	_onUpdate: unknown,
 	ctx: ExtensionContext,
+	bridge: HostBridge,
 ): Promise<AgentToolResult<unknown>> {
 	const action = params.action || "status";
 	const detection = detectTmux();
@@ -1015,6 +1557,62 @@ async function executeTool(
 			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: GrantDispatchParams = {
+			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 } };
@@ -1079,39 +1677,227 @@ async function executeTool(
 			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: unknown) {
+			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: unknown) {
+			persistAgentTurnFailure(job.id, reservedAgent.id, turn, "managed_process_launch_reservation_failed");
+			throw error;
+		}
+		let written: ReturnType<typeof dispatchAgentTurn>;
+		try {
+			written = dispatchAgentTurn(reserved, reservedAgent, turn, promptText);
+			injectPromptToPane(reservedAgent.paneId as string, 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: unknown) {
+			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, 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, detection, job, runs: launch.runs, paneIds: launch.paneIds, watcherPanes, archivedJobDir },
+			details: { action, jobId: job.id, sessionName: job.sessionName },
 		};
 	}
 	if (action === "notify") {
@@ -1193,19 +1979,71 @@ function formatFireTaskHandoff(job: FireTaskPlan): string {
 	].join("\n");
 }
 
-function markFireTaskNotified(job: FireTaskPlan): void {
-	const current = JSON.parse(fs.readFileSync(job.jobPath, "utf8")) as FireTaskPlan;
-	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: ExtensionContext, bridge: HostBridge): void {
+	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: ExtensionAPI) {
 	let handoffContext: ExtensionContext | undefined;
 	let handoffTail = Promise.resolve();
 	const jobWatchers = new Map<string, fs.FSWatcher>();
+	const bridge: HostBridge = 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();
@@ -1214,23 +2052,64 @@ export default function tmuxAgentManagerExtension(pi: ExtensionAPI) {
 
 	const refreshJobHandoffs = async (ctx: ExtensionContext): Promise<void> => {
 		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) 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 })),
+			if (!isFireTaskTerminal(job)) continue;
+			// 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" },
-			);
-			markFireTaskNotified(job);
+					{ 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");
 		}
 
@@ -1277,6 +2156,7 @@ export default function tmuxAgentManagerExtension(pi: ExtensionAPI) {
 	pi.on("session_start", async (_event, ctx) => {
 		handoffContext = ctx;
 		closeJobWatchers();
+		reconcileTmuxSessions(ctx, bridge);
 		await queueJobHandoffRefresh(ctx);
 	});
 	pi.on("session_shutdown", async () => {
@@ -1297,9 +2177,14 @@ export default function tmuxAgentManagerExtension(pi: ExtensionAPI) {
 			"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(
@@ -1314,6 +2199,8 @@ export default function tmuxAgentManagerExtension(pi: ExtensionAPI) {
 						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"),
@@ -1322,10 +2209,12 @@ export default function tmuxAgentManagerExtension(pi: ExtensionAPI) {
 						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.",
+							"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.",
 					},
 				),
 			),
@@ -1367,12 +2256,20 @@ export default function tmuxAgentManagerExtension(pi: ExtensionAPI) {
 			),
 			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(
@@ -1432,9 +2329,69 @@ export default function tmuxAgentManagerExtension(pi: ExtensionAPI) {
 			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 as Params, signal, onUpdate, ctx);
+			const result = await executeTool(toolCallId, params as Params, signal, onUpdate, ctx, bridge);
 			await queueJobHandoffRefresh(ctx);
 			return result;
 		},