larkin 0.4.14 → 0.4.16

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/app/setup.mjs

@@ -190,8 +190,9 @@ export async function main() {
         die(`setup 完成但 Agent ${selectedAgentId} 配置不可读`);
     if (!["codex", "claude", "pi"].includes(configuredAgent.runtime))
         die(`Runtime ${configuredAgent.runtime} 不受支持`);
-    // 非交互（Agent 驱动）时跳过 RPC probe：无 TTY 环境无法进行 pi RPC，探测留到 daemon 启动；
-    // 其余真实阻塞（缺 runtime 可执行文件 / 缺 key / 缺 lark-cli）一律 fast-fail 并给出 agent 可读的修复提示。
+    // 非交互（Agent 驱动）时仍跳过 probeNativeRuntimeReadiness：该探测保持 interactive-only。
+    // external-pi 绑定已在 setup-bind 内做非交互 Pi RPC catalog discovery（RPC over pipes 不需要 TTY）；
+    // daemon attach 探测仍是权威校验。其余真实阻塞（缺 runtime 可执行文件 / 缺 key / 缺 lark-cli）一律 fast-fail。
     if (!OPT.nonInteractive) {
         const runtimeReadiness = await probeNativeRuntimeReadiness({ runtime: configuredAgent.runtime,
             agentId: selectedAgentId, cwd: configuredAgent.workspaceDir,

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-profile-migration.cjs

@@ -32,8 +32,12 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.releasePiProfileMigrationLock = releasePiProfileMigrationLock;
+exports.clearStalePiProfileMigrationLock = clearStalePiProfileMigrationLock;
 exports.preparePiProfileMigration = preparePiProfileMigration;
 exports.validatePiProfileMigrationState = validatePiProfileMigrationState;
 exports.assertPiProfileMigrationAfterState = assertPiProfileMigrationAfterState;
@@ -44,6 +48,7 @@ const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const node_child_process_1 = require("node:child_process");
+const process_inspect_cjs_1 = __importDefault(require("../platform/process-inspect.cjs"));
 const runtime_readiness_js_1 = require("./runtime-readiness.cjs");
 const pi_compaction_recovery_js_1 = require("./pi-compaction-recovery.cjs");
 const pi_provider_config_js_1 = require("./pi-provider-config.cjs");
@@ -87,6 +92,109 @@ function releasePiProfileMigrationLock(state) {
             throw error;
     }
 }
+const TARGET_BUSY = "Pi provider target is busy";
+function migrationLockPath(configDir, agentId) {
+    if (!AGENT_ID.test(agentId))
+        throw new Error("Pi Agent ID 格式无效");
+    return path.join(path.resolve(configDir), "providers", "pi", `${agentId}${TARGET_LOCK_SUFFIX}`);
+}
+function lockPidFromBytes(bytes) {
+    const text = bytes.toString("utf8");
+    if (text.endsWith("\n") ? text.slice(0, -1).includes("\n") : text.includes("\n"))
+        return null;
+    const line = text.endsWith("\n") ? text.slice(0, -1) : text;
+    if (!/^[1-9][0-9]*$/.test(line))
+        return null;
+    const pid = Number(line);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+function inspectOwnedLock(file) {
+    let fd;
+    try {
+        const initial = fs.lstatSync(file);
+        if (initial.isSymbolicLink() || !initial.isFile() || initial.nlink !== 1 || (initial.mode & 0o777) !== 0o600) {
+            throw new Error(TARGET_BUSY);
+        }
+        assertOwner(initial, "Pi provider lock");
+        const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+        fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+        const before = fs.fstatSync(fd);
+        if (!before.isFile() || before.nlink !== 1 || (before.mode & 0o777) !== 0o600)
+            throw new Error(TARGET_BUSY);
+        assertOwner(before, "Pi provider lock");
+        const bytes = Buffer.allocUnsafe(before.size);
+        let offset = 0;
+        while (offset < before.size) {
+            const read = fs.readSync(fd, bytes, offset, before.size - offset, null);
+            if (read === 0)
+                throw new Error(TARGET_BUSY);
+            offset += read;
+        }
+        const after = fs.fstatSync(fd);
+        if (after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size || after.nlink !== before.nlink
+            || after.uid !== before.uid || (after.mode & 0o777) !== 0o600)
+            throw new Error(TARGET_BUSY);
+        const pid = lockPidFromBytes(bytes.subarray(0, after.size));
+        if (pid === null)
+            throw new Error(TARGET_BUSY);
+        return { pid, dev: after.dev, ino: after.ino };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        if (error.code === "ELOOP")
+            throw new Error(TARGET_BUSY);
+        if (error instanceof Error && error.message === TARGET_BUSY)
+            throw error;
+        if (error instanceof Error && /unsafe/.test(error.message))
+            throw new Error(TARGET_BUSY);
+        throw new Error(TARGET_BUSY);
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/** Reclaim a credential-adjacent import lock only when it is a proven-dead owned regular file. */
+function clearStalePiProfileMigrationLock(configDir, agentId, options = {}) {
+    const file = migrationLockPath(configDir, agentId);
+    assertNoSymlinkAncestors(path.dirname(file));
+    const inspected = inspectOwnedLock(file);
+    if (!inspected)
+        return;
+    const kill = options.kill ?? process.kill;
+    if (process_inspect_cjs_1.default.pidAlive(inspected.pid, kill))
+        throw new Error(TARGET_BUSY);
+    const quarantine = `${file}.stale-${process.pid}-${crypto.randomUUID()}`;
+    try {
+        fs.renameSync(file, quarantine);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw new Error(TARGET_BUSY);
+    }
+    fsyncDirectory(path.dirname(file));
+    try {
+        const quarantined = fs.lstatSync(quarantine);
+        if (quarantined.isSymbolicLink() || !quarantined.isFile() || quarantined.nlink !== 1
+            || (quarantined.mode & 0o777) !== 0o600 || quarantined.dev !== inspected.dev || quarantined.ino !== inspected.ino) {
+            throw new Error(TARGET_BUSY);
+        }
+        assertOwner(quarantined, "Pi provider lock");
+        const bytes = fs.readFileSync(quarantine);
+        if (lockPidFromBytes(bytes) !== inspected.pid || process_inspect_cjs_1.default.pidAlive(inspected.pid, kill)) {
+            throw new Error(TARGET_BUSY);
+        }
+    }
+    finally {
+        try {
+            fs.unlinkSync(quarantine);
+        }
+        catch { /* quarantine is not the live lock path */ }
+        fsyncDirectory(path.dirname(file));
+    }
+}
 function isKnownSystemSymlink(value) {
     return value === "/tmp" || value === "/private/tmp" || value === "/var" || value === "/private/var"
         || value === "/var/folders" || /^\/var\/folders\/[^/]+$/.test(value)
@@ -263,7 +371,7 @@ function preparePiProfileMigration(env, configDir, agentId, distribution = "buil
     const sourceDirectoryState = assertDirectory(sourceDir, "external Pi profile");
     const sourceExecutable = sourceVersion(env, sourceDir);
     const sourceFiles = Object.fromEntries(FILES.map((name) => {
-        const file = readRegular(path.join(sourceDir, name), `external Pi ${name}`);
+        const file = readRegular(path.join(sourceDir, name), `external Pi ${name}`, false);
         if (!file)
             throw new Error(`external Pi ${name} is required`);
         if (name === "auth.json" && file.mode !== 0o600)

package/dist/runtime/pi-profile-migration.mjs

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { spawnSync } from "node:child_process";
+import processInspect from "../platform/process-inspect.cjs";
 import { resolveRuntimeExecutable } from "./runtime-readiness.mjs";
 import { mergeOwnedPiSettings, parsePiExecutableVersion } from "./pi-compaction-recovery.mjs";
 import { BUNDLED_PI_VERSION } from "./pi-provider-config.mjs";
@@ -46,6 +47,109 @@ export function releasePiProfileMigrationLock(state) {
             throw error;
     }
 }
+const TARGET_BUSY = "Pi provider target is busy";
+function migrationLockPath(configDir, agentId) {
+    if (!AGENT_ID.test(agentId))
+        throw new Error("Pi Agent ID 格式无效");
+    return path.join(path.resolve(configDir), "providers", "pi", `${agentId}${TARGET_LOCK_SUFFIX}`);
+}
+function lockPidFromBytes(bytes) {
+    const text = bytes.toString("utf8");
+    if (text.endsWith("\n") ? text.slice(0, -1).includes("\n") : text.includes("\n"))
+        return null;
+    const line = text.endsWith("\n") ? text.slice(0, -1) : text;
+    if (!/^[1-9][0-9]*$/.test(line))
+        return null;
+    const pid = Number(line);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+function inspectOwnedLock(file) {
+    let fd;
+    try {
+        const initial = fs.lstatSync(file);
+        if (initial.isSymbolicLink() || !initial.isFile() || initial.nlink !== 1 || (initial.mode & 0o777) !== 0o600) {
+            throw new Error(TARGET_BUSY);
+        }
+        assertOwner(initial, "Pi provider lock");
+        const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+        fd = fs.openSync(file, fs.constants.O_RDONLY | noFollow);
+        const before = fs.fstatSync(fd);
+        if (!before.isFile() || before.nlink !== 1 || (before.mode & 0o777) !== 0o600)
+            throw new Error(TARGET_BUSY);
+        assertOwner(before, "Pi provider lock");
+        const bytes = Buffer.allocUnsafe(before.size);
+        let offset = 0;
+        while (offset < before.size) {
+            const read = fs.readSync(fd, bytes, offset, before.size - offset, null);
+            if (read === 0)
+                throw new Error(TARGET_BUSY);
+            offset += read;
+        }
+        const after = fs.fstatSync(fd);
+        if (after.dev !== before.dev || after.ino !== before.ino || after.size !== before.size || after.nlink !== before.nlink
+            || after.uid !== before.uid || (after.mode & 0o777) !== 0o600)
+            throw new Error(TARGET_BUSY);
+        const pid = lockPidFromBytes(bytes.subarray(0, after.size));
+        if (pid === null)
+            throw new Error(TARGET_BUSY);
+        return { pid, dev: after.dev, ino: after.ino };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        if (error.code === "ELOOP")
+            throw new Error(TARGET_BUSY);
+        if (error instanceof Error && error.message === TARGET_BUSY)
+            throw error;
+        if (error instanceof Error && /unsafe/.test(error.message))
+            throw new Error(TARGET_BUSY);
+        throw new Error(TARGET_BUSY);
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/** Reclaim a credential-adjacent import lock only when it is a proven-dead owned regular file. */
+export function clearStalePiProfileMigrationLock(configDir, agentId, options = {}) {
+    const file = migrationLockPath(configDir, agentId);
+    assertNoSymlinkAncestors(path.dirname(file));
+    const inspected = inspectOwnedLock(file);
+    if (!inspected)
+        return;
+    const kill = options.kill ?? process.kill;
+    if (processInspect.pidAlive(inspected.pid, kill))
+        throw new Error(TARGET_BUSY);
+    const quarantine = `${file}.stale-${process.pid}-${crypto.randomUUID()}`;
+    try {
+        fs.renameSync(file, quarantine);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw new Error(TARGET_BUSY);
+    }
+    fsyncDirectory(path.dirname(file));
+    try {
+        const quarantined = fs.lstatSync(quarantine);
+        if (quarantined.isSymbolicLink() || !quarantined.isFile() || quarantined.nlink !== 1
+            || (quarantined.mode & 0o777) !== 0o600 || quarantined.dev !== inspected.dev || quarantined.ino !== inspected.ino) {
+            throw new Error(TARGET_BUSY);
+        }
+        assertOwner(quarantined, "Pi provider lock");
+        const bytes = fs.readFileSync(quarantine);
+        if (lockPidFromBytes(bytes) !== inspected.pid || processInspect.pidAlive(inspected.pid, kill)) {
+            throw new Error(TARGET_BUSY);
+        }
+    }
+    finally {
+        try {
+            fs.unlinkSync(quarantine);
+        }
+        catch { /* quarantine is not the live lock path */ }
+        fsyncDirectory(path.dirname(file));
+    }
+}
 function isKnownSystemSymlink(value) {
     return value === "/tmp" || value === "/private/tmp" || value === "/var" || value === "/private/var"
         || value === "/var/folders" || /^\/var\/folders\/[^/]+$/.test(value)
@@ -222,7 +326,7 @@ export function preparePiProfileMigration(env, configDir, agentId, distribution
     const sourceDirectoryState = assertDirectory(sourceDir, "external Pi profile");
     const sourceExecutable = sourceVersion(env, sourceDir);
     const sourceFiles = Object.fromEntries(FILES.map((name) => {
-        const file = readRegular(path.join(sourceDir, name), `external Pi ${name}`);
+        const file = readRegular(path.join(sourceDir, name), `external Pi ${name}`, false);
         if (!file)
             throw new Error(`external Pi ${name} is required`);
         if (name === "auth.json" && file.mode !== 0o600)

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/dist/setup/setup-bind.mjs

@@ -9,7 +9,10 @@ import { fileURLToPath } from "node:url";
 import { isWindows } from "../platform/secure-metadata.mjs";
 import { TargetRootLayout } from "../platform/root-layout.mjs";
 import { planSingleRootBinding } from "./setup-binding.mjs";
-import { configureBuiltinPiProviderModel } from "../runtime/pi-provider-config.mjs";
+import { configureBuiltinPiProviderModel, piAgentDirectory } from "../runtime/pi-provider-config.mjs";
+import { applyPiProfileMigration, clearStalePiProfileMigrationLock, preparePiProfileMigration, releasePiProfileMigrationLock, rollbackPiProfileMigration, } from "../runtime/pi-profile-migration.mjs";
+import { discoverPiModelCatalog } from "../runtime/pi-model-catalog.mjs";
+import { calculatePiCompactionSettings } from "../runtime/pi-compaction-recovery.mjs";
 import { terminalSetupQuestioner } from "./setup-agent-choice.mjs";
 import { beginBuiltinPiCredentialTransaction, createOfficialPiAuthInteraction, createOfficialPiModelRuntime, runOfficialPiLogin, verifyOfficialPiProviderTurn, } from "../runtime/pi-official-auth.mjs";
 import * as larkinConfigImport from "../platform/config.mjs";
@@ -195,6 +198,30 @@ function fabricateAttachment(root, serverId) {
     };
     fs.writeFileSync(file, JSON.stringify(attachment, null, 2), { mode: 0o600 });
 }
+function catalogModelsFromError(error) {
+    if (!error || typeof error !== "object" || !("catalogModels" in error))
+        return [];
+    const models = error.catalogModels;
+    return Array.isArray(models) ? models.filter((id) => typeof id === "string" && id.length > 0) : [];
+}
+function formatExternalPiSetupFailure(error, options) {
+    const original = (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ").trim();
+    const alternatives = catalogModelsFromError(error);
+    const parts = [];
+    if (/external Pi (?:auth\.json|models\.json|settings\.json) is required|external Pi profile|external Pi auth\.json has an unsafe mode|external Pi models\.json has an unsafe mode|external Pi settings\.json has an unsafe mode/.test(original)) {
+        parts.push("external-pi requires the official file-backed Pi profile containing auth.json (0600), models.json, and settings.json, normally after `pi` login and default-model selection. Environment-variable-only credentials are unsupported.");
+    }
+    if (original)
+        parts.push(original);
+    parts.push("Fix the official `pi` login and default model, then rerun `larkin setup --runtime external-pi`.");
+    if (options.agentExisted) {
+        parts.push("This Agent already exists; after a successful setup you can switch models with `larkin model <provider>/<model>`.");
+    }
+    if (alternatives.length) {
+        parts.push(`Alternative models that report a context window: ${alternatives.join(", ")}.`);
+    }
+    return parts.join(" ");
+}
 function safeProviderFailure(error) {
     const message = error instanceof Error ? error.message : String(error);
     if (/\b(?:401|403)\b|unauth|invalid.*(?:key|token)|credential/i.test(message)) {
@@ -267,49 +294,90 @@ export async function main() {
     validateRuntime(runtime);
     const defaultModel = larkinConfig.defaultModelFor(runtime);
     const selectedModel = selection?.runtime === "pi" && selection.distribution === "builtin" ? selection.model : undefined;
-    const targetModelId = selectedModel || (prior?.runtime === runtime ? prior.model : defaultModel);
-    let runtimeModels = larkinConfig.loadRuntimeModels()[runtime];
-    if (runtime === "pi") {
-        const preservedEffort = prior?.runtime === "pi" && typeof prior.effort === "string" && prior.effort.trim()
-            ? [prior.effort]
-            : [];
-        runtimeModels = [{ id: targetModelId, supportedReasoningEfforts: preservedEffort }];
-    }
-    const targetModel = runtimeModels.find((model) => model.id === targetModelId);
-    if (!targetModel)
-        die(`目标模型 ${runtime}/${targetModelId} 不在 runtime 模型目录中；未修改 Agent 配置`);
-    const stored = planSingleRootBinding({
-        config: larkinConfig.toStored(config),
-        profile,
-        requestedAgent,
-        runtime: selection?.runtime || options.runtime,
-        ...(runtime === "pi" && piDistribution ? { piDistribution } : {}),
-        ...(selectedModel ? { model: selectedModel } : {}),
-        defaultModel,
-        supportedReasoningEfforts: targetModel.supportedReasoningEfforts || [],
-        now: new Date().toISOString(),
-    });
-    const bound = stored.agents[profile.appId];
-    fs.mkdirSync(CFG_DIR, { recursive: true });
+    let targetModelId = selectedModel || (prior?.runtime === runtime ? prior.model : defaultModel);
+    let resolvedExternalModel;
+    let pendingMigration = null;
+    let setupConfigCommitted = false;
     let providerTransaction = null;
     let providerPublished = false;
-    const authAlreadyCompleted = selection?.runtime === "pi" && selection.distribution === "builtin"
-        && selection.authCompleted === true;
-    const readinessAlreadyCompleted = authAlreadyCompleted
-        && selection.readinessCompleted === true;
     const authAbort = new AbortController();
-    const cancelProviderTransaction = (signal) => {
+    const cancelOnSignal = (signal) => {
         authAbort.abort();
+        if (!setupConfigCommitted && pendingMigration) {
+            try {
+                rollbackPiProfileMigration(pendingMigration.state);
+            }
+            catch { /* best effort */ }
+        }
         if (!providerPublished)
             providerTransaction?.rollback();
         process.exit(signal === "SIGINT" ? 130 : 143);
     };
-    const onSigint = () => cancelProviderTransaction("SIGINT");
-    const onSigterm = () => cancelProviderTransaction("SIGTERM");
+    const onSigint = () => cancelOnSignal("SIGINT");
+    const onSigterm = () => cancelOnSignal("SIGTERM");
     process.once("SIGINT", onSigint);
     process.once("SIGTERM", onSigterm);
+    let runtimeModels = larkinConfig.loadRuntimeModels()[runtime];
     let authQuestioner = null;
     try {
+        if (runtime === "pi" && piDistribution === "external" && targetModelId === "default") {
+            fs.mkdirSync(CFG_DIR, { recursive: true, mode: 0o700 });
+            try {
+                clearStalePiProfileMigrationLock(CFG_DIR, profile.appId);
+                const plan = preparePiProfileMigration(process.env, CFG_DIR, profile.appId, "external");
+                pendingMigration = plan;
+                applyPiProfileMigration(plan);
+                const catalog = await discoverPiModelCatalog({
+                    cwd: CFG_DIR,
+                    agentDir: piAgentDirectory(CFG_DIR, profile.appId),
+                    env: process.env,
+                });
+                const effective = catalog.effectiveModel;
+                const entry = effective ? catalog.models.find((model) => model.id === effective) : undefined;
+                if (!effective || !entry) {
+                    throw new Error("Pi official default resolution returned an unavailable model");
+                }
+                if (!entry.contextWindow) {
+                    const alternatives = catalog.models
+                        .filter((model) => Number.isFinite(model.contextWindow) && Number(model.contextWindow) > 0)
+                        .map((model) => model.id);
+                    throw Object.assign(new Error("Pi effective model is missing a context window"), { catalogModels: alternatives });
+                }
+                calculatePiCompactionSettings(entry.contextWindow);
+                targetModelId = effective;
+                resolvedExternalModel = effective;
+                runtimeModels = [{ id: effective, supportedReasoningEfforts: entry.supportedReasoningEfforts }];
+            }
+            catch (error) {
+                throw new Error(formatExternalPiSetupFailure(error, { agentExisted: Boolean(prior) }));
+            }
+        }
+        else if (runtime === "pi") {
+            const preservedEffort = prior?.runtime === "pi" && typeof prior.effort === "string" && prior.effort.trim()
+                ? [prior.effort]
+                : [];
+            runtimeModels = [{ id: targetModelId, supportedReasoningEfforts: preservedEffort }];
+        }
+        const targetModel = runtimeModels.find((model) => model.id === targetModelId);
+        if (!targetModel)
+            throw new Error(`目标模型 ${runtime}/${targetModelId} 不在 runtime 模型目录中；未修改 Agent 配置`);
+        const stored = planSingleRootBinding({
+            config: larkinConfig.toStored(config),
+            profile,
+            requestedAgent,
+            runtime: selection?.runtime || options.runtime,
+            ...(runtime === "pi" && piDistribution ? { piDistribution } : {}),
+            ...(selectedModel || resolvedExternalModel ? { model: selectedModel || resolvedExternalModel } : {}),
+            defaultModel,
+            supportedReasoningEfforts: targetModel.supportedReasoningEfforts || [],
+            now: new Date().toISOString(),
+        });
+        const bound = stored.agents[profile.appId];
+        fs.mkdirSync(CFG_DIR, { recursive: true });
+        const authAlreadyCompleted = selection?.runtime === "pi" && selection.distribution === "builtin"
+            && selection.authCompleted === true;
+        const readinessAlreadyCompleted = authAlreadyCompleted
+            && selection.readinessCompleted === true;
         providerTransaction = selection?.runtime === "pi" && selection.distribution === "builtin"
             && !authAlreadyCompleted ? beginBuiltinPiCredentialTransaction(CFG_DIR, profile.appId)
             : null;
@@ -349,10 +417,34 @@ export async function main() {
             }
         }
         larkinConfig.commitSetupConfig(process.env, loaded.revision, stored);
+        setupConfigCommitted = true;
         providerTransaction?.commit();
         providerPublished = true;
+        if (pendingMigration) {
+            try {
+                releasePiProfileMigrationLock(pendingMigration.state);
+            }
+            catch { /* post-commit lock release is best-effort; do not roll back credentials */ }
+            pendingMigration = null;
+        }
+        fabricateAttachment(layout.root, stored.serverId);
+        say(`\n✓ 已写配置: ${CFG_FILE}`);
+        say(`  agent=${profile.appId}  runtime=${bound.runtime}  model=${bound.model}`);
+        say(`  单服务 serverId=${stored.serverId}  larkinHome=${layout.root}`);
+        say("\n启动这个 Agent：");
+        say("  larkin start                     # 单服务启动全部已配置 Agent");
+        say(`  larkin start --agent ${profile.appId}  # 仅调试这个 Agent`);
+        say("创建独立飞书（Lark）机器人 + Agent：");
+        say("  larkin setup");
     }
     catch (error) {
+        if (!setupConfigCommitted && pendingMigration) {
+            try {
+                rollbackPiProfileMigration(pendingMigration.state);
+            }
+            catch { /* best effort */ }
+            pendingMigration = null;
+        }
         providerTransaction?.rollback();
         throw error;
     }
@@ -361,15 +453,6 @@ export async function main() {
         process.off("SIGINT", onSigint);
         process.off("SIGTERM", onSigterm);
     }
-    fabricateAttachment(layout.root, stored.serverId);
-    say(`\n✓ 已写配置: ${CFG_FILE}`);
-    say(`  agent=${profile.appId}  runtime=${bound.runtime}  model=${bound.model}`);
-    say(`  单服务 serverId=${stored.serverId}  larkinHome=${layout.root}`);
-    say("\n启动这个 Agent：");
-    say("  larkin start                     # 单服务启动全部已配置 Agent");
-    say(`  larkin start --agent ${profile.appId}  # 仅调试这个 Agent`);
-    say("创建独立飞书（Lark）机器人 + Agent：");
-    say("  larkin setup");
 }
 if (path.resolve(process.argv[1] || "") === path.resolve(fileURLToPath(import.meta.url))) {
     main().catch((error) => die(error instanceof Error ? error.message : String(error)));

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "larkin",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "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 {