larkin 0.4.14 → 0.4.15

package/dist/agent/context-prompt.cjs

@@ -16,7 +16,7 @@ const agent_cli_capabilities_js_1 = require("./agent-cli-capabilities.cjs");
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v22";
+exports.LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v23";
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -112,6 +112,7 @@ class ContextPromptBuilder {
                 "2. The tool returns an agent id immediately. Report it to the user and end the turn.",
                 "3. Do NOT poll or sleep; a completion notification arrives automatically.",
                 "4. On the notification, check the Inbox, then publish exactly one final summary.",
+                "If you explicitly use get_subagent_result with wait: true, make at most one bounded wait call per turn. If it returns timedOut: true, do not loop or call wait again in the same turn; yield and let the completion notification wake you.",
                 "Forbidden pattern (never acceptable): `nohup sh -c '...' > /tmp/x.out 2>&1 &`, `sleep N; cat ...`, disown, or any shell background substitute. These bypass subagent isolation.",
                 "Keep corrections, approvals, short commands, and Feishu writes in the foreground; do not delegate them.",
                 "Parallel independent tasks: when the user clearly asks for two or more independent tasks with no dependencies between them, delegate EACH task to its own background subagent in a single message with multiple Agent tool calls (one per task, all with run_in_background: true), report every job id, and end the turn. Do not run them one-by-one in the foreground and do not merge them into one subagent.",

package/dist/agent/context-prompt.mjs

@@ -13,7 +13,7 @@ import { agentCliPromptCapabilities } from "./agent-cli-capabilities.mjs";
  * 5. 版本化：每次实质改动 bump LARKIN_STANDING_PROMPT_VERSION，并同步 eval 数据集/graders/断言。
  * 6. 用 eval 验证：行为变化必须配套固定场景 + rubric（evals/*、test/support/*-grader.mjs、live 测试）。
  */
-export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v22";
+export const LARKIN_STANDING_PROMPT_VERSION = "larkin-standing-v23";
 /**
  * Agent 间协作唤醒引导（issue #75）：纯文本 @ 不会产生飞书 mention 事件，
  * 必须由模型直接构造真实的 mention 元素；`--mention` 扩展参数已移除。
@@ -109,6 +109,7 @@ export class ContextPromptBuilder {
                 "2. The tool returns an agent id immediately. Report it to the user and end the turn.",
                 "3. Do NOT poll or sleep; a completion notification arrives automatically.",
                 "4. On the notification, check the Inbox, then publish exactly one final summary.",
+                "If you explicitly use get_subagent_result with wait: true, make at most one bounded wait call per turn. If it returns timedOut: true, do not loop or call wait again in the same turn; yield and let the completion notification wake you.",
                 "Forbidden pattern (never acceptable): `nohup sh -c '...' > /tmp/x.out 2>&1 &`, `sleep N; cat ...`, disown, or any shell background substitute. These bypass subagent isolation.",
                 "Keep corrections, approvals, short commands, and Feishu writes in the foreground; do not delegate them.",
                 "Parallel independent tasks: when the user clearly asks for two or more independent tasks with no dependencies between them, delegate EACH task to its own background subagent in a single message with multiple Agent tool calls (one per task, all with run_in_background: true), report every job id, and end the turn. Do not run them one-by-one in the foreground and do not merge them into one subagent.",

package/dist/runtime/pi-inline-extensions.mjs

@@ -1,8 +1,37 @@
-import subagentsExtension from "@tintinweb/pi-subagents/dist/index.js";
+import { pathToFileURL } from "node:url";
 import bashTimeoutExtension from "./pi-bash-timeout-extension.mjs";
+import { bundledPiSubagentExtensionPath } from "./pi-subagent-injection.mjs";
+/**
+ * Load the prebuilt, patched subagent bundle shipped in dist/ rather than the
+ * package-manager copy. Standalone binaries additionally load the patched
+ * package through Bun's compiled module graph, while normal package installs
+ * continue to use the prebuilt patched bundle.
+ */
+async function loadBundledPiSubagentExtension() {
+    if (process.env.LARKIN_STANDALONE === "1") {
+        const loaded = await import("@tintinweb/pi-subagents/dist/index.js");
+        if (!loaded.default)
+            throw new Error("Larkin bounded pi-subagents package is invalid; refusing to start builtin Pi");
+        return loaded.default;
+    }
+    const bundle = bundledPiSubagentExtensionPath(process.env.LARKIN_CONFIG_DIR);
+    if (!bundle)
+        throw new Error("Larkin bounded pi-subagents bundle is unavailable; refusing to start builtin Pi");
+    const loaded = await import(pathToFileURL(bundle).href);
+    if (!loaded.default)
+        throw new Error("Larkin bounded pi-subagents bundle is invalid; refusing to start builtin Pi");
+    return loaded.default;
+}
 /** Builtin Pi extensions are loaded as code, never through Pi's path/data-URL loader. */
+const bundledSubagentsExtension = async (pi) => {
+    const extension = await loadBundledPiSubagentExtension();
+    if (typeof extension === "function")
+        await extension(pi);
+    else
+        await extension.factory(pi);
+};
 export const BUILTIN_PI_EXTENSION_FACTORIES = Object.freeze([
-    subagentsExtension,
+    bundledSubagentsExtension,
     bashTimeoutExtension,
 ]);
 /** Invoke Pi RPC with Larkin's builtin-only extension factories. */

package/dist/runtime/pi-subagent-injection.mjs

@@ -81,39 +81,76 @@ export function probeExternalPiVersion(piCommand, env) {
  * 已装时 Larkin 不再 -e 注入，避免同名工具（Agent/get_subagent_result/steer_subagent）
  * 重复注册导致 pi 扩展加载 FATAL（pi 对 duplicate tool registration 是硬失败）。
  */
-export function userPiAlreadyHasSubagentsExtension(env) {
+const BOUNDED_WAIT_CAPABILITY = "larkin-pi-subagents-bounded-wait-v1";
+function userPiSubagentsWaitCapability(env) {
     const agentDir = env.PI_CODING_AGENT_DIR || path.join(env.HOME || process.env.HOME || "", ".pi", "agent");
     try {
+        let configured = false;
         const settingsFile = path.join(agentDir, "settings.json");
         if (fs.existsSync(settingsFile)) {
             const settings = JSON.parse(fs.readFileSync(settingsFile, "utf8"));
             const packages = settings?.packages;
             if (Array.isArray(packages)) {
-                for (const entry of packages) {
-                    if (typeof entry === "string" && /pi-subagents/i.test(entry))
-                        return true;
-                }
+                configured = packages.some((entry) => typeof entry === "string" && /pi-subagents/i.test(entry));
             }
         }
         // settings.json 可能未登记但包目录已存在（残留/手动安装）。
         // Split token: repo contract forbids the literal package-manager word in sources.
-        const npmDir = path.join(agentDir, "n" + "pm", "node_modules", "@tintinweb");
-        if (fs.existsSync(npmDir) && fs.readdirSync(npmDir).some((name) => /pi-subagents/i.test(name)))
-            return true;
+        const packageRoots = [
+            path.join(agentDir, "n" + "pm", "node_modules", "@tintinweb", "pi-subagents"),
+            path.join(agentDir, "node_modules", "@tintinweb", "pi-subagents"),
+        ];
+        const installedRoot = packageRoots.find((root) => fs.existsSync(root));
+        if (!configured && !installedRoot)
+            return "absent";
+        if (!installedRoot)
+            return "unbounded";
+        const packageManifest = JSON.parse(fs.readFileSync(path.join(installedRoot, "package.json"), "utf8"));
+        const extensions = packageManifest.pi?.extensions;
+        if (!Array.isArray(extensions) || extensions.length === 0
+            || !extensions.every((entry) => typeof entry === "string" && entry.length > 0)) {
+            return "unbounded";
+        }
+        // Pi executes the entries declared by the package manifest. Do not trust a
+        // marker in a build artifact when the manifest points Pi at another file.
+        const capabilityFiles = extensions.map((entry) => path.resolve(installedRoot, entry));
+        const hasCapability = capabilityFiles.every((file) => {
+            try {
+                return fs.readFileSync(file, "utf8").includes(BOUNDED_WAIT_CAPABILITY);
+            }
+            catch {
+                return false;
+            }
+        });
+        return hasCapability ? "bounded" : "unbounded";
     }
     catch {
-        /* unreadable config: assume not installed, injection stays safe */
+        // Unreadable user extension state is not safe to treat as bounded.
+        return "unbounded";
     }
-    return false;
+}
+export function userPiAlreadyHasSubagentsExtension(env) {
+    return userPiSubagentsWaitCapability(env) !== "absent";
+}
+export function userPiSubagentsHasBoundedWaitCapability(env) {
+    return userPiSubagentsWaitCapability(env) === "bounded";
 }
 export function resolvePiSubagentExtensionArg(input, probeVersion = () => probeExternalPiVersion(input.piCommand, input.env), resolveBundle = () => bundledPiSubagentExtensionPath(input.env.LARKIN_CONFIG_DIR)) {
+    // A user-installed extension wins only when it advertises the exact bounded
+    // wait capability. Check this before the bundle path so a missing Larkin
+    // asset cannot silently leave an unbounded user extension active.
+    if (userPiAlreadyHasSubagentsExtension(input.env)) {
+        if (!userPiSubagentsHasBoundedWaitCapability(input.env)) {
+            throw new Error("[larkin] WARNING: refusing external Pi because the user-installed " +
+                "pi-subagents extension is unbounded or unverifiable; remove it or install " +
+                "a version advertising larkin-pi-subagents-bounded-wait-v1.");
+        }
+        return null;
+    }
     // resolveBundle is injectable so unit tests stay environment-independent
     // (no dependency on build artifacts or the filesystem).
     const bundle = resolveBundle();
     if (!bundle)
         return null;
-    // 用户已自行安装同款扩展时跳过注入，避免工具名重复注册冲突。
-    if (userPiAlreadyHasSubagentsExtension(input.env))
-        return null;
     return piVersionSupportsSubagents(probeVersion()) ? bundle : null;
 }

package/dist/runtime/pi-subagents.bundle.js

@@ -7104,6 +7104,43 @@ function abortable(promise, signal) {
     });
   });
 }
