@xingular/harness 0.1.7 → 2.0.0

package/dist/terminal-pi.js

@@ -10,6 +10,7 @@ var SocketError = class extends Error {
     super(message2);
     this.code = code;
   }
+  code;
 };
 function connectionFromEnv(env = process.env) {
   const socket = env[SOCKET_ENV];
@@ -105,8 +106,8 @@ async function attempt(ui, action) {
     return false;
   }
 }
-function resetIn(resetsAt, now = Date.now()) {
-  const minutes = Math.round((Date.parse(resetsAt) - now) / 6e4);
+function resetIn(resetsAt, now2 = Date.now()) {
+  const minutes = Math.round((Date.parse(resetsAt) - now2) / 6e4);
   if (Number.isNaN(minutes)) return resetsAt;
   if (minutes <= 0) return "now";
   if (minutes < 60) return `in ${minutes}m`;
@@ -123,7 +124,7 @@ function accountRows(overview, session) {
 var limitLine = (limit) => `${limit.label}: ${limit.usedPercent ?? "?"}% used${limit.resetsAt ? `, resets ${resetIn(limit.resetsAt)}` : ""}`;
 function accountDetails(account) {
   const state = account.state;
-  const lines = [
+  const lines2 = [
     account.label,
     `Health: ${HEALTH[state.health] ?? HEALTH.unknown}`,
     `Default for new sessions: ${account.isDefault ? "yes" : "no"}`,
@@ -137,7 +138,7 @@ function accountDetails(account) {
     state.limits.length ? null : "Usage limits: Pi providers do not report them.",
     state.capabilities.length ? `Detected: ${state.capabilities.join(", ")}` : null
   ];
-  return lines.filter((line) => line !== null).join("\n");
+  return lines2.filter((line) => line !== null).join("\n");
 }
 function loginStep(step) {
   if (step.type === "auth_url" && typeof step.url === "string") return `Open this link to sign in:
@@ -233,9 +234,9 @@ async function accountMenu(ui, call, session, accountId) {
 }
 async function showActivity(ui, call, accountId, label) {
   const entries = await call("accounts.audit", { accountId, limit: 30 });
-  const lines = entries.map((entry) => `${new Date(entry.at).toLocaleString()} \xB7 ${entry.action} \xB7 ${entry.detail}`);
+  const lines2 = entries.map((entry) => `${new Date(entry.at).toLocaleString()} \xB7 ${entry.action} \xB7 ${entry.detail}`);
   await ui.select(`${label}: activity
-${lines.join("\n") || "Nothing has happened here yet."}`, [BACK]);
+${lines2.join("\n") || "Nothing has happened here yet."}`, [BACK]);
 }
 async function signIn(ui, call, account) {
   const providers = await call("accounts.providers");
@@ -284,7 +285,7 @@ async function followLogin(ui, call, accountId, loginId) {
       await answerPrompt(ui, call, loginId, snapshot.prompt);
       continue;
     }
-    const step = [...snapshot.events].reverse().map(loginStep).find((text2) => text2 !== null);
+    const step = [...snapshot.events].reverse().map(loginStep).find((text3) => text3 !== null);
     if (step && snapshot.revision !== shownRevision) {
       shownRevision = snapshot.revision;
       const choice = await ui.select(`${step}
@@ -313,18 +314,18 @@ function reportLogin(ui, snapshot) {
 async function answerPrompt(ui, call, loginId, prompt) {
   const promptId = String(prompt.promptId ?? "");
   const detail = prompt.prompt ?? {};
-  const text2 = detail.message ?? "Sign-in needs an answer.";
+  const text3 = detail.message ?? "Sign-in needs an answer.";
   let value;
   if (detail.type === "select" && Array.isArray(detail.options)) {
     if (detail.options.every((option) => typeof option === "string")) {
-      value = await ui.select(text2, detail.options);
+      value = await ui.select(text3, detail.options);
     } else if (detail.options.every((option) => typeof option === "object" && option !== null && "id" in option && typeof option.id === "string" && "label" in option && typeof option.label === "string")) {
       const options = detail.options;
-      const selected = await ui.select(text2, options.map((option) => option.label));
+      const selected = await ui.select(text3, options.map((option) => option.label));
       value = options.find((option) => option.label === selected)?.id;
     }
   } else {
-    value = await ui.input(text2, detail.placeholder ?? void 0);
+    value = await ui.input(text3, detail.placeholder ?? void 0);
   }
   await call("accounts.loginRespond", { loginId, promptId, value: value ?? null });
 }
@@ -497,11 +498,303 @@ function claimTerminalControl(connection = connectionFromEnv()) {
   }
   return claim;
 }
+async function controlCall(call, params = {}, timeoutMs = 12e4) {
+  const connection = connectionFromEnv();
+  const control = await claimTerminalControl(connection);
+  return socketCall(connection, call, params, timeoutMs, control);
+}
+
+// src/sessions/contracts.ts
+import { z } from "zod";
+var runStatusSchema = z.enum(["queued", "running", "waiting_for_approval", "waiting_for_input", "interrupted", "completed", "failed"]);
+var runEventTypeSchema = z.enum([
+  "started",
+  "context.snapshot",
+  "message.delta",
+  "message.completed",
+  "message.steered",
+  "tool.started",
+  "tool.completed",
+  "retry.started",
+  "retry.ended",
+  "compaction.started",
+  "compaction.ended",
+  "approval.requested",
+  "approval.resolved",
+  "question.requested",
+  "question.answered",
+  "extension.notice",
+  "reaction.added",
+  "agent.message",
+  "artifact.added",
+  "file.changed",
+  "usage.updated",
+  "account.status",
+  "status.changed",
+  "failed",
+  "completed"
+]);
+var messageDeltaPayload = z.object({ messageId: z.string(), text: z.string() });
+var messageCompletedPayload = z.object({ messageId: z.string(), role: z.enum(["user", "assistant"]), text: z.string() });
+var messageSteeredPayload = z.object({ text: z.string() });
+var contextSnapshotPayload = z.object({
+  systemPrompt: z.string().max(1e5),
+  contextUpdate: z.string().max(1e5).optional(),
+  tools: z.array(z.object({ name: z.string(), description: z.string().max(2e3), parameters: z.unknown() })).max(120),
+  systemPromptTruncated: z.boolean().optional(),
+  contextUpdateTruncated: z.boolean().optional(),
+  toolsTruncated: z.boolean().optional()
+});
+var toolAttachmentRefSchema = z.object({
+  id: z.string().min(1).max(300),
+  name: z.string().min(1).max(500),
+  mimeType: z.string().min(1).max(100)
+}).strict();
+var toolAttachmentRefsSchema = z.array(toolAttachmentRefSchema).max(16);
+var toolPayload = z.object({
+  toolCallId: z.string(),
+  name: z.string(),
+  summary: z.string().max(200).optional(),
+  input: z.string().max(24e3).optional(),
+  inputTruncated: z.boolean().optional(),
+  output: z.string().max(24e3).optional(),
+  outputTruncated: z.boolean().optional(),
+  ok: z.boolean().optional(),
+  /** On `tool.completed`: how long the call ran, and the size of what it returned to the model. */
+  durationMs: z.number().optional(),
+  resultChars: z.number().optional(),
+  /** Opaque attachment references. Content stays outside the run event stream. */
+  attachments: toolAttachmentRefsSchema.optional()
+});
+var retryStartedPayload = z.object({ attempt: z.number(), maxAttempts: z.number(), delayMs: z.number(), error: z.string().max(1e3).optional() });
+var retryEndedPayload = z.object({ attempt: z.number(), success: z.boolean(), error: z.string().max(1e3).optional() });
+var compactionStartedPayload = z.object({ reason: z.string() });
+var compactionEndedPayload = z.object({
+  reason: z.string(),
+  aborted: z.boolean(),
+  willRetry: z.boolean().optional(),
+  error: z.string().max(1e3).optional(),
+  tokensBefore: z.number().optional(),
+  tokensAfter: z.number().optional(),
+  summary: z.string().max(24e3).optional(),
+  summaryTruncated: z.boolean().optional()
+});
+var approvalAutomaticSchema = z.enum(["always", "remembered", "scope"]);
+var approvalRequestedPayload = z.object({
+  approvalId: z.string(),
+  target: z.string(),
+  action: z.string(),
+  screenshotRef: z.string().optional(),
+  operation: z.object({ tool: z.string(), args: z.unknown() }).optional(),
+  /** A tool the user may choose to always allow for this session. */
+  rememberable: z.boolean().optional(),
+  /** Set when the request was granted as it was made, so nobody is waiting on it. */
+  automatic: approvalAutomaticSchema.optional()
+});
+var approvalResolvedPayload = z.object({ approvalId: z.string(), decision: z.enum(["approved", "denied", "native"]), automatic: approvalAutomaticSchema.optional() });
+var questionOptionSchema = z.object({ label: z.string().min(1), description: z.string().optional() });
+var questionBatchFields = {
+  batchId: z.string().min(1).optional(),
+  batchIndex: z.number().int().min(1).max(5).optional(),
+  batchCount: z.number().int().min(1).max(5).optional()
+};
+var questionBatchRefinement = (value, context) => {
+  const fields = [value.batchId, value.batchIndex, value.batchCount];
+  if (fields.some((field) => field !== void 0) && fields.some((field) => field === void 0)) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "Question batch fields must be supplied together." });
+  }
+  if (value.batchIndex !== void 0 && value.batchCount !== void 0 && value.batchIndex > value.batchCount) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "Question batch index cannot exceed its count." });
+  }
+};
+var questionRequestedPayload = z.object({
+  questionId: z.string(),
+  question: z.string().min(1),
+  summary: z.string().min(1).max(100).optional(),
+  options: z.array(questionOptionSchema),
+  multiSelect: z.boolean(),
+  allowText: z.boolean(),
+  userOnly: z.boolean().optional(),
+  ...questionBatchFields
+}).superRefine(questionBatchRefinement);
+var questionAnsweredPayload = z.object({
+  questionId: z.string(),
+  selected: z.array(z.string()),
+  text: z.string().optional(),
+  notes: z.record(z.string(), z.string().max(1e4)).optional(),
+  ...questionBatchFields
+}).superRefine(questionBatchRefinement);
+var reactionAddedPayload = z.object({ emoji: z.string().min(1).refine((text3) => Buffer.byteLength(text3) <= 16 && !/[A-Za-z0-9\s]/.test(text3)) });
+var agentMessagePayload = z.object({ direction: z.enum(["to", "from"]), agentId: z.string(), agentName: z.string(), text: z.string() });
+var extensionNoticePayload = z.object({
+  kind: z.enum(["notify", "status", "widget", "title", "error"]),
+  level: z.enum(["info", "warning", "error"]).optional(),
+  key: z.string().optional(),
+  text: z.string(),
+  extension: z.string().optional()
+});
+var artifactPayload = z.object({ artifactId: z.string(), name: z.string(), file: z.unknown().optional() });
+var fileChangedPayload = z.object({ path: z.string(), change: z.enum(["added", "modified", "deleted"]) });
+var costSourceSchema = z.enum(["harness", "estimate", "mixed"]);
+var usageRequestSchema = z.object({
+  /** Position in the run, from 1. */
+  index: z.number(),
+  responseId: z.string().optional(),
+  model: z.string().optional(),
+  provider: z.string().optional(),
+  inputTokens: z.number().optional(),
+  cacheReadTokens: z.number().optional(),
+  cacheWriteTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  reasoningTokens: z.number().optional(),
+  costUsd: z.number().optional(),
+  costSource: z.enum(["harness", "estimate"]).optional(),
+  /** Separate provider-supplied summary; never generic private thinking content. */
+  reasoningSummary: z.string().max(4e3).optional(),
+  /** From sending the request to the end of the response, and to its first output. */
+  durationMs: z.number().optional(),
+  ttftMs: z.number().optional(),
+  stopReason: z.string().optional()
+});
+var usagePayloadSchema = z.object({
+  /** Input tokens that were not read from the provider's cache. */
+  inputTokens: z.number().optional(),
+  /** Includes reasoning tokens. */
+  outputTokens: z.number().optional(),
+  cacheReadTokens: z.number().optional(),
+  cacheWriteTokens: z.number().optional(),
+  reasoningTokens: z.number().optional(),
+  costUsd: z.number().optional(),
+  costSource: costSourceSchema.optional(),
+  /** Model requests made so far. */
+  requests: z.number().optional(),
+  /** Size of the latest request (not cumulative), and the model's limit. */
+  contextTokens: z.number().optional(),
+  contextWindow: z.number().optional(),
+  model: z.string().optional(),
+  provider: z.string().optional(),
+  /** The request this update reports. */
+  request: usageRequestSchema.optional()
+});
+var accountIssueCategorySchema = z.enum(["auth_expired", "rate_limited", "quota", "network", "unknown"]);
+var accountLimitSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  usedPercent: z.number().nullable().optional(),
+  resetsAt: z.string().nullable().optional(),
+  windowMinutes: z.number().nullable().optional(),
+  status: z.string().nullable().optional()
+});
+var accountStatusPayload = z.object({
+  accountId: z.string(),
+  category: accountIssueCategorySchema.optional(),
+  message: z.string().optional(),
+  resetsAt: z.string().optional(),
+  plan: z.string().optional(),
+  limits: z.array(accountLimitSchema).optional()
+});
+var statusPayload = z.object({ status: runStatusSchema, reason: z.string().optional() });
+var failedPayload = z.object({ code: z.string(), message: z.string() });
+var emptyPayload = z.object({}).passthrough();
+var runEventPayloadSchemas = {
+  started: emptyPayload,
+  "context.snapshot": contextSnapshotPayload,
+  "message.delta": messageDeltaPayload,
+  "message.completed": messageCompletedPayload,
+  "message.steered": messageSteeredPayload,
+  "tool.started": toolPayload,
+  "tool.completed": toolPayload,
+  "retry.started": retryStartedPayload,
+  "retry.ended": retryEndedPayload,
+  "compaction.started": compactionStartedPayload,
+  "compaction.ended": compactionEndedPayload,
+  "approval.requested": approvalRequestedPayload,
+  "approval.resolved": approvalResolvedPayload,
+  "question.requested": questionRequestedPayload,
+  "question.answered": questionAnsweredPayload,
+  "extension.notice": extensionNoticePayload,
+  "reaction.added": reactionAddedPayload,
+  "agent.message": agentMessagePayload,
+  "artifact.added": artifactPayload,
+  "file.changed": fileChangedPayload,
+  "usage.updated": usagePayloadSchema,
+  "account.status": accountStatusPayload,
+  "status.changed": statusPayload,
+  failed: failedPayload,
+  completed: emptyPayload
+};
+var runEventSchema = z.object({
+  id: z.string(),
+  runId: z.string(),
+  sessionId: z.string(),
+  sequence: z.number().int().nonnegative(),
+  timestamp: z.string(),
+  type: runEventTypeSchema,
+  payload: z.unknown(),
+  /** The native event this one was derived from, kept as evidence. */
+  native: z.unknown().optional(),
+  /** Set when consecutive text deltas were merged for relay; covers sequences coalescedFrom..sequence. */
+  coalescedFrom: z.number().int().nonnegative().optional()
+}).superRefine((event, context) => {
+  if (!runEventPayloadSchemas[event.type].safeParse(event.payload).success) {
+    context.addIssue({ code: "custom", path: ["payload"], message: `Invalid payload for ${event.type}` });
+  }
+});
+var text = z.string().nullish().transform((value) => value ?? null);
+var runRecordSchema = z.object({
+  resumedFromRunId: text,
+  parentRunId: text,
+  relation: text,
+  terminalReason: text,
+  id: z.string(),
+  projectId: text,
+  mode: z.string(),
+  harness: z.string(),
+  sessionType: z.string(),
+  sessionId: z.string(),
+  nativeSessionId: text,
+  workingDirectory: text,
+  worktreeId: text,
+  goal: text,
+  attachmentCount: z.number().int().nonnegative().default(0),
+  startedAt: z.string(),
+  endedAt: text,
+  status: z.string(),
+  exitCode: z.number().int().nullish().transform((value) => value ?? null),
+  handoffId: text,
+  accountId: text,
+  agentId: text,
+  trigger: text
+});
+
+// src/core/index.ts
+import { DatabaseSync } from "node:sqlite";
+
+// src/sessions/subagents.ts
+var SUBAGENT_RECEIPT = "xingularSubagents";
+var SUBAGENT_OWNER = "xingular-subagent-owner";
+var SUBAGENT_RESULTS = "xingular-subagent-results";
+function subagentHistory(entries) {
+  const owners = [];
+  const receipts = [];
+  for (const raw of entries) {
+    if (!raw || typeof raw !== "object") continue;
+    const entry = raw;
+    if (entry.type === "custom" && entry.customType === SUBAGENT_OWNER && typeof entry.data?.runId === "string") owners.push(entry.data.runId);
+    const message2 = entry.type === "message" ? entry.message : entry;
+    const receipt = message2?.details?.[SUBAGENT_RECEIPT];
+    if (!receipt || receipt.version !== 1 || typeof receipt.ownerRunId !== "string") continue;
+    const strings = (value) => Array.isArray(value) && value.every((id) => typeof id === "string");
+    if (receipt.spawned !== void 0 && !strings(receipt.spawned) || receipt.delivered !== void 0 && !strings(receipt.delivered)) continue;
+    receipts.push(receipt);
+  }
+  return { owners, receipts };
+}
 
 // src/tools/askUser.ts
 var ASK_USER = "ask_user";
 var MAX_OPTIONS = 6;
-var text = (value) => typeof value === "string" ? value.trim() : "";
+var text2 = (value) => typeof value === "string" ? value.trim() : "";
 function describeAnswer(answer) {
   const parts = [];
   if (answer.selected.length) parts.push(`The user chose: ${answer.selected.join(", ")}.`);
@@ -509,7 +802,7 @@ function describeAnswer(answer) {
   for (const [choice, note] of Object.entries(answer.notes ?? {})) parts.push(`Their note for ${choice}: ${note}`);
   return parts.join(" ") || "The user did not answer.";
 }
-function askUserTool(run) {
+function askUserTool(run2) {
   return {
     name: ASK_USER,
     label: "Ask the user",
@@ -531,15 +824,15 @@ function askUserTool(run) {
       if (!Array.isArray(input.questions) || input.questions.length < 1 || input.questions.length > 5) return "Ask between one and five questions.";
       const questions = input.questions.map((raw) => {
         const item = raw;
-        const summary = text(item.summary);
-        const question = text(item.question);
-        const options = (Array.isArray(item.options) ? item.options : []).map((option) => ({ label: text(option.label), description: text(option.description) })).filter((option) => option.label).slice(0, MAX_OPTIONS);
+        const summary = text2(item.summary);
+        const question = text2(item.question);
+        const options = (Array.isArray(item.options) ? item.options : []).map((option) => ({ label: text2(option.label), description: text2(option.description) })).filter((option) => option.label).slice(0, MAX_OPTIONS);
         return { summary, question, options, multiSelect: options.length > 1 && item.multiSelect === true, allowText: true };
       });
       if (questions.some((question) => !question.summary || question.summary.length > 100)) return "Each question needs a short summary of no more than 100 characters.";
       if (questions.some((question) => !question.question)) return "Every question needs a question sentence.";
       if (questions.some((question) => question.options.some((option) => !option.description))) return "Every choice needs a short description. Aim for 25 words or fewer.";
-      const answers = await run.requestAnswers(questions);
+      const answers = await run2.requestAnswers(questions);
       return questions.map((question, index) => `${question.summary}: ${describeAnswer(answers[index])}`).join("\n");
     }
   };
@@ -551,9 +844,24 @@ function resultSize(result) {
   if (!Array.isArray(content)) return typeof result === "string" ? result.length : null;
   return content.reduce((total, part) => total + (part?.type === "text" && typeof part.text === "string" ? part.text.length : 0), 0);
 }
+async function withParentCancellation(signal, work) {
+  const stop = () => {
+    void controlCall("terminal.interrupt").catch(() => {
+    });
+  };
+  if (signal?.aborted) stop();
+  signal?.addEventListener("abort", stop, { once: true });
+  try {
+    return await work();
+  } finally {
+    signal?.removeEventListener("abort", stop);
+  }
+}
 async function piExtension_default(pi) {
   await terminalCall("startup", { phase: "Pi extension loaded" });
   let context = null;
+  let nativeSubagents = false;
+  let subagentParent = false;
   let timer = null;
   let polling = false;
   let failure;
@@ -624,6 +932,18 @@ async function piExtension_default(pi) {
         }
       });
     }
+    const native = await controlCall("terminal.subagents.tools");
+    nativeSubagents = native.tools.length > 0;
+    for (const tool of native.tools) pi.registerTool({
+      name: tool.name,
+      label: tool.label,
+      description: tool.description,
+      parameters: Type.Unsafe(tool.parameters),
+      execute: async (_id, input, signal) => {
+        const result = await withParentCancellation(signal, () => controlCall("terminal.subagents.call", { name: tool.name, input }, 2147483647));
+        return { content: [{ type: "text", text: result.text }], details: result.details ?? {} };
+      }
+    });
   } catch (error) {
     await terminalCall("startupFailed", { reason: `${stage} failed: ${error instanceof Error ? error.message : "Unavailable"}` }).catch(() => {
     });
@@ -656,13 +976,26 @@ async function piExtension_default(pi) {
     usage = emptyUsage();
     reasoningTokens = void 0;
     costReported = false;
-    await terminalCall("begin", { text: event.messageType === "user" ? event.prompt : "" });
+    const begun = await terminalCall("begin", { text: event.messageType === "user" ? event.prompt : "" });
+    if (nativeSubagents) {
+      pi.appendEntry(SUBAGENT_OWNER, { runId: begun.runId });
+      await controlCall("terminal.subagents.register", { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) });
+      subagentParent = true;
+    }
   });
+  const deliverChildren = async (event, ctx, settle) => {
+    if (!nativeSubagents || settle && event.outcome !== "completed" || ctx.signal?.aborted) return;
+    const result = await withParentCancellation(ctx.signal, () => controlCall("terminal.subagents.delivery", { history: subagentHistory([...ctx.sessionManager.getBranch(), ...event.entries]), settle }, 2147483647));
+    if (!result) return;
+    return { entries: [...event.entries, { type: "custom_message", customType: SUBAGENT_RESULTS, content: result.text, display: false, details: { [SUBAGENT_RECEIPT]: result.receipt } }], continue: true };
+  };
+  pi.on("turn_end", (event, ctx) => deliverChildren(event, ctx, false));
+  pi.on("agent_before_settle", (event, ctx) => deliverChildren(event, ctx, true));
   pi.on("message_end", async (event) => {
     if (event.message.role !== "assistant") return;
     if (event.message.stopReason === "error" || event.message.stopReason === "aborted") failure = event.message.errorMessage ?? `Pi stopped: ${event.message.stopReason}`;
-    const text2 = event.message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
-    if (text2) await terminalCall("message", { text: text2 });
+    const text3 = event.message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+    if (text3) await terminalCall("message", { text: text3 });
     if (event.message.usage) {
       const reported = event.message.usage;
       usage.inputTokens += reported.input ?? 0;
@@ -707,9 +1040,9 @@ async function piExtension_default(pi) {
   });
   pi.on("tool_call", async (event) => {
     try {
-      const policy = await terminalCall("policy", { tool: event.toolName, args: event.input });
+      const policy = await controlCall("terminal.policy", { tool: event.toolName, args: event.input });
       if (policy.requiresApproval) {
-        const approval = await terminalCall("approval", { requestId: event.toolCallId, target: event.toolName, action: JSON.stringify(event.input), tool: event.toolName, args: event.input });
+        const approval = await controlCall("terminal.approval", { requestId: event.toolCallId, tool: event.toolName, args: event.input });
         if (approval.decision === "approved") return;
         return { block: true, reason: "The user denied this action. Ask how they would like to proceed." };
       }
@@ -732,8 +1065,16 @@ async function piExtension_default(pi) {
     fileTools.delete(event.toolCallId);
     if (!event.isError && path) await terminalCall("file", { path, change: "modified" });
   });
-  pi.on("agent_settled", async () => {
-    await terminalCall("settled", { error: failure });
+  pi.on("agent_settled", async (event, ctx) => {
+    if (subagentParent && !event.aborted && !failure) {
+      try {
+        await controlCall("terminal.subagents.verify", { history: subagentHistory(ctx.sessionManager.getBranch()) }, 2147483647);
+      } catch (error) {
+        failure = error instanceof Error ? error.message : String(error);
+      }
+    }
+    subagentParent = false;
+    await terminalCall("settled", { error: failure, aborted: event.aborted });
   });
   pi.on("user_bash", async () => {
     throw new Error("Use the bash tool so this action can be checked.");

package/docs/README.md

@@ -5,6 +5,9 @@ Current implementation: [Harness terminal frontend](terminal-tui.md). The packag
 
 | ID | Record | Type | Status | Related |
 |---|---|---|---|---|
+| ADR-0004 | [Fullscreen terminal layout with a fixed dock](decisions/ADR-0004-fullscreen-terminal-layout.md) | Decision | Accepted; working tree implementation | ADR-0001, [Terminal architecture and evidence](terminal-tui.md) |
+| ADR-0003 | [Shared asynchronous subagents with native-history delivery receipts](decisions/ADR-0003-shared-asynchronous-subagents.md) | Decision | Accepted; working tree implementation | ADR-0002, [Embedding API](../README.md) |
+| ADR-0002 | [Native subagent lifecycle in Harness sessions](decisions/ADR-0002-native-subagent-lifecycle.md) | Decision | Superseded by ADR-0003 | [Embedding API](../README.md) |
 | ADR-0001 | [Own the terminal frontend and keep Pi as the session runtime](decisions/ADR-0001-owned-terminal.md) | Decision | Accepted; working tree implementation | [Terminal architecture and evidence](terminal-tui.md) |
 
 Living reference pages describe checked source behavior. Accepted decisions record the choice;

package/docs/decisions/ADR-0002-native-subagent-lifecycle.md

@@ -0,0 +1,49 @@
+---
+id: ADR-0002
+title: Native subagent lifecycle in Harness sessions
+status: superseded
+superseded_by: ADR-0003
+created: 2026-10-18
+updated: 2026-10-18
+---
+# ADR-0002 — Native subagent lifecycle in Harness sessions
+
+Superseded by [ADR-0003](ADR-0003-shared-asynchronous-subagents.md), which expands the native
+service to asynchronous execution, reliable delivery, and terminal parity. The earlier decision
+and its rationale are retained below.
+
+## Context
+
+Subagents already used Harness sessions, capability snapshots and run lineage, but their tool
+owned launching and polled run files for completion. A host inferred ownership from session
+names, coupling it to an internal identifier format.
+
+## Decision
+
+`Sessions.spawnSubagent` owns child creation. A live parent's captured launch supplies caller,
+account, model selection, folder, policy context, prompt and capability ceiling. The host or
+model supplies only a complete brief and an optional tool subset. Current capability availability
+and the captured nesting limit further restrict each child. Empty tool subsets stay empty;
+spawning permission is never added back after narrowing. Children start with fresh history,
+without inherited image attachments or request preamble. Existing tool gating applies.
+
+The model tool is an adapter to the same native API exposed over RPC. `RunRegistry.wait` resolves
+on settlement, including failed startup and interruption, without polling or per-call listeners.
+The Harness Subagents plugin attributes the model-visible tool. Opt-in remains a session option;
+`{}` selects the Harness default depth of one. Application organization delegation remains a host
+concern. Consumers resolve ownership from run lineage rather than parsing session IDs.
+
+## Alternatives and consequences
+
+Keeping orchestration in the tool would leave hosts without the same lifecycle contract.
+Moving application organizations into Harness would violate the embedding boundary. A new
+background job manager would duplicate existing run tracking, approvals and interruption.
+The selected change reuses these layers and preserves the synchronous model tool behavior.
+The native API starts children only for live parents in the same Harness instance; it does not
+resume a stopped parent's launch or implement cross-process child management.
+
+## Evidence
+
+Regression coverage is in `src/sessions/sessions.test.ts` and `src/server/server.test.ts`.
+Application host and run-family tests cover nested lineage with opaque session IDs. Verification
+results belong to the implementation handoff; no release or live-provider behavior is claimed.

package/docs/decisions/ADR-0003-shared-asynchronous-subagents.md

@@ -0,0 +1,68 @@
+---
+id: ADR-0003
+title: Shared asynchronous subagents with native-history delivery receipts
+status: accepted
+created: 2026-10-18
+updated: 2026-10-18
+supersedes: ADR-0002
+---
+# ADR-0003 — Shared asynchronous subagents with native-history delivery receipts
+
+## Context and decision
+
+The owner selected reliable delivery, asynchronous spawn/wait, and one SDK/terminal/App API after
+studying OMP. They chose attached children joined before the parent finishes, async spawning by
+default, availability for every interactive caller within its capability ceiling, and recovery
+only when the user explicitly resumes. This supersedes the blocking tool contract in ADR-0002.
+
+`harness.subagents` owns spawning, selective waits and results. SDK and terminal adapters register
+live, frozen parent context with it; no model argument supplies caller, account or replacement
+launch metadata. The terminal adapter uses its private control key. Children use normal Harness
+sessions, isolated accounts, fresh history, existing gates and capability intersection. The old
+`sessions.spawnSubagent` entry point forwards to the service for compatibility.
+
+A parent reserves each child in `runs/<parent>/subagents.json` through the run store before startup.
+A native branch owner marker is persisted before a real parent accepts spawns. Results are delivered
+at turn boundaries or through explicit blocking tools. Native messages and tool results carry typed
+receipts; only receipts on the selected branch acknowledge delivery. Constructing a delivery draft
+never acknowledges it. Large batches acknowledge only the included children. The final settlement
+hook joins children and injects remaining results; an adapter verification guard refuses successful
+completion if persisted native history still lacks a result. The stable system prefix is unchanged.
+
+On explicit resume, matching owner markers, caller/account/folder/native identity and run lineage
+restore undelivered results. A startup reservation that never opened becomes an interrupted run.
+Existing startup recovery interrupts orphaned active runs. Neither recovery path restarts model
+work. Cancellation settles approvals and questions before waiting for SDK abort, preventing blocked
+child interactions from deadlocking parent shutdown.
+
+Interactive sessions enable the tools by default, `null` disables them, and explicit capability
+sets can exclude them. Unattended callers remain off unless the host explicitly enables them.
+Default nesting remains one, with a maximum of three. There is no new scheduler, reusable-worker
+lifecycle, model routing, workspace isolation system, concurrency cap or family budget here.
+
+## Alternatives and consequences
+
+A tool-owned launcher leaves terminal and SDK behavior divergent. An in-memory delivery flag loses
+results across restart; searching prose for run IDs confuses mentions with delivery. Native-history
+receipts identify persisted context without adding a second acknowledgement store. Run records
+remain the outcome source of truth, while the parent file preserves startup reservations.
+
+The App owns organization delegation and resolves native ancestry for thread routing, tools,
+isolation and connections. Its existing work-budget accounting includes native descendants. Harness
+learns no organizational role or application concept. Native completion records execution outcome;
+it does not certify the child's findings or artifacts.
+
+## Evidence and limits
+
+`subagentService.test.ts` covers selective waits, foreign handles, cancellation, bounded batches and
+recovery windows. Real scripted Pi tests in `conversation.test.ts` cover async delivery, inline
+receipts and interruption during a child question. `runtime.socket.test.ts` exercises the real
+terminal socket, private controls, native execution and child decision routing. RPC and App host
+regressions cover protocol shapes and ancestry. Tests use disposable storage without external
+model requests. These are working-tree changes, not a publication or live-provider acceptance claim.
+
+Verification on 2026-10-18: Harness typecheck, 455 tests (two skipped), unchanged golden fixtures,
+build and standalone proof passed. App typecheck, layer/UI checks, sidecar build, 30 sidecar tests
+and 217 Rust tests passed (one ignored). The renderer suite passed 491 tests and retained its
+pre-existing `PendingRequestDock.test.ts` heading-text assertion failure. No live account or
+user-data-root testing was performed.