feat(agent): agent.spawn{await:true} suspends too; children wake the parent via fact

agent.await and agent.spawn{await:true} now return immediately when
children are still running: the session closes, runAgent registers a
wake signal in agent_run.await_wake and waits with waitForFact without
holding an io/agent worker slot. A child that settles (terminal or
waiting) signals the parent's registered fact, so the parent resumes at
once instead of polling; the suspended call replays and the child
report becomes the tool result. agent.spawn is registered replay-safe;
a suspended spawn is recorded as failed in the ledger so the replay
re-runs it against the same child.

Migration 0037 also adds the admin_recovery_code, admin_passkey and
webauthn_challenge tables used by the account work.

E11 asserts the parent is suspended with no run held by any worker
while it waits, and covers spawn{await:true} end to end.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

apps/server/src/modules/agent/runner.ts

@@ -27,7 +27,7 @@ import { type RunUpstream, resolveRunUpstream } from "../pi/index.ts";
 import type { ServerContext } from "../types.ts";
 import { DEMO_SCRIPTS, parseFakeScripts } from "./fake-scripts.ts";
 import { buildGoalReport } from "./report.ts";
-import { type AwaitSuspension, attachLiveRun, type LiveRun, subagentSettings } from "./subagents.ts";
+import { type AwaitSuspension, attachLiveRun, type LiveRun, subagentSettings, wakeParent } from "./subagents.ts";
 
 // runAgent 任务的执行体:从设置装配 Pi(或 fake)运行时 → 事件先写 agent_run_event 再推 SSE →
 // 崩溃恢复(pendingOperations>0 时先按幂等键对账未知结果再 resume)→ 消费追加消息 → 汇报以业务表为准。
