@cortexkit/aft-bridge 0.58.2 → 0.60.0

package/dist/bash-format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bash-format.d.ts","sourceRoot":"","sources":["../src/bash-format.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAiB5E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAQzD;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}
+{"version":3,"file":"bash-format.d.ts","sourceRoot":"","sources":["../src/bash-format.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,gGAAgG;AAChG,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAsB5E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAQzD;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/dist/bash-format.js

@@ -15,6 +15,11 @@ export function formatForegroundResult(data) {
     }
     if (status === "timed_out") {
         rendered += `\n[command timed out]`;
+        // Name the limit that killed it, so AFT's own default limit is not
+        // mistaken for the command failing.
+        if (typeof data.status_reason === "string" && data.status_reason !== "") {
+            rendered += ` ${data.status_reason}`;
+        }
     }
     if (typeof exit === "number" && exit !== 0) {
         rendered += `\n[exit code: ${exit}]`;

package/dist/bash-format.js.map

@@ -1 +1 @@
-{"version":3,"file":"bash-format.js","sourceRoot":"","sources":["../src/bash-format.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,gGAAgG;AAChG,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,OAAO,GAAG,MAAM,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAA6B;IAClE,MAAM,MAAM,GAAI,IAAI,CAAC,cAAqC,IAAI,EAAE,CAAC;IACjE,MAAM,UAAU,GAAG,IAAI,CAAC,WAAiC,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,KAAK,IAAI,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,MAA4B,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,SAA+B,CAAC;IAClD,IAAI,QAAQ,GAAG,MAAM,CAAC;IACtB,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5B,QAAQ,IAAI,uCAAuC,UAAU,GAAG,CAAC;IACnE,CAAC;IACD,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;QAC3B,QAAQ,IAAI,uBAAuB,CAAC;IACtC,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;QAC3C,QAAQ,IAAI,iBAAiB,IAAI,GAAG,CAAC;IACvC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAe;IAC9C,OAAO,CACL,MAAM,KAAK,WAAW;QACtB,MAAM,KAAK,QAAQ;QACnB,MAAM,KAAK,QAAQ;QACnB,MAAM,KAAK,WAAW;QACtB,MAAM,KAAK,cAAc,CAC1B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"bash-format.js","sourceRoot":"","sources":["../src/bash-format.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,gGAAgG;AAChG,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,OAAO,GAAG,MAAM,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAA6B;IAClE,MAAM,MAAM,GAAI,IAAI,CAAC,cAAqC,IAAI,EAAE,CAAC;IACjE,MAAM,UAAU,GAAG,IAAI,CAAC,WAAiC,CAAC;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,KAAK,IAAI,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,MAA4B,CAAC;IACjD,MAAM,IAAI,GAAG,IAAI,CAAC,SAA+B,CAAC;IAClD,IAAI,QAAQ,GAAG,MAAM,CAAC;IACtB,IAAI,SAAS,IAAI,UAAU,EAAE,CAAC;QAC5B,QAAQ,IAAI,uCAAuC,UAAU,GAAG,CAAC;IACnE,CAAC;IACD,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;QAC3B,QAAQ,IAAI,uBAAuB,CAAC;QACpC,mEAAmE;QACnE,oCAAoC;QACpC,IAAI,OAAO,IAAI,CAAC,aAAa,KAAK,QAAQ,IAAI,IAAI,CAAC,aAAa,KAAK,EAAE,EAAE,CAAC;YACxE,QAAQ,IAAI,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvC,CAAC;IACH,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;QAC3C,QAAQ,IAAI,iBAAiB,IAAI,GAAG,CAAC;IACvC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAe;IAC9C,OAAO,CACL,MAAM,KAAK,WAAW;QACtB,MAAM,KAAK,QAAQ;QACnB,MAAM,KAAK,QAAQ;QACnB,MAAM,KAAK,WAAW;QACtB,MAAM,KAAK,cAAc,CAC1B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC;AAC3B,CAAC"}

package/dist/bash-hints.d.ts

@@ -4,38 +4,54 @@ export type WatchCallerRole = "worker" | "primary";
 export declare const DEFAULT_PRIMARY_WATCH_TIMEOUT_MS = 30000;
 /** Largest bash_watch timeout accepted by the OpenCode and Pi plugins' tool schemas. */
 export declare const MAX_WATCH_TIMEOUT_MS = 1800000;
+/**
+ * Default `bash.worker_wait_max_ms`: the longest a delegated worker's wait on
+ * one command blocks before control returns to it. Mirrors
+ * `DEFAULT_BASH_WORKER_WAIT_MAX_MS` in the engine's `config.rs`. A worker that
+ * blocked with no limit once sat behind a stuck test run for fifteen hours;
+ * with the limit it gets control back, sees the command is still running, and
+ * decides whether to wait again or kill it.
+ */
+export declare const DEFAULT_WORKER_WAIT_MAX_MS = 1800000;
+/** Smallest accepted `bash.worker_wait_max_ms`; mirrors `MIN_BASH_WORKER_WAIT_MAX_MS`. */
+export declare const MIN_WORKER_WAIT_MAX_MS = 60000;
 /**
  * Longest delay a JavaScript timer accepts (2^31 - 1 ms, about 24.8 days); a
- * larger one fires almost at once. A bridge request that must wait for a
- * command with no hard-kill timeout uses it as its transport timeout, which
- * in practice means no transport timeout.
+ * larger one fires almost at once. Bridge transport timeouts derived from a
+ * configured limit are clamped to it.
  */
 export declare const LONGEST_TIMER_DELAY_MS = 2147483647;
+/**
+ * How a delegated worker's waits are bounded, worded once for every tool
+ * description. It names the setting, not its value, so the prompt prefix is
+ * the same for every user.
+ */
+export declare const WORKER_WAIT_LIMIT_PHRASE = "the worker wait limit (`bash.worker_wait_max_ms`, 30 minutes by default)";
 /**
  * Description of the bash_watch tool's sync-wait defaults, embedded in both
  * plugins' tool descriptions. Every caller sees the same description, so it
  * has to state both roles' real behaviour.
  */
-export declare const WATCH_SYNC_DEFAULTS_DESCRIPTION = "Sync waits default to 30s in a main session (max `bash.watch_sync_max_ms`, 120s by default); in a delegated session a sync wait without a timeout waits until the command finishes";
+export declare const WATCH_SYNC_DEFAULTS_DESCRIPTION = "Sync waits default to 30s in a main session (max `bash.watch_sync_max_ms`, 120s by default); in a delegated session a sync wait without a timeout waits up to the worker wait limit (`bash.worker_wait_max_ms`, 30 minutes by default), then reports it is still running; watch again to keep waiting. An explicit timeout never exceeds that worker limit";
 /**
  * Description of the bash_watch timeout parameter. Every caller sees the same
  * schema, so it has to be true for both roles.
  */
-export declare const WATCH_TIMEOUT_PARAM_DESCRIPTION = "Sync-only timeout in milliseconds. In a main session: default 30000, max `bash.watch_sync_max_ms` (120000 by default). In a delegated session: omit it to wait until the command finishes; a value you pass is used as given.";
+export declare const WATCH_TIMEOUT_PARAM_DESCRIPTION = "Sync-only timeout in milliseconds. In a main session: default 30000, max `bash.watch_sync_max_ms` (120000 by default). In a delegated session: omit it to wait up to the worker wait limit (`bash.worker_wait_max_ms`, 30 minutes by default), after which the watch reports the command is still running; a value you pass is clamped to that worker limit.";
 /**
- * Effective sync bash_watch deadline in milliseconds, or `undefined` for a
- * wait with no deadline, which lasts until the task exits, a pattern matches,
- * a new message arrives, or the call is aborted.
+ * Effective sync bash_watch deadline in milliseconds.
  *
  * A delegated worker cannot be woken once its turn ends, so it has nothing
- * useful to do while its command runs except wait. Any deadline only makes it
- * call bash_watch again, and every such call re-reads its whole context. It
- * therefore waits with no deadline by default, and a timeout it passes is
- * honoured as given rather than clamped to the configured cap. A primary keeps
- * the short default and the cap because it can do other work or end its turn
- * and be woken by the completion reminder.
+ * useful to do while its command runs except wait, and a short deadline only
+ * makes it call bash_watch again, re-reading its whole context each time. It
+ * therefore waits up to the worker wait limit (`workerWaitMaxMs`,
+ * `bash.worker_wait_max_ms`) by default: long enough that re-watching is
+ * rare, short enough that a stuck command cannot hold it forever. A timeout
+ * it passes is clamped to the worker limit, not to the primary cap. A
+ * primary keeps the short default and the cap because it can do other work
+ * or end its turn and be woken by the completion reminder.
  */
-export declare function resolveWatchTimeoutMs(requestedMs: number | undefined, role: WatchCallerRole, capMs: number): number | undefined;
+export declare function resolveWatchTimeoutMs(requestedMs: number | undefined, role: WatchCallerRole, capMs: number, workerWaitMaxMs: number): number;
 /**
  * Largest bash_watch timeout a caller of this role may pass. A primary is
  * bounded by the configured cap; a worker only by the schema maximum.
@@ -73,18 +89,48 @@ export declare function abortableSleep(ms: number, signal?: AbortSignal): Promis
  */
 export declare function formatWatchWaited(elapsedMs: number, limitMs: number | undefined, capMs: number | undefined): string;
 /**
- * Appended to a bash_watch reply whose sync deadline passed without a match.
- * The deadline is a property of the watch, not of the command: a delegated
- * worker that read the bare "timeout reached" line as its own execution being
- * interrupted declared a failed result while its long-running command was
- * still going. Each role gets only the move that applies to it: a worker must
- * keep watching and not report, while a primary may end its turn because the
- * completion reminder wakes it. A worker only reaches this with a timeout it
- * passed itself, so it is told that leaving the timeout out waits until the
- * command finishes. `timeoutParam` is the host's spelling of the bash_watch
- * timeout argument, so the worker is told a name it can pass.
- */
-export declare function watchTimeoutSteer(role: WatchCallerRole, timeoutParam?: string): string;
+ * Appended to a primary's bash_watch reply whose sync deadline passed without
+ * a match. The deadline is a property of the watch, not of the command, so the
+ * caller is told the command is still running and that the completion
+ * reminder wakes it. A worker gets {@link workerWatchStillRunning} instead.
+ */
+export declare function watchTimeoutSteer(): string;
+/** A duration in words: whole minutes as minutes, anything else in seconds. */
+export declare function formatWaitDuration(ms: number): string;
+/**
+ * The sentence naming a task's own kill deadline, from the `hard_kill` field
+ * and `started_at` of the engine's task status (`{ limit_ms, source }`), or how
+ * the task was killed when its hard kill fired (`status_reason`). It reports an
+ * absolute UTC deadline measured from command start and the approximate time
+ * remaining. Mirrors `kill_deadline_sentence` in the engine.
+ */
+export declare function taskKillDeadlineText(data: Record<string, unknown>, role: WatchCallerRole, nowMs?: number): string;
+/**
+ * A wait should not hand back a still-running task just before its own kill
+ * deadline. Five seconds covers the slowest status poll and kill publication.
+ */
+export declare function taskKillDeadlineWithinHandoffMargin(data: Record<string, unknown>): boolean;
+/** The last lines of `output`, so a worker can judge whether a command is stuck. */
+export declare function outputTail(output: string | undefined): string;
+/**
+ * Appended to a delegated worker's bash_watch reply whose deadline passed
+ * while the command still runs (by default the worker wait limit). The
+ * deadline is a property of the watch, not of the command: a worker that read
+ * a bare "timeout reached" line as its own execution failing declared a
+ * failed result while its command was still going. So it is told plainly that
+ * the command is still running, how long it has run, and its latest output,
+ * then given both moves by name: watch again to keep waiting, or kill a
+ * command that should have finished. `taskIdArg` and `timeoutParam` are the
+ * host's spellings of the bash_watch arguments.
+ */
+export declare function workerWatchStillRunning(options: {
+    taskId: string;
+    waitedMs: number;
+    ranMs: number | undefined;
+    output: string | undefined;
+    taskIdArg?: string;
+    timeoutParam?: string;
+}): string;
 /**
  * How long a sync bash_watch with no deadline keeps retrying while every
  * status poll times out because the bridge is busy. Without this bound a wait
@@ -110,9 +156,9 @@ export declare function interruptedWatchTail(role: WatchCallerRole, primaryTail:
  * command now runs in the background. AFT's own reply already says the task
  * won't wake the worker; this names the plugin-owned bash_watch tool, which
  * AFT cannot assume a host has. The suggested call passes no timeout on
- * purpose: a worker's watch without one waits until the command finishes, so
- * any number would only make it wake and watch again. `taskIdArg` is the
- * host's spelling of the task id argument.
+ * purpose: a worker's watch without one waits up to the worker wait limit,
+ * the longest it may, so any number would only make it wake sooner and watch
+ * again. `taskIdArg` is the host's spelling of the task id argument.
  */
 export declare function workerBackgroundTaskNote(taskId: string, taskIdArg?: string): string;
 /**

package/dist/bash-hints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bash-hints.d.ts","sourceRoot":"","sources":["../src/bash-hints.ts"],"names":[],"mappings":"AAWA,8EAA8E;AAC9E,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEnD,iFAAiF;AACjF,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,aAAgB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,uLAC0I,CAAC;AAEvL;;;GAGG;AACH,eAAO,MAAM,+BAA+B,kOACqL,CAAC;AAElO;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAGpB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK1D;AAED;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE;IACvB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAI5D,CAAC;AAEF,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAW9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,CAOR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,YAAY,SAAc,GAAG,MAAM,CAK3F;AAED;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,6FAC4D,CAAC;AAE7F;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAEvF;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,SAAW,GAAG,MAAM,CAErF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAInE;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAInE;AAqBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAYjE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,mBAAmB,EAAE,OAAO,EAC5B,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAQR"}
+{"version":3,"file":"bash-hints.d.ts","sourceRoot":"","sources":["../src/bash-hints.ts"],"names":[],"mappings":"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"}

package/dist/bash-hints.js

@@ -1,44 +1,61 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { relativePathEscapesRoot } from "./path-display.js";
 /** Sync bash_watch deadline used by a primary session that passes no timeout. */
 export const DEFAULT_PRIMARY_WATCH_TIMEOUT_MS = 30_000;
 /** Largest bash_watch timeout accepted by the OpenCode and Pi plugins' tool schemas. */
 export const MAX_WATCH_TIMEOUT_MS = 1_800_000;
+/**
+ * Default `bash.worker_wait_max_ms`: the longest a delegated worker's wait on
+ * one command blocks before control returns to it. Mirrors
+ * `DEFAULT_BASH_WORKER_WAIT_MAX_MS` in the engine's `config.rs`. A worker that
+ * blocked with no limit once sat behind a stuck test run for fifteen hours;
+ * with the limit it gets control back, sees the command is still running, and
+ * decides whether to wait again or kill it.
+ */
+export const DEFAULT_WORKER_WAIT_MAX_MS = 1_800_000;
+/** Smallest accepted `bash.worker_wait_max_ms`; mirrors `MIN_BASH_WORKER_WAIT_MAX_MS`. */
+export const MIN_WORKER_WAIT_MAX_MS = 60_000;
 /**
  * Longest delay a JavaScript timer accepts (2^31 - 1 ms, about 24.8 days); a
- * larger one fires almost at once. A bridge request that must wait for a
- * command with no hard-kill timeout uses it as its transport timeout, which
- * in practice means no transport timeout.
+ * larger one fires almost at once. Bridge transport timeouts derived from a
+ * configured limit are clamped to it.
  */
 export const LONGEST_TIMER_DELAY_MS = 2_147_483_647;
+/**
+ * How a delegated worker's waits are bounded, worded once for every tool
+ * description. It names the setting, not its value, so the prompt prefix is
+ * the same for every user.
+ */
+export const WORKER_WAIT_LIMIT_PHRASE = "the worker wait limit (`bash.worker_wait_max_ms`, 30 minutes by default)";
 /**
  * Description of the bash_watch tool's sync-wait defaults, embedded in both
  * plugins' tool descriptions. Every caller sees the same description, so it
  * has to state both roles' real behaviour.
  */
-export const WATCH_SYNC_DEFAULTS_DESCRIPTION = "Sync waits default to 30s in a main session (max `bash.watch_sync_max_ms`, 120s by default); in a delegated session a sync wait without a timeout waits until the command finishes";
+export const WATCH_SYNC_DEFAULTS_DESCRIPTION = "Sync waits default to 30s in a main session (max `bash.watch_sync_max_ms`, 120s by default); in a delegated session a sync wait without a timeout waits up to the worker wait limit (`bash.worker_wait_max_ms`, 30 minutes by default), then reports it is still running; watch again to keep waiting. An explicit timeout never exceeds that worker limit";
 /**
  * Description of the bash_watch timeout parameter. Every caller sees the same
  * schema, so it has to be true for both roles.
  */
-export const WATCH_TIMEOUT_PARAM_DESCRIPTION = "Sync-only timeout in milliseconds. In a main session: default 30000, max `bash.watch_sync_max_ms` (120000 by default). In a delegated session: omit it to wait until the command finishes; a value you pass is used as given.";
+export const WATCH_TIMEOUT_PARAM_DESCRIPTION = "Sync-only timeout in milliseconds. In a main session: default 30000, max `bash.watch_sync_max_ms` (120000 by default). In a delegated session: omit it to wait up to the worker wait limit (`bash.worker_wait_max_ms`, 30 minutes by default), after which the watch reports the command is still running; a value you pass is clamped to that worker limit.";
 /**
- * Effective sync bash_watch deadline in milliseconds, or `undefined` for a
- * wait with no deadline, which lasts until the task exits, a pattern matches,
- * a new message arrives, or the call is aborted.
+ * Effective sync bash_watch deadline in milliseconds.
  *
  * A delegated worker cannot be woken once its turn ends, so it has nothing
- * useful to do while its command runs except wait. Any deadline only makes it
- * call bash_watch again, and every such call re-reads its whole context. It
- * therefore waits with no deadline by default, and a timeout it passes is
- * honoured as given rather than clamped to the configured cap. A primary keeps
- * the short default and the cap because it can do other work or end its turn
- * and be woken by the completion reminder.
+ * useful to do while its command runs except wait, and a short deadline only
+ * makes it call bash_watch again, re-reading its whole context each time. It
+ * therefore waits up to the worker wait limit (`workerWaitMaxMs`,
+ * `bash.worker_wait_max_ms`) by default: long enough that re-watching is
+ * rare, short enough that a stuck command cannot hold it forever. A timeout
+ * it passes is clamped to the worker limit, not to the primary cap. A
+ * primary keeps the short default and the cap because it can do other work
+ * or end its turn and be woken by the completion reminder.
  */
-export function resolveWatchTimeoutMs(requestedMs, role, capMs) {
+export function resolveWatchTimeoutMs(requestedMs, role, capMs, workerWaitMaxMs) {
     if (role === "worker")
-        return requestedMs;
+        return Math.min(requestedMs ?? workerWaitMaxMs, workerWaitMaxMs);
     return Math.min(requestedMs ?? DEFAULT_PRIMARY_WATCH_TIMEOUT_MS, capMs);
 }
 /**
@@ -101,7 +118,7 @@ export function abortableSleep(ms, signal) {
 export function formatWatchWaited(elapsedMs, limitMs, capMs) {
     let limit;
     if (limitMs === undefined)
-        limit = "no limit: waits until the command finishes";
+        limit = "no wait limit";
     else if (capMs !== undefined && limitMs >= capMs)
         limit = `limit ${limitMs}ms, the bash.watch_sync_max_ms cap`;
     else
@@ -109,23 +126,149 @@ export function formatWatchWaited(elapsedMs, limitMs, capMs) {
     return `Waited ${Math.round(elapsedMs)}ms (${limit})`;
 }
 /**
- * Appended to a bash_watch reply whose sync deadline passed without a match.
- * The deadline is a property of the watch, not of the command: a delegated
- * worker that read the bare "timeout reached" line as its own execution being
- * interrupted declared a failed result while its long-running command was
- * still going. Each role gets only the move that applies to it: a worker must
- * keep watching and not report, while a primary may end its turn because the
- * completion reminder wakes it. A worker only reaches this with a timeout it
- * passed itself, so it is told that leaving the timeout out waits until the
- * command finishes. `timeoutParam` is the host's spelling of the bash_watch
- * timeout argument, so the worker is told a name it can pass.
+ * Appended to a primary's bash_watch reply whose sync deadline passed without
+ * a match. The deadline is a property of the watch, not of the command, so the
+ * caller is told the command is still running and that the completion
+ * reminder wakes it. A worker gets {@link workerWatchStillRunning} instead.
  */
-export function watchTimeoutSteer(role, timeoutParam = "timeoutMs") {
-    if (role === "worker") {
-        return `The command is still running; this is not a failure. Watch again and don't report a result until it finishes; a bash_watch without ${timeoutParam} waits until the command finishes.`;
-    }
+export function watchTimeoutSteer() {
     return "The command is still running; this is not a failure. Watch again, do other work, or end your turn: the completion reminder wakes you.";
 }
+/** A duration in words: whole minutes as minutes, anything else in seconds. */
+export function formatWaitDuration(ms) {
+    const rounded = Math.max(0, Math.round(ms));
+    if (rounded === 60_000)
+        return "1 minute";
+    if (rounded > 0 && rounded % 60_000 === 0)
+        return `${rounded / 60_000} minutes`;
+    const seconds = (rounded / 1000).toFixed(1).replace(/\.0$/, "");
+    return `${seconds}s`;
+}
+/**
+ * The sentence naming a task's own kill deadline, from the `hard_kill` field
+ * and `started_at` of the engine's task status (`{ limit_ms, source }`), or how
+ * the task was killed when its hard kill fired (`status_reason`). It reports an
+ * absolute UTC deadline measured from command start and the approximate time
+ * remaining. Mirrors `kill_deadline_sentence` in the engine.
+ */
+export function taskKillDeadlineText(data, role, nowMs = Date.now()) {
+    if (data.status === "timed_out") {
+        const reason = typeof data.status_reason === "string" ? data.status_reason : "";
+        return reason === ""
+            ? "The task was killed by its time limit (exit 124)."
+            : `The task was ${reason}.`;
+    }
+    // A terminal task's deadline no longer matters; an unknown state (the
+    // bridge stayed busy) has none to report.
+    if (isTerminalTaskStatus(data.status) || typeof data.status !== "string")
+        return "";
+    if (data.status === "unknown")
+        return "";
+    // A remote task has no AFT hard-kill deadline (`hard_kill`); report its
+    // build-server status note instead (still queued, or when the runner will
+    // stop it). Mirrors `kill_deadline_text` in crates/aft/src/commands/bash_watch.rs.
+    if (typeof data.remote_phase_note === "string" && data.remote_phase_note !== "") {
+        const note = data.remote_phase_note;
+        return `${note.charAt(0).toUpperCase()}${note.slice(1)}.`;
+    }
+    const hardKill = data.hard_kill;
+    if (!hardKill || typeof hardKill.limit_ms !== "number") {
+        return "This task has no kill deadline.";
+    }
+    const startedAtMs = data.started_at;
+    if (typeof startedAtMs !== "number" || !Number.isSafeInteger(startedAtMs)) {
+        return "This task has no kill deadline.";
+    }
+    const limitMs = hardKill.limit_ms;
+    const limit = formatWaitDuration(limitMs);
+    const deadlineAt = startedAtMs + limitMs;
+    const when = `at ${formatKillDeadlineUtc(deadlineAt)}, when it has run ${limit}`;
+    let source;
+    if (hardKill.source === "timeout") {
+        source = "(the `timeout` you passed)";
+    }
+    else if (role === "worker") {
+        source =
+            "(its default background limit), but each wait you make on it moves that kill to at least the worker wait limit (`bash.worker_wait_max_ms`) after the wait, so it is not killed while you keep waiting; pass a `timeout` to set your own limit";
+    }
+    else {
+        source = "(its default background limit) unless you pass a longer `timeout`";
+    }
+    const remaining = deadlineAt <= nowMs
+        ? "; the kill deadline has passed"
+        : `; about ${formatApproximateRemaining(deadlineAt - nowMs)} remain`;
+    return `AFT kills this task ${when} ${source}${remaining}.`;
+}
+/**
+ * A wait should not hand back a still-running task just before its own kill
+ * deadline. Five seconds covers the slowest status poll and kill publication.
+ */
+export function taskKillDeadlineWithinHandoffMargin(data) {
+    if (typeof data.status !== "string" || isTerminalTaskStatus(data.status))
+        return false;
+    const hardKill = data.hard_kill;
+    const limitMs = hardKill?.limit_ms;
+    const elapsedMs = data.elapsed_ms;
+    return (typeof limitMs === "number" &&
+        Number.isSafeInteger(limitMs) &&
+        typeof elapsedMs === "number" &&
+        Number.isSafeInteger(elapsedMs) &&
+        limitMs - elapsedMs <= 5_000);
+}
+function formatKillDeadlineUtc(unixMs) {
+    const date = new Date(unixMs);
+    if (!Number.isFinite(date.getTime()))
+        throw new Error("invalid bash task start time");
+    const year = String(date.getUTCFullYear()).padStart(4, "0");
+    const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const day = String(date.getUTCDate()).padStart(2, "0");
+    const hour = String(date.getUTCHours()).padStart(2, "0");
+    const minute = String(date.getUTCMinutes()).padStart(2, "0");
+    const second = String(date.getUTCSeconds()).padStart(2, "0");
+    const millis = date.getUTCMilliseconds();
+    const fraction = millis === 0 ? "" : `.${String(millis).padStart(3, "0")}`;
+    return `${year}-${month}-${day} ${hour}:${minute}:${second}${fraction}Z`;
+}
+function formatApproximateRemaining(ms) {
+    if (ms >= 60_000) {
+        const minutes = Math.max(1, Math.floor((ms + 30_000) / 60_000));
+        return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+    }
+    return formatWaitDuration(ms);
+}
+function isTerminalTaskStatus(status) {
+    return (status === "completed" ||
+        status === "failed" ||
+        status === "killed" ||
+        status === "timed_out" ||
+        status === "fate_unknown");
+}
+/** Most lines of a still-running command's output shown to a worker. */
+const WORKER_OUTPUT_TAIL_LINES = 20;
+/** The last lines of `output`, so a worker can judge whether a command is stuck. */
+export function outputTail(output) {
+    const lines = (output ?? "").replace(/\s+$/, "").split("\n");
+    return lines.slice(-WORKER_OUTPUT_TAIL_LINES).join("\n");
+}
+/**
+ * Appended to a delegated worker's bash_watch reply whose deadline passed
+ * while the command still runs (by default the worker wait limit). The
+ * deadline is a property of the watch, not of the command: a worker that read
+ * a bare "timeout reached" line as its own execution failing declared a
+ * failed result while its command was still going. So it is told plainly that
+ * the command is still running, how long it has run, and its latest output,
+ * then given both moves by name: watch again to keep waiting, or kill a
+ * command that should have finished. `taskIdArg` and `timeoutParam` are the
+ * host's spellings of the bash_watch arguments.
+ */
+export function workerWatchStillRunning(options) {
+    const taskIdArg = options.taskIdArg ?? "taskId";
+    const timeoutParam = options.timeoutParam ?? "timeoutMs";
+    const ran = options.ranMs === undefined ? "" : ` It has run for ${formatWaitDuration(options.ranMs)}.`;
+    const tail = outputTail(options.output);
+    const output = tail === "" ? "No output yet." : `Recent output:\n${tail}`;
+    return `The command is still running after ${formatWaitDuration(options.waitedMs)} of watching; this is not a failure.${ran} Call bash_watch({ ${taskIdArg}: "${options.taskId}" }) again to keep waiting (without ${timeoutParam} a watch waits up to the worker wait limit, then reports it is still running), or bash_kill({ ${taskIdArg}: "${options.taskId}" }) if it should have finished by now. Don't report a result until it finishes.\n${output}`;
+}
 /**
  * How long a sync bash_watch with no deadline keeps retrying while every
  * status poll times out because the bridge is busy. Without this bound a wait
@@ -153,12 +296,12 @@ export function interruptedWatchTail(role, primaryTail) {
  * command now runs in the background. AFT's own reply already says the task
  * won't wake the worker; this names the plugin-owned bash_watch tool, which
  * AFT cannot assume a host has. The suggested call passes no timeout on
- * purpose: a worker's watch without one waits until the command finishes, so
- * any number would only make it wake and watch again. `taskIdArg` is the
- * host's spelling of the task id argument.
+ * purpose: a worker's watch without one waits up to the worker wait limit,
+ * the longest it may, so any number would only make it wake sooner and watch
+ * again. `taskIdArg` is the host's spelling of the task id argument.
  */
 export function workerBackgroundTaskNote(taskId, taskIdArg = "taskId") {
-    return `\n\nNOTE (subagent session): Continue with other work if you have it. If you don't, call bash_watch({ ${taskIdArg}: "${taskId}" }) to wait for completion before returning to the parent; without a timeout it waits until the command finishes. Subagents don't survive turn-end and won't be woken when the command finishes.`;
+    return `\n\nNOTE (subagent session): Continue with other work if you have it. If you don't, call bash_watch({ ${taskIdArg}: "${taskId}" }) to wait for completion before returning to the parent; without a timeout it waits up to ${WORKER_WAIT_LIMIT_PHRASE}, then reports it is still running; watch again to keep waiting, or call bash_kill({ ${taskIdArg}: "${taskId}" }) if it should have finished by now. Subagents don't survive turn-end and won't be woken when the command finishes.`;
 }
 /**
  * Line a bash_status snapshot of a still-running task ends with. A primary is
@@ -369,7 +512,7 @@ function nextCwdAfterCd(currentCwd, firstStage, afterCd) {
 }
 function isDirInsideProject(resolvedRoot, dir) {
     const rel = path.relative(resolvedRoot, path.resolve(dir));
-    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    return !relativePathEscapesRoot(rel);
 }
 function collectPathOperands(firstStage, startAfterCommand) {
     const operands = [];
@@ -380,6 +523,8 @@ function collectPathOperands(firstStage, startAfterCommand) {
     // the grep read as path-less ("in-project cwd") and nudged toward aft_search
     // for a target it could not see - the logs directory, in the field.
     let sawPattern = false;
+    let optionsEnded = false;
+    let optionValue;
     while (index < firstStage.length) {
         const tokenResult = readShellToken(firstStage, index);
         if (tokenResult === null)
@@ -393,23 +538,56 @@ function collectPathOperands(firstStage, startAfterCommand) {
         if (end <= index)
             break;
         index = skipSpaces(firstStage, end);
-        if (token.startsWith("-"))
+        // A descriptor before a redirection is shell syntax, not a search path.
+        if (/^\d+$/.test(token) && /[<>]/.test(firstStage[end] ?? ""))
+            break;
+        if (optionValue) {
+            if (optionValue === "pattern" || optionValue === "file")
+                sawPattern = true;
+            optionValue = undefined;
+            continue;
+        }
+        if (!optionsEnded && token === "--") {
+            optionsEnded = true;
             continue;
-        if (!sawPattern && !looksLikePathOperand(token)) {
+        }
+        if (!optionsEnded && token.startsWith("-")) {
+            if (token === "-e" || token === "--regexp")
+                optionValue = "pattern";
+            else if (token === "-f" || token === "--file")
+                optionValue = "file";
+            else if (/^(?:--regexp=|--file=|-e.+|-f.+)/.test(token))
+                sawPattern = true;
+            else if ([
+                "-A",
+                "-B",
+                "-C",
+                "-m",
+                "--after-context",
+                "--before-context",
+                "--context",
+                "--max-count",
+                "--include",
+                "--exclude",
+                "--exclude-dir",
+                "-g",
+                "--glob",
+                "-t",
+                "--type",
+                "-T",
+                "--type-not",
+            ].includes(token))
+                optionValue = "other";
+            continue;
+        }
+        if (!sawPattern) {
             sawPattern = true;
             continue;
         }
-        if (looksLikePathOperand(token) || isDynamicPathOperand(token))
-            operands.push(token);
+        operands.push(token);
     }
     return operands;
 }
-function looksLikePathOperand(token) {
-    return (token.includes("/") ||
-        token.startsWith("~") ||
-        token.startsWith("./") ||
-        token.startsWith("../"));
-}
 function isDynamicPathOperand(token) {
     return token.startsWith("~") || token.includes("$") || token.includes("`");
 }
@@ -430,7 +608,7 @@ function isPathInsideProject(resolvedRoot, baseCwd, operand) {
     // from the project root after a `cd`), absolute/`~` operands against the FS.
     const resolved = resolvePathOperand(baseCwd, operand);
     const rel = path.relative(resolvedRoot, resolved);
-    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    return !relativePathEscapesRoot(rel);
 }
 function shouldSuppressResolvedPath(resolved) {
     try {