@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/scripts/real-pi-smoke.mjs

@@ -1,27 +1,15 @@
 #!/usr/bin/env node
-import {
-  copyFileSync,
-  existsSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname, join, resolve, relative, isAbsolute } from "node:path";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
 import process from "node:process";
-import { setTimeout as delay } from "node:timers/promises";
-import { isChildTreeAlive } from "../src/shared/post-exit-stdio-guard.ts";
-import { SmokeProcesses, filesIn, processRef } from "./real-pi-processes.mjs";
+import { runLiveSmoke } from "./real-pi-live.mjs";
+import { SmokeProcesses } from "./real-pi-processes.mjs";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
-const authAgentDir =
-  process.env.PI_REAL_SMOKE_AUTH_AGENT_DIR ??
-  (process.env.HOME ? join(process.env.HOME, ".pi", "agent") : undefined);
 
 function usage() {
   console.log(
-    `Usage: node scripts/real-pi-smoke.mjs [--llm] [--llm-full] [--keep-temp] [--timeout-ms <ms>]\n\nRuns an opt-in real Pi package smoke for this checkout. It uses an isolated\ntemporary Pi home, installs the single pi-subagents package with bundled intercom, verifies pi list,\nand loads the single compiled entry. It does not install pi-fitch-kit, publish anything,\nor create GitHub Actions.\n\nOptions:\n  --llm             Also run live model-backed list, foreground, and async-completion smoke prompts\n  --llm-full        Also verify forked tool-result context and saved-conversation continuation\n  --keep-temp       Keep the isolated temporary home for debugging\n  --timeout-ms <ms> Per-command timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS})\n  -h, --help        Show this help\n\nEnvironment:\n  PI_REAL_SMOKE_AUTH_AGENT_DIR     Source Pi agent dir for auth.json/models.json during --llm (default: ~/.pi/agent)\n  PI_REAL_SMOKE_MODEL              Model passed to live --llm smoke prompts, e.g. openai/gpt-6-astra\n  PI_REAL_SMOKE_PROVIDER           Provider passed to live --llm smoke prompts\n\nExit codes:\n  0  real Pi smoke passed\n  1  install/list/live smoke failed\n  2  invalid arguments`,
+    `Usage: node scripts/real-pi-smoke.mjs [--llm] [--llm-full] [--keep-temp] [--timeout-ms <ms>]\n\nRuns an opt-in real Pi package smoke for this checkout. It uses an isolated\ntemporary Pi home, installs the single pi-subagents package with bundled intercom, verifies pi list,\nand loads the single compiled entry. It does not install pi-fitch-kit, publish anything,\nor create GitHub Actions.\n\nOptions:\n  --llm             Also run live model-backed intercom, list, and delegate prompts in a persistent RPC main\n                    that stays open until each launch receipt's completion notification resumes it\n  --llm-full        Also verify forked completion context and saved-conversation continuation\n  --keep-temp       Keep the isolated temporary home for debugging\n  --timeout-ms <ms> Per-command timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS})\n  -h, --help        Show this help\n\nEnvironment:\n  PI_REAL_SMOKE_AUTH_AGENT_DIR     Source Pi agent dir for auth.json/models.json during --llm (default: ~/.pi/agent)\n  PI_REAL_SMOKE_MODEL              Model passed to live --llm smoke prompts, e.g. openai/gpt-6-astra\n  PI_REAL_SMOKE_PROVIDER           Provider passed to live --llm smoke prompts\n\nExit codes:\n  0  real Pi smoke passed\n  1  install/list/live smoke failed\n  2  invalid arguments`,
   );
 }
 
@@ -75,23 +63,6 @@ function parseArgs(argv) {
   return options;
 }
 