@@ -502,11 +502,14 @@ export async function drive(
 export async function goalSettled(env: AgentEnv, runId: string, modelText: string): Promise<AgentGoalReport | null> {
   const r = await buildGoalReport(env.ctx.db, runId, modelText);
   if (r.state !== "waiting") return r;
-  await env.ctx.db
+  const u = await env.ctx.db
     .updateTable("agent_run")
     .set({ status: "waiting", summary: r.summary })
     .where("id", "=", runId)
     .where("status", "in", ["running", "waiting"])
-    .execute();
+    .returning(["parent_run_id", sql<boolean>`(select status = 'running' from agent_run o where o.id = ${runId})`.as("was_running")])
+    .executeTakeFirst();
+  // 子会话刚转 waiting(对父会话来说已有结果):唤醒挂起等待的父会话
+  if (u?.parent_run_id && u.was_running) await wakeParent(env.ctx, runId);
   return null;
 }

apps/server/src/modules/agent/service.ts

@@ -12,7 +12,7 @@ import { type AgentRunRow, type DB, type Kysely, sql } from "@umt/db";
 import type { ServerContext } from "../types.ts";
 import { buildGoalReport } from "./report.ts";
 import { type AgentEnv, type DriveResult, INVESTIGATE_CAPABILITIES, publishStatus, scopeFor } from "./runner.ts";
-import { cascadeCancel, descendants, descendantUsage, recordChildCompletion } from "./subagents.ts";
+import { cascadeCancel, descendants, descendantUsage, recordChildCompletion, wakeParent } from "./subagents.ts";
 
 // agent_run 生命周期:建行 + 业务任务行 + 入队 runAgent;追加消息 / 中止;终态汇报(业务表核查)与后台调查去重。
 
@@ -340,6 +340,8 @@ export async function finalize(
     const fin = await ctx.db.selectFrom("agent_run").selectAll().where("id", "=", runId).executeTakeFirst();
     if (fin) await recordChildCompletion(ctx, fin);
   }
+  // 子会话落定(含 waiting):唤醒挂起等待它的父会话
+  if (run.parent_run_id) await wakeParent(ctx, runId);
   // 结束前刚到的追加消息:再唤醒一次
   const pending = await ctx.db
     .selectFrom("agent_run_message")

apps/server/src/modules/agent/subagents.ts

@@ -31,9 +31,11 @@ import type { AgentEnv, RunScope } from "./runner.ts";
 //   能力白名单 ⊆ 父、模式不高于父、预算从父剩余预算划拨;settings.pi.subagents{enabled,maxConcurrent,maxDepth}。
 // - 并发:子会话在 runAgent 里先占名额(父会话下同时 running 的子会话 < maxConcurrent,咨询锁内原子判定),
 //   没名额就 waitForFact 挂起(不占 worker、不占模型)。
-// - agent.await:等子会话结束,返回脱敏后的汇报摘要。runAgent 驱动的会话里,子会话还没结束时挂起:
-//   关闭本会话(工具调用留在 JSONL 里未完成),runAgent 用 waitForFact 等子会话落定(不占 worker、不占模型),
-//   再打开会话 resume —— agent.await 是只读能力(replay=safe),恢复时重放一次拿到结果。见 AwaitSuspension。
+// - agent.await / agent.spawn{await:true}:等子会话结束,返回脱敏后的汇报摘要。runAgent 驱动的会话里,
+//   子会话还没结束时工具调用立即返回(挂起):关闭本会话(工具调用留在 JSONL 里未完成),runAgent 在 agent_run.await_wake
+//   登记唤醒信号后用 waitForFact 等子会话落定(不占 worker 槽位、不调用模型);子会话落定时 wakeParent 写 fact
+//   唤醒父会话,再打开会话 resume —— 两个能力都是 replay=safe,恢复时重放一次,子会话汇报作为工具结果续跑。
+//   见 AwaitSuspension。
 // - 事件:父会话运行进程把子会话事件按父 seq 镜像进父事件流(subagent_spawned / subagent_event / subagent_completed);
 //   父会话已不在运行时,由直接写入器在咨询锁内补记 subagent_completed。
 // - 取消:父会话取消递归传播到全部子孙会话;预算:父会话运行时把子孙会话用量计入自己的预算。
@@ -66,7 +68,23 @@ const safe = (s: string | null | undefined, n = 1500) => clip(redactString(s ??
 
 // ── 进程内活跃会话(镜像泵 + 用量缓存) ──
 
-/** agent.await 挂起请求:runAgent 据此 waitForFact,落定后以 resumedAwaits 重开会话 */
+/**
+ * 挂起中的工具调用(agent.spawn{await:true})抛出这个错误:账本记 failed、不缓存结果,
+ * 会话恢复时重放同一调用(幂等键相同 → 同一个子会话)再取汇报。会话此时已关闭,模型看不到它。
+ */
+export class AwaitSuspendedError extends CapabilityError {
+  constructor() {
+    super("precondition", "会话已挂起等待子会话结束,恢复后重放本调用");
+  }
+}
+
+/** runAgent 挂起期间登记在 agent_run.await_wake 的唤醒信号(子会话落定时 wakeParent 按它 signal) */
+export interface AwaitWake {
+  engineRunId: string;
+  fact: string;
+}
+
+/** agent.await / agent.spawn{await:true} 挂起请求:runAgent 据此 waitForFact,落定后以 resumedAwaits 重开会话 */
 export interface AwaitSuspension {
   /** 挂起的工具调用(恢复时重放,同一 invocationId 不再挂起) */
   invocationId: string;
@@ -588,6 +606,53 @@ export async function awaitReady(ctx: ServerContext, parentId: string, sus: Awai
   return rows.every((r) => SETTLED.includes(r.status)) ? true : null;
 }
 
+/** 挂起前登记 / 恢复后清除唤醒信号(幂等) */
+export async function setAwaitWake(ctx: ServerContext, runId: string, wake: AwaitWake | null): Promise<null> {
+  await ctx.db
+    .updateTable("agent_run")
+    .set({ await_wake: wake ? JSON.stringify(wake) : null })
+    .where("id", "=", runId)
+    .execute();
+  return null;
+}
+
+/**
+ * 子会话落定(终态或 waiting)后唤醒挂起等待的父会话:按父会话登记的 await_wake 写 fact + 发引擎信号。
+ * 父会话没挂起时什么也不做;失败只记日志(父会话还有兜底轮询)。
+ */
+export async function wakeParent(ctx: ServerContext, childRunId: string): Promise<boolean> {
+  try {
+    const r = await ctx.db
+      .selectFrom("agent_run as c")
+      .innerJoin("agent_run as p", "p.id", "c.parent_run_id")
+      .select(["p.id as parentId", "p.await_wake as wake"])
+      .where("c.id", "=", childRunId)
+      .executeTakeFirst();
+    const w = r?.wake as AwaitWake | null | undefined;
+    if (!w?.engineRunId || !w.fact) return false;
+    await ctx.engine.signal(w.engineRunId, w.fact, { childRunId });
+    return true;
+  } catch (err) {
+    ctx.logger.warn({ childRunId, err: { message: (err as Error).message } }, "唤醒父会话失败(父会话会兜底轮询)");
+    return false;
+  }
+}
+
+/**
+ * 子会话还没落定时请求挂起:记下等待条件并关闭会话(本调用在 JSONL 里保持未完成),drive 看到 requested 后返回
+ * suspended。同一批里已有别的调用在挂起时不再重复登记。
+ */
+async function requestSuspension(live: LiveRun, invocationId: string, runIds: string[] | null, timeoutSec: number) {
+  if (!live.suspend || live.suspend.requested) return;
+  live.suspend.requested = {
+    invocationId,
+    runIds,
+    deadline: new Date(Date.now() + timeoutSec * 1000).toISOString(),
+  };
+  await new Promise((r) => setTimeout(r, 0));
+  await live.handle.close();
+}
+
 // ── 能力处理器 ──
 
 export interface SpawnDeps {
@@ -614,7 +679,8 @@ async function parentOf(ctx: ServerContext, c: HandlerContext): Promise<AgentRun
 }
 
 export function registerSubagentCapabilities(registry: CapabilityRegistry, ctx: ServerContext, deps: SpawnDeps) {
-  registry.register(capabilitySpec("agent.spawn"), async (input, c) => {
+  // replay=safe:await=true 挂起后会话恢复时要重放本调用取子会话汇报;幂等键相同 → dedupe_key 命中同一个子会话
+  registry.register({ ...capabilitySpec("agent.spawn"), replay: "safe" }, async (input, c) => {
     const parent = await parentOf(ctx, c);
     const s = await ctx.settings.all();
     const cfg = subagentSettings(s);
@@ -655,9 +721,23 @@ export function registerSubagentCapabilities(registry: CapabilityRegistry, ctx:
       child = r.run;
     }
     await liveRun(parent.id)?.pump();
-    const result = input.await
-      ? ((await awaitChildren(ctx, parent.id, [child.id], input.timeoutSec, c.signal)).results[0] ?? null)
-      : null;
+    let result: SubagentResult | null = null;
+    if (input.await) {
+      const live = liveRun(parent.id);
+      const inv = c.invocationId;
+      if (live?.suspend && inv) {
+        // runAgent 驱动:不在工具调用里等,挂起会话(不占 worker),子会话落定后重放本调用
+        const snap = await awaitChildren(ctx, parent.id, [child.id], 0, c.signal);
+        if (!snap.allDone && !live.suspend.resumed.has(inv)) {
+          // 崩溃对账(reconcile:*)只确保子会话已建,不挂起;真正的等待交给恢复后的重放
+          if (!inv.startsWith("reconcile:")) await requestSuspension(live, inv, [child.id], input.timeoutSec);
+          throw new AwaitSuspendedError();
+        }
+        result = snap.results[0] ?? null;
+      } else {
+        result = (await awaitChildren(ctx, parent.id, [child.id], input.timeoutSec, c.signal)).results[0] ?? null;
+      }
+    }
     const cs = (child.scope ?? {}) as Partial<RunScope>;
     return {
       runId: child.id,
@@ -677,14 +757,8 @@ export function registerSubagentCapabilities(registry: CapabilityRegistry, ctx:
     // 恢复时重放:已挂起等过,直接返回当前状态
     const snap = await awaitChildren(ctx, parent.id, input.runIds, 0, c.signal);
     if (snap.allDone || live.suspend.resumed.has(inv) || live.suspend.requested) return snap;
-    // 挂起:记下等待条件,关闭会话(本调用在 JSONL 里保持未完成);drive 看到 requested 后返回 suspended
-    live.suspend.requested = {
-      invocationId: inv,
-      runIds: input.runIds?.length ? [...input.runIds] : null,
-      deadline: new Date(Date.now() + input.timeoutSec * 1000).toISOString(),
-    };
-    await new Promise((r) => setTimeout(r, 0));
-    await live.handle.close();
+    // 挂起:立即返回,会话关闭(本调用在 JSONL 里保持未完成,返回值不会进模型上下文);恢复后重放拿真实结果
+    await requestSuspension(live, inv, input.runIds?.length ? [...input.runIds] : null, input.timeoutSec);
     return snap;
   });
 }

apps/server/src/modules/agent/tasks.ts

@@ -17,14 +17,17 @@ import {
 import { buildGoalReport } from "./report.ts";
 import { type AgentEnv, type DriveResult, drive, goalSettled } from "./runner.ts";
 import { finalize } from "./service.ts";
-import { awaitReady, catchUpChildren, claimSubagentSlot } from "./subagents.ts";
+import { awaitReady, catchUpChildren, claimSubagentSlot, setAwaitWake } from "./subagents.ts";
 
 // 持久任务:runAgent(驱动一次有界 Agent 会话 → 等目标关联的下载/入库落定 → 以业务表汇报)
 // 与 resolveDecision(decision.created → 自动调查;decision.updated(resolved)→ 执行所选处理)。
 
 const id = z.string().uuid();
-/** agent.await 挂起时的唤醒轮询间隔与单个会话最多挂起次数 */
-const AWAIT_POLL_SEC = 2;
+/**
+ * agent.await / agent.spawn{await:true} 挂起时的兜底轮询间隔(正常由子会话落定时的 wakeParent 信号立即唤醒;
+ * 信号在等待开始前送达而丢失时靠它兜底)与单个会话最多挂起次数
+ */
+const AWAIT_POLL_SEC = 10;
 const MAX_AWAIT_SUSPENDS = 100;
 const DB_RETRY = { maximumAttempts: 3, initialInterval: "1s", backoffCoefficient: 2, maximumInterval: "30s" } as const;
 
@@ -77,8 +80,8 @@ export function registerAgentTasks(registry: TaskRegistry, env: () => AgentEnv)
           res = { status: "failed", reason: "error", budget: null, message: "等待子会话名额超时", finalText: "" };
         else {
           res = await t.step.run("drive", () => drive(e, e.ctx.capabilities, runId, t.abortSignal));
-          // agent.await 挂起:会话已关闭,waitForFact 等子会话落定 / 超时 / 取消(不占 worker、不占模型),
-          // 再重开会话 resume(挂起的 agent.await 重放一次拿到结果)
+          // agent.await / agent.spawn{await:true} 挂起:会话已关闭;登记唤醒信号后 waitForFact 等子会话落定 / 超时 / 取消
+          // (不占 worker 槽位、不调用模型),子会话落定时写 fact 唤醒;再重开会话 resume(挂起的调用重放一次拿到结果)
           const resumedAwaits: string[] = [];
           for (let n = 1; res.status === "suspended" && res.suspension; n++) {
             const sus = res.suspension;
@@ -87,11 +90,15 @@ export function registerAgentTasks(registry: TaskRegistry, env: () => AgentEnv)
               break;
             }
             const waitMs = Math.max(0, Date.parse(sus.deadline) - Date.now());
-            await t.step.waitForFact<true>(`subagent-await-${n}`, {
+            const fact = `subagent-await-${n}`;
+            const engineRunId = t.runId;
+            await t.step.run(`${fact}-arm`, () => setAwaitWake(e.ctx, runId, { engineRunId, fact }));
+            await t.step.waitForFact<true>(fact, {
               check: () => awaitReady(e.ctx, runId, sus),
               timeout: `${AWAIT_POLL_SEC}s`,
               maxRounds: Math.max(1, Math.ceil(waitMs / 1000 / AWAIT_POLL_SEC) + 1),
             });
+            await t.step.run(`${fact}-disarm`, () => setAwaitWake(e.ctx, runId, null));
             resumedAwaits.push(sus.invocationId);
             const resumed = [...resumedAwaits];
             res = await t.step.run(`drive-${n}`, () =>