@xingular/harness 0.1.7 → 2.1.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,70 @@
+---
+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 changes shipped in `@xingular/harness` 2.0.0 (commit `44471bc`); release does not imply live-provider acceptance.
+
+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.
+
+Release verification on 2026-10-18: npm 10 clean install, typecheck, 515 tests (two skipped), build and standalone proof passed. GitHub CI passed on Ubuntu and macOS, and the npm publish workflow released version 2.0.0 with provenance. No live provider requests were made during release verification.