-function copyLiveAuth(agentDir) {
-  if (!authAgentDir || !existsSync(authAgentDir)) {
-    return [];
-  }
-  mkdirSync(agentDir, { recursive: true });
-  const copied = [];
-  for (const filename of ["auth.json", "models.json"]) {
-    const source = join(authAgentDir, filename);
-    if (!existsSync(source)) {
-      continue;
-    }
-    copyFileSync(source, join(agentDir, filename));
-    copied.push(filename);
-  }
-  return copied;
-}
-
 function isolatedEnv(root, agentDir) {
   const home = join(root, "home");
   const env = { ...process.env };
@@ -176,253 +147,6 @@ function registeredCommands(response) {
     : [];
 }
 
-async function runLivePrompt(label, prompt, options, expectedTool) {
-  const args = [
-    "--print",
-    "--mode",
-    "json",
-    "--session-dir",
-    join(options.root, "sessions"),
-    "--approve",
-  ];
-  if (process.env.PI_REAL_SMOKE_PROVIDER) {
-    args.push("--provider", process.env.PI_REAL_SMOKE_PROVIDER);
-  }
-  if (process.env.PI_REAL_SMOKE_MODEL) {
-    args.push(
-      "--model",
-      process.env.PI_REAL_SMOKE_MODEL,
-      "--models",
-      process.env.PI_REAL_SMOKE_MODEL,
-    );
-  }
-  args.push(prompt);
-  const output = await runPi(label, args, options);
-  writeFileSync(join(options.root, `${label.replace(/ /g, "-")}.jsonl`), output);
-  const events = output.split("\n").flatMap((line) => {
-    try {
-      return [JSON.parse(line)];
-    } catch {
-      return [];
-    }
-  });
-  if (
-    !events.some(
-      (event) => event.type === "tool_execution_start" && event.toolName === expectedTool,
-    )
-  ) {
-    throw new Error(
-      `${label} never invoked ${expectedTool}; a matching final sentence is not execution evidence.`,
-    );
-  }
-  const errors = events.filter((event) => event.type === "tool_execution_end" && event.isError);
-  if (errors.length) {
-    throw new Error(
-      `${label} had ${errors.length} failed tool call(s); inspect its saved wire log.`,
-    );
-  }
-  if (!events.some((event) => event.type === "agent_settled")) {
-    throw new Error(`${label} did not reach agent_settled.`);
-  }
-  return {
-    events,
-    text: events
-      .filter((event) => event.type === "message_end" && event.message?.role === "assistant")
-      .flatMap((event) =>
-        event.message.content.filter((part) => part.type === "text").map((part) => part.text),
-      )
-      .join("\n"),
-  };
-}
-
-function* savedAssistantModels(file) {
-  for (const line of readFileSync(file, "utf8").split("\n")) {
-    if (!line.trim()) {
-      continue;
-    }
-    const entry = JSON.parse(line);
-    if (entry.type === "message" && entry.message?.role === "assistant") {
-      yield `${entry.message.provider}/${entry.message.model}`;
-    }
-  }
-}
-
-function auditSavedModels(directories, expectedModel) {
-  const models = new Set();
-  let responses = 0;
-  for (const file of directories.flatMap((dir) => [...filesIn(dir)])) {
-    if (!file.endsWith(".jsonl")) {
-      continue;
-    }
-    for (const model of savedAssistantModels(file)) {
-      responses++;
-      models.add(model);
-    }
-  }
-  if (!responses) {
-    throw new Error("No saved assistant messages found for model audit.");
-  }
-  if (expectedModel?.includes("/") && [...models].some((model) => model !== expectedModel)) {
-    throw new Error(`Unexpected model in saved parent/child sessions: ${[...models].join(", ")}`);
-  }
-  console.log(
-    `[real-pi-smoke] audited ${responses} saved parent/child responses: ${[...models].join(", ")}`,
-  );
-}
-
-function requireOutput(label, output, pattern) {
-  if (!pattern.test(output)) {
-    throw new Error(`${label} did not include expected evidence ${pattern}.\nOutput:\n${output}`);
-  }
-  const compact = output.trim().split(/\r?\n/).slice(-8).join("\n");
-  console.log(`[real-pi-smoke] ${label} output evidence:\n${compact}`);
-}
-
-function asyncCompletion(dir, runId) {
-  const resultPath = join(dir, "result.json");
-  if (!existsSync(resultPath)) {
-    return { status: "missing" };
-  }
-  const result = JSON.parse(readFileSync(resultPath, "utf8"));
-  if (result.id !== runId) {
-    throw new Error("Async completion belongs to another saved run");
-  }
-  if (result.status !== "completed") {
-    throw new Error(`async run ${runId} ended ${result.status}: ${result.error ?? ""}`);
-  }
-  const processPath = join(dir, "actor.lock", "process.json");
-  if (!existsSync(processPath)) {
-    return { status: "completed; actor exit unconfirmed" };
-  }
-  const actor = JSON.parse(readFileSync(processPath, "utf8"));
-  return {
-    status: result.status,
-    output: isChildTreeAlive(processRef(actor.pid))
-      ? undefined
-      : readFileSync(join(dir, "output.txt"), "utf8"),
-  };
-}
-
-async function waitForAsyncCompletion(run, pattern, { env, timeoutMs, signal }) {
-  const dir = dirname(run.sessionFile);
-  const within = relative(join(env.PI_CODING_AGENT_DIR, "sessions", "agent-runs"), dir);
-  if (isAbsolute(within) || within.startsWith("..") || !/^[a-zA-Z0-9_-]{1,128}$/.test(run.id)) {
-    throw new Error("Async receipt did not identify this smoke's private saved run");
-  }
-  const deadline = Date.now() + timeoutMs;
-  let lastState = "missing";
-  while (Date.now() < deadline) {
-    signal.throwIfAborted();
-    const completion = asyncCompletion(dir, run.id);
-    lastState = completion.status;
-    if (completion.output !== undefined) {
-      requireOutput(`async run ${run.id} completed and actor exited`, completion.output, pattern);
-      return;
-    }
-    // Result publication is not process exit; retain resources until final actor writes finish.
-    // oxlint-disable-next-line no-await-in-loop
-    await delay(100, undefined, { signal });
-  }
-  throw new Error(
-    `async run ${run.id} did not complete and exit after ${timeoutMs}ms (last state: ${lastState}).`,
-  );
-}
-
-async function runLiveSmoke(options, runOptions, agentDir) {
-  const copiedAuthFiles = copyLiveAuth(agentDir);
-  if (copiedAuthFiles.length > 0) {
-    console.log(
-      `[real-pi-smoke] copied ${copiedAuthFiles.join(" and ")} into isolated Pi agent dir for live provider auth`,
-    );
-  }
-  const childModelInstruction = process.env.PI_REAL_SMOKE_MODEL
-    ? ` Pass model '${process.env.PI_REAL_SMOKE_MODEL}' to every delegate call.`
-    : "";
-  await runBasicLiveSmoke(runOptions, childModelInstruction);
-  if (options.llmFull) {
-    await runFullLiveSmoke(runOptions, childModelInstruction);
-  }
-  auditSavedModels(
-    [join(runOptions.root, "sessions"), join(agentDir, "sessions", "agent-runs")],
-    process.env.PI_REAL_SMOKE_MODEL,
-  );
-}
-
-function toolDetails(events, name) {
-  return events
-    .filter((event) => event.type === "tool_execution_end" && event.toolName === name)
-    .map((event) => event.result?.details);
-}
-
-function requireCompleted(run, expected) {
-  if (run?.status !== "completed" || run.output?.text !== expected) {
-    throw new Error(`Native child did not complete with expected output: ${expected}`);
-  }
-}
-
-async function runBasicLiveSmoke(runOptions, childModelInstruction) {
-  const prompts = [
-    [
-      "intercom",
-      "Call the intercom tool with action status. Reply exactly 'real-pi-smoke intercom ok' only if it reports 'Connected: Yes'.",
-      "intercom",
-    ],
-    [
-      "list",
-      "Call agent_runs with action list. Reply exactly 'real-pi-smoke list ok' only if it successfully returns a saved-run list. There are no profiles to discover.",
-      "agent_runs",
-    ],
-    [
-      "foreground",
-      `Call delegate with prompt 'Reply exactly: real-pi-smoke foreground ok', name 'smoke-foreground', and async false.${childModelInstruction} Reply exactly 'real-pi-smoke foreground ok' only if the actual child result contains it.`,
-      "delegate",
-    ],
-  ];
-  for (const [kind, prompt, tool] of prompts) {
-    // Keep separate native parent sessions so each smoke owns its saved runs.
-    // oxlint-disable-next-line no-await-in-loop
-    const result = await runLivePrompt(`real Pi ${kind} prompt`, prompt, runOptions, tool);
-    if (kind === "foreground") {
-      requireCompleted(toolDetails(result.events, "delegate")[0], "real-pi-smoke foreground ok");
-    }
-    requireOutput(`real Pi ${kind} prompt`, result.text, new RegExp(`real-pi-smoke ${kind} ok`));
-  }
-  const result = await runLivePrompt(
-    "real Pi async prompt",
-    `Call delegate with prompt 'Reply exactly: real-pi-smoke async ok', name 'smoke-async', and async true.${childModelInstruction} Do not wait or call agent_runs. Reply exactly 'real-pi-smoke async launched ok' after receiving a launch receipt, not claiming completion.`,
-    runOptions,
-    "delegate",
-  );
-  requireOutput("real Pi async prompt", result.text, /real-pi-smoke async launched ok/);
-  const receipt = toolDetails(result.events, "delegate")[0];
-  if (receipt?.receipt !== "launch" || !receipt.id || !receipt.sessionFile) {
-    throw new Error("Native delegate did not return a saved asynchronous launch receipt");
-  }
-  await waitForAsyncCompletion(receipt, /^real-pi-smoke async ok$/m, runOptions);
-}
-
-async function runFullLiveSmoke(runOptions, childModelInstruction) {
-  const prompt = `First call delegate with prompt 'Reply exactly CALIBRATION_FACT=packed-otter-7319', name 'fact', context fresh and async false.${childModelInstruction} Then call delegate with context fork, async false, and prompt 'Read the preceding delegate tool result in inherited conversation. Without tools, filesystem reads, or guessing, return the CALIBRATION_FACT line exactly; return FACT_NOT_VISIBLE if absent.' Finally call agent_runs with action continue, the first saved run id, async false, and prompt 'Without tools, repeat the CALIBRATION_FACT line from your own saved conversation exactly.' Reply exactly 'real-pi-smoke fork ok' only if both the forked child and continued child actually return CALIBRATION_FACT=packed-otter-7319. There are no profiles, task prefixes, output settings, or canned role instructions.`;
-  const result = await runLivePrompt("real Pi fork prompt", prompt, runOptions, "delegate");
-  const delegates = toolDetails(result.events, "delegate");
-  const continuation = toolDetails(result.events, "agent_runs")[0];
-  for (const run of [...delegates, continuation]) {
-    requireCompleted(run, "CALIBRATION_FACT=packed-otter-7319");
-  }
-  if (
-    delegates.length !== 2 ||
-    delegates[0].context !== "fresh" ||
-    delegates[1].context !== "fork" ||
-    continuation.predecessor !== delegates[0].id ||
-    continuation.sessionFile !== delegates[0].sessionFile
-  ) {
-    throw new Error(
-      "Fork/continuation smoke did not execute the two contexts and reuse the first saved conversation",
-    );
-  }
-  requireOutput("real Pi fork prompt", result.text, /real-pi-smoke fork ok/);
-}
-
 function createProject(root) {
   const projectRoot = join(root, "project");
   mkdirSync(projectRoot, { recursive: true });
@@ -479,7 +203,7 @@ async function main() {
     );
     if (!options.llm) {
       console.log(
-        "[real-pi-smoke] live model subagent prompts skipped; pass --llm to exercise foreground/async paths.",
+        "[real-pi-smoke] live model subagent prompts skipped; pass --llm to exercise launch receipts and completion notifications.",
       );
     }
   } finally {

package/scripts/run-tests.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
 import { mkdtempSync, readdirSync, rmSync } from "node:fs";
-import { availableParallelism } from "node:os";
+import { availableParallelism, tmpdir } from "node:os";
 import { join } from "node:path";
 
 // ponytail: integration is sized for the 3-vCPU macOS hosted runner, where the suite takes
@@ -91,7 +91,9 @@ function sanitizedEnv() {
 function runNodeTest(label, files, timeoutMs, concurrency) {
   const args = [...(concurrency ? [`--test-concurrency=${concurrency}`] : []), "--test", ...files];
   const startedAt = Date.now();
-  const tempRoot = mkdtempSync(join("/tmp", "pi-subagents-test-"));
+  const tempRoot = mkdtempSync(
+    join(process.platform === "android" ? tmpdir() : "/tmp", "pi-subagents-"),
+  );
   const env = sanitizedEnv();
   env.PI_SUBAGENT_TEMP_ROOT = tempRoot;
   env.PI_INTERCOM_RUNTIME_DIR = join(tempRoot, "ic");

package/scripts/typescript.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Android's npm compiler package is not published; use its installed native compiler.
+ * @param {string} [script]
+ * @returns {{ command: string, args: string[] }}
+ */
+export function compilerInvocation(script) {
+  if (script === undefined && process.platform === "android") {
+    return { command: "tsgo", args: [] };
+  }
+  const compiler = script ?? join(process.cwd(), "node_modules", "typescript", "bin", "tsc");
+  if (!existsSync(compiler)) {
+    throw new Error(`typescript is not installed at ${compiler}; run npm install first.`);
+  }
+  return { command: process.execPath, args: [compiler] };
+}
+
+if (import.meta.main) {
+  const compiler = compilerInvocation();
+  const result = spawnSync(compiler.command, [...compiler.args, ...process.argv.slice(2)], {
+    stdio: "inherit",
+  });
+  if (result.error) {
+    console.error(
+      process.platform === "android"
+        ? `Cannot run native TypeScript: install an Android build of tsgo on PATH. ${result.error.message}`
+        : result.error.message,
+    );
+  }
+  process.exitCode = result.status ?? 1;
+}

package/skills/pi-intercom/SKILL.md

@@ -56,4 +56,5 @@ persistent supervisor question/approval workflow.
 Old agent-directory brokers may coexist during migration; updated sessions use
 the same-user broker. Do not kill another broker or change runtime configuration
 to force discovery. Only intercom-connected eligible sessions appear, not all
-open Pi processes. See `docs/intercom.md` for broker and persistence contracts.
+open Pi processes. See [local messaging](../../docs/intercom.md) for broker and
+persistence contracts.

package/skills/pi-subagents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pi-subagents
-description: "Delegate one complete assignment to a native Pi child; inspect, continue, wait for, or stop saved child runs. Use for Pi delegation, not profile administration or non-Pi agents."
+description: "Delegate one complete assignment to a native Pi child; inspect, continue, or stop saved child runs. Use for Pi delegation, not profile administration or non-Pi agents."
 ---
 
 # Pi delegation
@@ -25,19 +25,26 @@ Fresh context is default; `context:"fork"` preserves the native conversation,
 including prior tool results. A forked child still cannot delegate. Optional
 `cwd` and `model` are explicit launch overrides; do not change global auth/model
 settings to implement an override.
+`model:"provider/model:thinking"` uses Pi's native suffix resolver when the host
+exports it; a literal model ID wins before suffix parsing. Without that host API,
+use a literal ID with inherited thinking or upgrade Pi. Never retry another model
+silently.
 
-Runs are asynchronous unless `async:false`. Continue useful independent work;
-when child evidence gates the next step, end the turn and await completion rather
-than polling. A launch receipt is not completion. Review actual outputs and
+Every launch, continuation and guidance call returns a receipt; no tool waits for
+child completion. Continue useful independent work; when child evidence gates the
+next step, end the turn and let the completion notice resume you rather than
+polling `inspect`. A launch receipt is not completion. Review actual outputs and
 validation evidence before accepting the result.
 
+Keep the main session running for completion delivery. A one-shot print
+invocation exits after its final turn and stops any remaining children.
+
 ## Controls
 
 - `agent_runs({action:"list"})` discovers this native main's saved runs.
 - `inspect` reads a run by ID; follow returned offsets for complete output.
 - `continue` takes a complete follow-up `prompt` and keeps the saved child chat.
   Active work receives guidance; completed work gets an immutable successor.
-- `wait` observes existing work; cancelling that wait does not stop the producer.
 - `stop` requests termination. Inspect actual process evidence; request acceptance
   does not prove actor or command exit.
 
@@ -45,6 +52,15 @@ Use IDs returned by the tools. Runs belong to their native main session, not a
 cwd, project, name, or forked copy of its transcript. Resume the same main for
 ownership. Do not delete ambiguous launch state to force another attempt.
 
+Escape aborts the parent's reply, not already-launched children; `stop` ends one
+run. Children terminate when their parent exits. Resume the same parent and explicitly
+continue a saved child conversation; the child inspects the interrupted work
+rather than automatically replaying tool calls. Ordinary `/reload` is not exit.
+Under a fork launcher that provides `ctx.managedHost`, `pi restart` or `/restart`
+is not exit either: children keep running and report to the ready replacement.
+That needs one full CLI relaunch after upgrading; a worker under an older loaded
+launcher still stops children when it exits.
+
 ## Coordination and delivery
 
 All pairs inside a main/children group can use `intercom` list/send/last. Across
@@ -60,3 +76,5 @@ proof; a child-reported pass is evidence to inspect, not automatic sign-off.
 Normal child completion returns through the run, not a redundant intercom
 message. Use direct `send` for guidance, corrections, or blockers that affect live
 work. Ordinary `ask` is bounded request/reply, not durable supervisor revival.
+The [pi-intercom skill](../pi-intercom/SKILL.md) covers messaging operations.
+See [tools and lifecycle](../../docs/reference.md) for the owning contracts.

package/src/agent/child-runtime.ts

@@ -0,0 +1,105 @@
+import * as fs from "node:fs";
+import type {
+  CreateAgentSessionRuntimeFactory,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { Launch } from "./contracts.ts";
+import type { loadSDK, WorkingState } from "./host.ts";
+import { shellCommand } from "./process.ts";
+import { localCwdOwner } from "./cwd.ts";
+import type { ToolEvent } from "./observation-state.ts";
+
+function guard(pi: ExtensionAPI, directory: string, token: string): void {
+  pi.on("tool_call", (event) => {
+    if (event.toolName === "delegate" || event.toolName === "agent_runs") {
+      return { block: true, reason: "Only a main session may delegate or control children." };
+    }
+    const owner = pi.getAllTools().find((tool) => tool.name === "bash")?.sourceInfo;
+    if (
+      event.toolName === "bash" &&
+      typeof event.input.command === "string" &&
+      owner &&
+      (owner.source === "builtin" || localCwdOwner(owner))
+    ) {
+      // Preserve the selected local owner's cwd/env and leave remote/custom tools alone.
+      const input = event.input;
+      input.command = shellCommand(event.input.command, directory, token);
+    }
+    return;
+  });
+}
+interface ChildHooks {
+  readonly directory: string;
+  readonly token: string;
+  /** Exact parked working state; absent means the saved journal alone. */
+  readonly saved: WorkingState | undefined;
+  readonly started: (pi: ExtensionAPI, ctx: ExtensionContext) => void;
+  readonly tool: (event: ToolEvent) => void;
+}
+/** One native child session with this package's child policy and live-view hooks. */
+export function childRuntime(
+  sdk: Awaited<ReturnType<typeof loadSDK>>,
+  launch: Launch,
+  hooks: ChildHooks,
+): CreateAgentSessionRuntimeFactory {
+  return async ({ sessionManager }) => {
+    // Exact restore keeps settings, tool policy and accepted queues; it never replays input.
+    const restore = hooks.saved ? { workingSession: hooks.saved } : {};
+    if (!fs.existsSync(launch.sessionFile)) {
+      throw new Error("Missing saved native session; refusing to create another.");
+    }
+    const settingsManager = sdk.SettingsManager.create(launch.cwd, launch.agentDir, {
+      projectTrusted: launch.trusted,
+    });
+    const services = await sdk.createAgentSessionServices({
+      ...restore,
+      cwd: launch.cwd,
+      agentDir: launch.agentDir,
+      settingsManager,
+      resourceLoaderOptions: {
+        additionalExtensionPaths: [launch.entry],
+        extensionFactories: [
+          {
+            name: "codemode",
+            builtin: true,
+            factory: sdk.createCodemodeExtension({ mode: "on" }),
+          },
+          { name: "tool_search", builtin: true, factory: sdk.createToolSearchExtension() },
+          { name: "mcp", builtin: true, factory: sdk.createMcpExtension() },
+          (pi) => {
+            guard(pi, hooks.directory, hooks.token);
+            pi.on("session_start", (_event, ctx) => {
+              hooks.started(pi, ctx);
+            });
+            // Sparse tool lifecycle keeps the live view's tools even while nobody watches.
+            pi.on("tool_execution_start", hooks.tool);
+            pi.on("tool_execution_update", hooks.tool);
+            pi.on("tool_execution_end", hooks.tool);
+          },
+        ],
+      },
+    });
+    const diagnostics = services.resourceLoader.getExtensions().errors;
+    if (diagnostics.length > 0) {
+      throw new Error(`Child extension load failed: ${JSON.stringify(diagnostics)}`);
+    }
+    const model = services.modelRuntime.getModel(launch.provider, launch.model);
+    if (!model) {
+      throw new Error(
+        `Saved model ${launch.provider}/${launch.model} is unavailable; no fallback was used.`,
+      );
+    }
+    return {
+      ...(await sdk.createAgentSessionFromServices({
+        ...restore,
+        services,
+        sessionManager,
+        model,
+        thinkingLevel: launch.thinking,
+      })),
+      services,
+      diagnostics: services.diagnostics,
+    };
+  };
+}

package/src/agent/contracts.ts

@@ -36,11 +36,17 @@ export const processSchema = Type.Object({
   pid: Type.Integer({ minimum: 1 }),
   identity: Type.String(),
   token: Type.String(),
+  clock: Type.Optional(
+    Type.Object({
+      boot: Type.String(),
+      namespace: Type.String(),
+      at: Type.String({ pattern: "^[1-9][0-9]*$", maxLength: 20 }),
+    }),
+  ),
 });
 export type ProcessIdentity = Static<typeof processSchema>;
 export const attachmentSchema = Type.Object({
-  pid: Type.Integer({ minimum: 1 }),
-  identity: Type.String(),
+  ...Type.Pick(processSchema, ["pid", "identity", "clock"]).properties,
   generation: Type.String(),
   attached: Type.Boolean(),
 });
@@ -97,6 +103,16 @@ export const commandSchema = Type.Object({
 });
 export type Command = Static<typeof commandSchema>;
 export const successorSchema = Type.Object({ id: Type.String() });
+/** Authority to restore exact working state, valid only after the named actor has exited. */
+/** Exact parked authority: one exited generation's state bytes for this session and leaf. */
+export const parkedSchema = Type.Object({
+  token: Type.String(),
+  state: Type.String(),
+  digest: Type.String(),
+  sessionId: Type.String(),
+  leafId: Type.Union([Type.String(), Type.Null()]),
+});
+export type Parked = Static<typeof parkedSchema>;
 export const exitSchema = Type.Object({
   pid: Type.Integer(),
   code: Type.Union([Type.Integer(), Type.Null()]),
@@ -110,35 +126,3 @@ export const admissionSchema = Type.Object({
   state: Type.Optional(Type.Union([Type.Literal("accepted"), Type.Literal("stale")])),
   at: Type.Number(),
 });
-export const delegateSchema = Type.Object(
-  {
-    prompt: Type.String({ minLength: 1 }),
-    name: Type.Optional(Type.String({ minLength: 1 })),
-    cwd: Type.Optional(Type.String({ minLength: 1 })),
-    model: Type.Optional(
-      Type.String({ minLength: 1, description: "Exact provider/model ID; no fallback." }),
-    ),
-    context: Type.Optional(Type.Union([Type.Literal("fresh"), Type.Literal("fork")])),
-    async: Type.Optional(Type.Boolean({ default: true })),
-  },
-  { additionalProperties: false },
-);
-export type DelegateInput = Static<typeof delegateSchema>;
-export const runsSchema = Type.Object(
-  {
-    action: Type.Union([
-      Type.Literal("list"),
-      Type.Literal("inspect"),
-      Type.Literal("continue"),
-      Type.Literal("stop"),
-      Type.Literal("wait"),
-    ]),
-    id: Type.Optional(Type.String()),
-    prompt: Type.Optional(Type.String({ minLength: 1 })),
-    async: Type.Optional(Type.Boolean({ default: true })),
-    offset: Type.Optional(Type.Integer({ minimum: 0 })),
-    length: Type.Optional(Type.Integer({ minimum: 4, maximum: 262144 })),
-  },
-  { additionalProperties: false },
-);
-export type RunsInput = Static<typeof runsSchema>;