+var RESULT_WAIT_QUEUE_POLL_MS = 50;
+var DEFAULT_RESULT_WAIT_TIMEOUT_MS = 30000;
+var MAX_RESULT_WAIT_TIMEOUT_MS = 60000;
+function normalizeResultWaitTimeout(timeoutMs) {
+  if (timeoutMs === undefined || !Number.isFinite(timeoutMs))
+    return DEFAULT_RESULT_WAIT_TIMEOUT_MS;
+  return Math.max(1, Math.min(MAX_RESULT_WAIT_TIMEOUT_MS, Math.floor(timeoutMs)));
+}
+function waitWithDeadline(promise, timeoutMs, signal) {
+  let timer;
+  const timeout = new Promise((resolve2) => {
+    timer = setTimeout(() => resolve2({ timedOut: true }), timeoutMs);
+  });
+  return abortable(Promise.race([
+    promise.then((value) => ({ timedOut: false, value })),
+    timeout
+  ]), signal).finally(() => {
+    if (timer !== undefined)
+      clearTimeout(timer);
+  });
+}
+async function waitForSubagentResult(record, timeoutMs, signal) {
+  const deadline = Date.now() + timeoutMs;
+  while (record.status === "queued") {
+    const remainingMs2 = deadline - Date.now();
+    if (remainingMs2 <= 0)
+      return true;
+    await abortable(new Promise((resolve2) => setTimeout(resolve2, Math.min(RESULT_WAIT_QUEUE_POLL_MS, remainingMs2))), signal);
+  }
+  if (!record.promise)
+    return false;
+  const remainingMs = deadline - Date.now();
+  if (remainingMs <= 0)
+    return true;
+  return (await waitWithDeadline(record.promise, remainingMs, signal)).timedOut;
+}
+var LARKIN_BOUNDED_WAIT_CAPABILITY = "larkin-pi-subagents-bounded-wait-v1";
 function renderRunningAgentStatus(frame, statsText, activity, theme) {
   const container = new Container;
   container.addChild(new Text(theme.fg("accent", frame) + (statsText ? " " + statsText : ""), 0, 0));
@@ -7287,7 +7324,10 @@ function src_default(pi) {
   const agentActivity = new Map;
   const pendingNudges = new Map;
   const NUDGE_HOLD_MS = 200;
-  const QUEUE_WAIT_POLL_MS = Math.floor(NUDGE_HOLD_MS / 4);
+  let resultWaitConsumedInParentTurn = false;
+  pi.on("agent_start", () => {
+    resultWaitConsumedInParentTurn = false;
+  });
   function scheduleNudge(key, send, delay = NUDGE_HOLD_MS) {
     cancelNudge(key);
     pendingNudges.set(key, setTimeout(() => {
@@ -8147,6 +8187,9 @@ You will be notified when this agent completes.
       wait: Type.Optional(Type.Boolean({
         description: "If true, wait for the agent to complete before returning. Default: false."
       })),
+      timeout_ms: Type.Optional(Type.Number({
+        description: "Maximum wait in milliseconds when wait is true. Defaults to 30000 and is capped at 60000."
+      })),
       verbose: Type.Optional(Type.Boolean({
         description: "If true, include the agent's full conversation (messages + tool calls). Default: false."
       }))
@@ -8156,12 +8199,14 @@ You will be notified when this agent completes.
       if (!record) {
         return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
       }
+      if (params.wait && resultWaitConsumedInParentTurn) {
+        throw new Error("Refusing wait: true after an earlier wait began in this parent turn; yield and await the completion notification instead.");
+      }
+      let timedOut = false;
+      const waitTimeoutMs = normalizeResultWaitTimeout(params.timeout_ms);
       if (params.wait && (record.status === "running" || record.status === "queued")) {
-        while (record.status === "queued") {
-          await abortable(new Promise((resolve2) => setTimeout(resolve2, QUEUE_WAIT_POLL_MS)), signal);
-        }
-        if (record.promise)
-          await abortable(record.promise, signal);
+        resultWaitConsumedInParentTurn = true;
+        timedOut = await waitForSubagentResult(record, waitTimeoutMs, signal);
       }
       const displayName = getDisplayName(record.type);
       const duration = formatDuration(record.startedAt, record.completedAt);
@@ -8176,12 +8221,12 @@ You will be notified when this agent completes.
         statsParts.push(`Compactions: ${record.compactionCount}`);
       statsParts.push(`Duration: ${duration}`);
       let output = `Agent: ${record.id}
-` + `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}
+` + `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)}${timedOut ? " | timedOut: true" : ""} | ${statsParts.join(" | ")}
 ` + `Description: ${record.description}
 
 `;
-      if (record.status === "running") {
-        output += "Agent is still running. Use wait: true or check back later.";
+      if (record.status === "running" || record.status === "queued") {
+        output += timedOut ? `Agent is still ${record.status}. Wait timed out after ${waitTimeoutMs}ms; the background agent was not cancelled. Yield/end this turn and await the completion notification; do not call wait: true again.` : "Agent is still running. Use wait: true or check back later.";
       } else if (record.status === "error") {
         output += `Error: ${record.error}${partialOutputSuffix(record)}`;
       } else {
@@ -8985,6 +9030,8 @@ ${systemPrompt}
   });
 }
 export {
+  waitForSubagentResult,
   renderRunningAgentStatus,
-  src_default as default
+  src_default as default,
+  LARKIN_BOUNDED_WAIT_CAPABILITY
 };

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "larkin",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "private": false,
   "larkinPackageRole": "npm-published",
   "files": [
     "dist/",
+    "patches/",
     "assets/",
     "scripts/npm/",
     "README.md",
@@ -114,5 +115,8 @@
     "typescript": "^7.0.2",
     "vite": "^8.1.5",
     "vitest": "^4.1.10"
+  },
+  "patchedDependencies": {
+    "@tintinweb/pi-subagents@0.14.3": "patches/@tintinweb%2Fpi-subagents@0.14.3.patch"
   }
 }

package/patches/@tintinweb%2Fpi-subagents@0.14.3.patch

@@ -0,0 +1,249 @@
+diff --git a/node_modules/@tintinweb/pi-subagents/.bun-tag-58e08ce8246a76a0 b/.bun-tag-58e08ce8246a76a0
+new file mode 100644
+index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
+diff --git a/node_modules/@tintinweb/pi-subagents/.bun-tag-6ef69510e99ece5d b/.bun-tag-6ef69510e99ece5d
+new file mode 100644
+index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
+diff --git a/node_modules/@tintinweb/pi-subagents/.bun-tag-80c5d241789d23ea b/.bun-tag-80c5d241789d23ea
+new file mode 100644
+index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
+diff --git a/dist/index.js b/dist/index.js
+index ab65ef15b5c1da803c0378b1d0ba383645198028..dc18e00d2ce4bddb6ee77608364d3c8b39fdfd60 100644
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -69,6 +69,44 @@ function abortable(promise, signal) {
+         });
+     });
+ }
++const RESULT_WAIT_QUEUE_POLL_MS = 50;
++const DEFAULT_RESULT_WAIT_TIMEOUT_MS = 30000;
++const MAX_RESULT_WAIT_TIMEOUT_MS = 60000;
++function normalizeResultWaitTimeout(timeoutMs) {
++    if (timeoutMs === undefined || !Number.isFinite(timeoutMs))
++        return DEFAULT_RESULT_WAIT_TIMEOUT_MS;
++    return Math.max(1, Math.min(MAX_RESULT_WAIT_TIMEOUT_MS, Math.floor(timeoutMs)));
++}
++function waitWithDeadline(promise, timeoutMs, signal) {
++    let timer;
++    const timeout = new Promise((resolve) => {
++        timer = setTimeout(() => resolve({ timedOut: true }), timeoutMs);
++    });
++    return abortable(Promise.race([
++        promise.then((value) => ({ timedOut: false, value })),
++        timeout,
++    ]), signal).finally(() => {
++        if (timer !== undefined)
++            clearTimeout(timer);
++    });
++}
++/** Wait for one background record without cancelling it when the deadline expires. */
++export async function waitForSubagentResult(record, timeoutMs, signal) {
++    const deadline = Date.now() + timeoutMs;
++    while (record.status === "queued") {
++        const remainingMs = deadline - Date.now();
++        if (remainingMs <= 0)
++            return true;
++        await abortable(new Promise((resolve) => setTimeout(resolve, Math.min(RESULT_WAIT_QUEUE_POLL_MS, remainingMs))), signal);
++    }
++    if (!record.promise)
++        return false;
++    const remainingMs = deadline - Date.now();
++    if (remainingMs <= 0)
++        return true;
++    return (await waitWithDeadline(record.promise, remainingMs, signal)).timedOut;
++}
++const LARKIN_BOUNDED_WAIT_CAPABILITY = "larkin-pi-subagents-bounded-wait-v1";
+ export function renderRunningAgentStatus(frame, statsText, activity, theme) {
+     const container = new Container();
+     container.addChild(new Text(theme.fg("accent", frame) + (statsText ? " " + statsText : ""), 0, 0));
+@@ -280,9 +318,14 @@ export default function (pi) {
+     // before they reach pi.sendMessage (fire-and-forget).
+     const pendingNudges = new Map();
+     const NUDGE_HOLD_MS = 200;
++    // A parent agent run may span multiple model turns. Consume the one-wait
++    // budget when a queued/running wait begins, rather than only after timeout.
++    let resultWaitConsumedInParentTurn = false;
++    pi.on("agent_start", () => {
++        resultWaitConsumedInParentTurn = false;
++    });
+     // A queued result wait must observe completion before its held notification
+     // can fire, so successful waits can still suppress that redundant nudge.
+-    const QUEUE_WAIT_POLL_MS = Math.floor(NUDGE_HOLD_MS / 4);
+     function scheduleNudge(key, send, delay = NUDGE_HOLD_MS) {
+         cancelNudge(key);
+         pendingNudges.set(key, setTimeout(() => {
+@@ -1293,6 +1336,9 @@ Terse command-style prompts produce shallow, generic work.
+             wait: Type.Optional(Type.Boolean({
+                 description: "If true, wait for the agent to complete before returning. Default: false.",
+             })),
++            timeout_ms: Type.Optional(Type.Number({
++                description: "Maximum wait in milliseconds when wait is true. Defaults to 30000 and is capped at 60000.",
++            })),
+             verbose: Type.Optional(Type.Boolean({
+                 description: "If true, include the agent's full conversation (messages + tool calls). Default: false.",
+             })),
+@@ -1307,12 +1353,15 @@ Terse command-style prompts produce shallow, generic work.
+             // completion notification can still be delivered.
+             // Queued agents have no promise yet (it's created when the queue starts
+             // them), so poll until they leave the queue, then await like a running one.
++            // One deadline covers both phases so queue polling cannot reset the wait.
++            if (params.wait && resultWaitConsumedInParentTurn) {
++                throw new Error("Refusing wait: true after an earlier wait began in this parent turn; yield and await the completion notification instead.");
++            }
++            let timedOut = false;
++            const waitTimeoutMs = normalizeResultWaitTimeout(params.timeout_ms);
+             if (params.wait && (record.status === "running" || record.status === "queued")) {
+-                while (record.status === "queued") {
+-                    await abortable(new Promise((resolve) => setTimeout(resolve, QUEUE_WAIT_POLL_MS)), signal);
+-                }
+-                if (record.promise)
+-                    await abortable(record.promise, signal);
++                resultWaitConsumedInParentTurn = true;
++                timedOut = await waitForSubagentResult(record, waitTimeoutMs, signal);
+             }
+             const displayName = getDisplayName(record.type);
+             const duration = formatDuration(record.startedAt, record.completedAt);
+@@ -1327,10 +1376,12 @@ Terse command-style prompts produce shallow, generic work.
+                 statsParts.push(`Compactions: ${record.compactionCount}`);
+             statsParts.push(`Duration: ${duration}`);
+             let output = `Agent: ${record.id}\n` +
+-                `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
++                `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)}${timedOut ? " | timedOut: true" : ""} | ${statsParts.join(" | ")}\n` +
+                 `Description: ${record.description}\n\n`;
+-            if (record.status === "running") {
+-                output += "Agent is still running. Use wait: true or check back later.";
++            if (record.status === "running" || record.status === "queued") {
++                output += timedOut
++                    ? `Agent is still ${record.status}. Wait timed out after ${waitTimeoutMs}ms; the background agent was not cancelled. Yield/end this turn and await the completion notification; do not call wait: true again.`
++                    : "Agent is still running. Use wait: true or check back later.";
+             }
+             else if (record.status === "error") {
+                 output += `Error: ${record.error}${partialOutputSuffix(record)}`;
+diff --git a/src/index.ts b/src/index.ts
+index 828938e6d710dc5a8f99a6185e37f9592b12352d..fb2d3119a50c6aa9c8864037af65ff95bbe4bb1f 100644
+--- a/src/index.ts
++++ b/src/index.ts
+@@ -91,6 +91,54 @@ function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+   });
+ }
+ 
++const RESULT_WAIT_QUEUE_POLL_MS = 50;
++const DEFAULT_RESULT_WAIT_TIMEOUT_MS = 30_000;
++const MAX_RESULT_WAIT_TIMEOUT_MS = 60_000;
++
++function normalizeResultWaitTimeout(timeoutMs: number | undefined): number {
++  if (timeoutMs === undefined || !Number.isFinite(timeoutMs)) return DEFAULT_RESULT_WAIT_TIMEOUT_MS;
++  return Math.max(1, Math.min(MAX_RESULT_WAIT_TIMEOUT_MS, Math.floor(timeoutMs)));
++}
++
++function waitWithDeadline<T>(promise: Promise<T>, timeoutMs: number, signal?: AbortSignal): Promise<{ timedOut: true } | { timedOut: false; value: T }> {
++  let timer: ReturnType<typeof setTimeout> | undefined;
++  const timeout = new Promise<{ timedOut: true }>((resolve) => {
++    timer = setTimeout(() => resolve({ timedOut: true }), timeoutMs);
++  });
++  return abortable(
++    Promise.race([
++      promise.then((value) => ({ timedOut: false as const, value })),
++      timeout,
++    ]),
++    signal,
++  ).finally(() => {
++    if (timer !== undefined) clearTimeout(timer);
++  });
++}
++
++/** Wait for one background record without cancelling it when the deadline expires. */
++export async function waitForSubagentResult(
++  record: Pick<AgentRecord, "status" | "promise">,
++  timeoutMs: number,
++  signal?: AbortSignal,
++): Promise<boolean> {
++  const deadline = Date.now() + timeoutMs;
++  while (record.status === "queued") {
++    const remainingMs = deadline - Date.now();
++    if (remainingMs <= 0) return true;
++    await abortable(
++      new Promise<void>((resolve) => setTimeout(resolve, Math.min(RESULT_WAIT_QUEUE_POLL_MS, remainingMs))),
++      signal,
++    );
++  }
++  if (!record.promise) return false;
++  const remainingMs = deadline - Date.now();
++  if (remainingMs <= 0) return true;
++  return (await waitWithDeadline(record.promise, remainingMs, signal)).timedOut;
++}
++
++export const LARKIN_BOUNDED_WAIT_CAPABILITY = "larkin-pi-subagents-bounded-wait-v1";
++
+ export function renderRunningAgentStatus(
+   frame: string,
+   statsText: string,
+@@ -330,10 +378,14 @@ export default function (pi: ExtensionAPI) {
+   // before they reach pi.sendMessage (fire-and-forget).
+   const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+   const NUDGE_HOLD_MS = 200;
++  // A parent agent run may span multiple model turns. Consume the one-wait
++  // budget when a queued/running wait begins, rather than only after timeout.
++  let resultWaitConsumedInParentTurn = false;
++  pi.on("agent_start", () => {
++    resultWaitConsumedInParentTurn = false;
++  });
+   // A queued result wait must observe completion before its held notification
+   // can fire, so successful waits can still suppress that redundant nudge.
+-  const QUEUE_WAIT_POLL_MS = Math.floor(NUDGE_HOLD_MS / 4);
+-
+   function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
+     cancelNudge(key);
+     pendingNudges.set(key, setTimeout(() => {
+@@ -1453,6 +1505,11 @@ Terse command-style prompts produce shallow, generic work.
+           description: "If true, wait for the agent to complete before returning. Default: false.",
+         }),
+       ),
++      timeout_ms: Type.Optional(
++        Type.Number({
++          description: "Maximum wait in milliseconds when wait is true. Defaults to 30000 and is capped at 60000.",
++        }),
++      ),
+       verbose: Type.Optional(
+         Type.Boolean({
+           description: "If true, include the agent's full conversation (messages + tool calls). Default: false.",
+@@ -1470,14 +1527,15 @@ Terse command-style prompts produce shallow, generic work.
+       // completion notification can still be delivered.
+       // Queued agents have no promise yet (it's created when the queue starts
+       // them), so poll until they leave the queue, then await like a running one.
++      // One deadline covers both phases so queue polling cannot reset the wait.
++      if (params.wait && resultWaitConsumedInParentTurn) {
++        throw new Error("Refusing wait: true after an earlier wait began in this parent turn; yield and await the completion notification instead.");
++      }
++      let timedOut = false;
++      const waitTimeoutMs = normalizeResultWaitTimeout(params.timeout_ms);
+       if (params.wait && (record.status === "running" || record.status === "queued")) {
+-        while (record.status === "queued") {
+-          await abortable(
+-            new Promise<void>((resolve) => setTimeout(resolve, QUEUE_WAIT_POLL_MS)),
+-            signal,
+-          );
+-        }
+-        if (record.promise) await abortable(record.promise, signal);
++        resultWaitConsumedInParentTurn = true;
++        timedOut = await waitForSubagentResult(record, waitTimeoutMs, signal);
+       }
+ 
+       const displayName = getDisplayName(record.type);
+@@ -1492,11 +1550,13 @@ Terse command-style prompts produce shallow, generic work.
+ 
+       let output =
+         `Agent: ${record.id}\n` +
+-        `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
++        `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)}${timedOut ? " | timedOut: true" : ""} | ${statsParts.join(" | ")}\n` +
+         `Description: ${record.description}\n\n`;
+ 
+-      if (record.status === "running") {
+-        output += "Agent is still running. Use wait: true or check back later.";
++      if (record.status === "running" || record.status === "queued") {
++        output += timedOut
++          ? `Agent is still ${record.status}. Wait timed out after ${waitTimeoutMs}ms; the background agent was not cancelled. Yield/end this turn and await the completion notification; do not call wait: true again.`
++          : "Agent is still running. Use wait: true or check back later.";
+       } else if (record.status === "error") {
+         output += `Error: ${record.error}${partialOutputSuffix(record)}`;
+       } else {