pi-claude-supervisor 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented here.
 
+## [0.8.0](https://github.com/btnalit/pi-claude-supervisor/compare/v0.7.3...v0.8.0) (2026-09-19)
+
+
+### Features
+
+* **recover:** extend an expired task's budget from now, and discard records nobody will recover ([0bbf07f](https://github.com/btnalit/pi-claude-supervisor/commit/0bbf07f8a44eb5f9cfb3542a8b01115aa2c3703a))
+* **supervisor:** turn the wall-clock deadline into a warned, graceful close-out ([4b5f92a](https://github.com/btnalit/pi-claude-supervisor/commit/4b5f92a61c99d9f1448d3c994975826897326ced))
+
+
+### Bug Fixes
+
+* **recover:** point an adopted task's discard at re-adoption, guard the owed re-ask ([0fef7d8](https://github.com/btnalit/pi-claude-supervisor/commit/0fef7d850b3934543feb664b954f5d4cb92c63e0))
+* **supervisor:** address the review of the deadline close-out ([721b0b8](https://github.com/btnalit/pi-claude-supervisor/commit/721b0b8d2c62f81811ad67bf42c396a1c0550903))
+
+## [0.7.3](https://github.com/btnalit/pi-claude-supervisor/compare/v0.7.2...v0.7.3) (2026-09-17)
+
+
+### Bug Fixes
+
+* **policy:** a name bound to literal text is not an unseen argument ([b93bbf6](https://github.com/btnalit/pi-claude-supervisor/commit/b93bbf6ae019fb7137588f113c0e1113ee942be7))
+* **policy:** a tilde expands only at the start of a word ([9671b23](https://github.com/btnalit/pi-claude-supervisor/commit/9671b23cd6f112f28decc2e906c029c11f5f7d1c))
+* **tmux:** a subagent hand-back is Claude's own prompt, not a human's ([90d40ba](https://github.com/btnalit/pi-claude-supervisor/commit/90d40baf357c5390f1699502235459e2d4230d55))
+* **tmux:** remove a dead Worker's tmux socket and sweep leftovers at load ([db83d40](https://github.com/btnalit/pi-claude-supervisor/commit/db83d4016dc210739d386d038df220cd7c1c4479))
+
 ## [0.7.2](https://github.com/btnalit/pi-claude-supervisor/compare/v0.7.1...v0.7.2) (2026-09-17)
 
 

package/README.cn.md

@@ -194,8 +194,16 @@ stream-json` 的方式运行 Claude,完全没有终端界面;一旦设置
   `PI_CLAUDE_SUPERVISOR_TRUSTED_CLAUDE` 显式固定)。
 - Linux 上,cgroup v2 边界会清理每一个后代进程,包括 `setsid()` 后代;
   `required` 模式会 fail closed,而不是回退到其他清理方式。
-- 默认 4 小时总时限、20 分钟无输出 watchdog 会停止 Worker;嵌入方调用可以修改或
-  关闭任一项(`deadlineMs`、`noOutputTimeoutMs`)。
+- 每个任务有一个总时限(默认 4 小时,可用 `--deadline 8h` 按任务指定或用
+  `DEADLINE_MS` 全局设置)。到期不会直接杀掉工作:到期前
+  `DEADLINE_WARNING_MS`(默认 15 分钟)会提醒 Decision Worker 引导 Worker 收尾;
+  到期后进入 `DEADLINE_GRACE_MS`(默认 30 分钟)的收尾窗口,空闲的 Worker 会被直接
+  验收和 review 而不是被停止,`wait` 决策不再生效,修复轮会告诉 Worker 还剩多少
+  时间。只有收尾窗口也耗尽,Worker 才会被硬停(`worker_watchdog_timeout`);对
+  接管的交互式会话来说这个硬停只是 release:Claude 继续运行,但不再受监督。
+  收尾窗口只属于自动模式任务;手动任务仍在到期时停止,`DEADLINE_GRACE_MS=0`
+  让自动任务也恢复这一行为。20 分钟无输出 watchdog(`NO_OUTPUT_TIMEOUT_MS`)
+  随时会停止沉默的 Worker。
 - 验收命令、证据收集和 Reviewer 共用一个 abort signal,因此 stop 或 shutdown
   不必等待完整的命令或模型超时。
 - 每个任务只持有一个 cwd 租约;并发任务需要各自独立的 worktree。
@@ -267,6 +275,10 @@ stream-json` 的方式运行 Claude,完全没有终端界面;一旦设置
 | `EVIDENCE_MAX_BYTES` | `1048576`(1 MiB) | 每个任务收集的最大仓库证据字节数 |
 | `EVIDENCE_MAX_UNTRACKED_FILES` | `512` | 每个任务作为证据收集的最大未跟踪文件数 |
 | `REVIEW_TIMEOUT_MS` | `600000`(10 分钟) | 每轮独立 Reviewer 的总预算,含一次针对 provider 错误的重试 |
+| `DEADLINE_MS` | `4h` | 每个任务的累计总时限(`8h`、`90m`、`2h30m` 或毫秒;5 分钟到 7 天);`0`(或 `0m`)关闭;`--deadline` 可按任务覆盖 |
+| `DEADLINE_GRACE_MS` | `30m` | 自动任务到期后的收尾窗口:空闲的 Worker 会被验收而不是停止;`0` 恢复到期立即停止 |
+| `DEADLINE_WARNING_MS` | `15m` | 到期前多久提醒并重新询问 Decision Worker;`0` 关闭提醒 |
+| `NO_OUTPUT_TIMEOUT_MS` | `20m` | Worker 多久没有输出就停止;`0` 关闭该检查 |
 | `EVENT_LOG_MAX_BYTES` | `67108864`(64 MiB) | `events.jsonl` 达到该大小后滚动,保留 5 份滚动文件 |
 
 ## 恢复、租约与状态
@@ -280,6 +292,13 @@ Worker,它不会静默恢复或重复执行任务。只有在租约证明旧 Wor
 的 `TRANSPORT`/`TMUX_MODE` 配置来判断,因此在启动任务和恢复任务之间请不要
 改变这两个配置。
 
+因总时限到期而停止的任务会以 `deadline=expired … ago` 列出。普通 `recover`
+会拒绝它;`recover --takeover --extend <duration> <task-id>` 从现在起再给这么
+多预算(恢复后的 Supervisor 会把新时限持久化),`--extend 0` 则立即进入收尾:
+新 Worker 的第一个 watchdog tick 就会对仓库现状做验收和 review,修复轮会告诉
+它还剩多少时间。确定不再恢复的记录用 `/supervise discard <task-id>` 丢弃
+(会话文件保留到保留期清理为止)。
+
 每个任务在 `CWD_LEASE_DIR` 下持有一个 cwd 租约;并发任务需要各自独立的
 worktree。无法读取的租约记录(损坏的 JSON、异常的结构)会被隔离到 quarantine
 目录,而不会阻塞其他查找;`/supervise sessions` 会列出当前被隔离的记录,方便

package/README.md

@@ -69,8 +69,11 @@ Then, inside any Pi session:
 ```text
 /supervise start implement the requested change
 /supervise adopt-tmux my-tmux-session implement the requested change
+/supervise start --deadline 8h a large multi-worktree change
 ```
 
+Both accept `--spec <file>` and `--deadline <duration>` (`8h`, `90m`, `0` for
+no deadline) ahead of the task text.
 Watch a task with `/supervise status <task-id>` or `/supervise sessions`; for
 a tmux transport, attach directly with the `tmux -S <socket> attach -t
 <session>` command each of these prints. `/supervise stop <task-id>` closes
@@ -232,9 +235,20 @@ Supervisor being able to see it, or when you don't need to attach.
 - On Linux, a cgroup v2 boundary cleans up every descendant, including
   `setsid()` descendants; `required` mode fails closed instead of falling
   back.
-- A 4-hour wall-clock deadline and a 20-minute no-output watchdog stop a
-  worker by default; embedding callers can change or disable either
-  (`deadlineMs`, `noOutputTimeoutMs`).
+- A wall-clock deadline (4 hours by default, `--deadline 8h` per task or
+  `DEADLINE_MS`) bounds a task. Reaching it does not kill the work: the
+  Decision Worker is warned ahead of time (`DEADLINE_WARNING_MS`, 15 min) and
+  told to steer the Worker to a wrap-up, and once the deadline passes a
+  close-out window opens (`DEADLINE_GRACE_MS`, 30 min) in which an idle Worker
+  is verified and reviewed instead of stopped, a `wait` decision is no longer
+  honored, and a repair round tells the Worker how long it has left. Only when
+  the close-out window has also elapsed is the Worker stopped outright
+  (`worker_watchdog_timeout`), and on an adopted interactive session that stop
+  is a release: Claude keeps running, unsupervised. The close-out belongs to
+  automatic tasks; a manual task is stopped at the deadline as before, and
+  `DEADLINE_GRACE_MS=0` restores that for automatic ones too. A 20-minute
+  no-output watchdog (`NO_OUTPUT_TIMEOUT_MS`) still stops a silent Worker at
+  any time.
 - Acceptance checks, evidence collection, and the Reviewer share an abort
   signal, so a stop or shutdown does not wait for a full command or model
   timeout.
@@ -309,6 +323,10 @@ Environment variables (or `~/.config/pi-claude-supervisor/env`), all prefixed
 | `EVIDENCE_MAX_BYTES` | `1048576` (1 MiB) | Maximum repository evidence bytes collected per task |
 | `EVIDENCE_MAX_UNTRACKED_FILES` | `512` | Maximum untracked files collected as evidence per task |
 | `REVIEW_TIMEOUT_MS` | `600000` (10 min) | Total independent Reviewer budget per round, including one retry on a provider error |
+| `DEADLINE_MS` | `4h` | Cumulative wall-clock budget per task (`8h`, `90m`, `2h30m` or ms; 5m–7d); `0` (or `0m`) disables it; `--deadline` overrides it per task |
+| `DEADLINE_GRACE_MS` | `30m` | Close-out window after the deadline for automatic tasks: an idle Worker is verified instead of stopped; `0` restores the immediate stop |
+| `DEADLINE_WARNING_MS` | `15m` | How long before the deadline the Decision Worker is warned and re-asked; `0` disables the warning |
+| `NO_OUTPUT_TIMEOUT_MS` | `20m` | Stop a Worker that has produced no output for this long; `0` disables the check |
 | `EVENT_LOG_MAX_BYTES` | `67108864` (64 MiB) | Rotates `events.jsonl` at this size; 5 rotated files are kept |
 
 ## Recovery, leases and state
@@ -325,6 +343,15 @@ interactive — it derives that from the current `TRANSPORT`/`TMUX_MODE`
 configuration at recovery time, so do not change either between starting a
 task and recovering it.
 
+A task that stopped at its wall-clock deadline is listed with `deadline=expired
+… ago`. Plain `recover` refuses it; `recover --takeover --extend <duration>
+<task-id>` grants that much budget from now (the recovered Supervisor persists
+the new deadline), and `--extend 0` opens the close-out at once, so the fresh
+Worker's first watchdog tick verifies and reviews the repository as it stands
+and any repair round tells it how long it has. A record nobody will recover is
+dropped with `/supervise discard <task-id>` (its session file is kept until
+retention pruning).
+
 Every task holds one cwd lease under `CWD_LEASE_DIR`; concurrent tasks need
 separate worktrees. A lease record that cannot be read (corrupt JSON,
 unexpected shape) is quarantined instead of blocking other lookups, and

package/docs/architecture.md

@@ -401,6 +401,36 @@ not. JSONL sends are rejected while a request is active, and a valid terminal
 result moves the session to `waiting`; only then may the next turn be sent. A paused
 Worker does not consume its no-output budget; resume establishes a fresh no-output
 baseline while the cumulative wall-clock deadline remains active.
+
+The wall-clock deadline is a budget, not a kill switch. The watchdog drives it
+through three phases, each recorded once per task: `worker_deadline_approaching`
+(`deadlineWarningMs` before the deadline) refreshes the Decision Worker's clock
+(`deadline.remainingMs` in its context and `deadlineRemainingMinutes` in every
+event prompt) and, if the Worker idles under a `wait`, replays the last completed
+turn so the Decision Worker can steer the Worker to integrate, commit and stop;
+`worker_deadline_reached` opens the close-out window (`deadlineGraceMs`), during
+which an idle automatic Worker is verified at once (`deadline_close_out`), a
+`wait` decision on an idle Worker is applied as verify (`decision_overridden`), a
+Worker mid-turn keeps its turn and its completed turn is decided with
+`closeOut: true`, and a repair round tells the Worker how much of the window
+remains; `worker_watchdog_timeout` (`worker deadline exceeded`) stops the Worker
+only once the close-out window has also elapsed. The deadline never verifies
+underneath a decision that is still in flight for the last turn, and a repeated
+`wait` for the same turn re-arms the wait timer rather than being deduplicated.
+A zero grace window restores the immediate stop at the deadline, and a manual
+task (no Decision Worker to drive a close-out) always behaves that way; a repair
+round is refused once less than a minute of the window is left, so the findings
+stay on a blocked candidate instead of being cut short by the stop. For an adopted
+interactive session the outright stop is a release (the adapter never kills a
+session it does not own), so the Claude process keeps running unsupervised; the
+close-out exists so that a task which merely ran long still ends with a verified
+candidate instead of a silent hand-back. A record left behind by the outright
+stop (`recoverable_failure`, so `active/interrupted`) is not a dead end either:
+`recover --extend <duration>` re-persists a deadline measured from now
+(`extendedDeadlineMs`), `--extend 0` recovers straight into the close-out, and
+`discard` closes a record nobody will recover — refused while the task's cwd
+lease exists, since a live owner means the task is running in another Pi and a
+dead owner's lease is reclaimed only through `recover --takeover`'s cleanup proof.
 Input writes are serialized with stop and are acknowledged through the stream
 write callback before their idempotency key is consumed. Writes have a bounded
 timeout, and `stop()` preempts a queued lifecycle operation by initiating adapter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-claude-supervisor",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "A policy-gated Pi supervisor for observing and verifying Claude Code workers.",
   "license": "MIT",
   "publishConfig": {
@@ -67,8 +67,8 @@
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.85.1",
     "@types/node": "22.20.1",
-    "typebox": "1.3.30",
+    "typebox": "1.3.32",
     "typescript": "7.0.2",
-    "yaml": "2.9.0"
+    "yaml": "2.9.1"
   }
 }

package/src/config.ts

@@ -39,6 +39,10 @@ const allowed = new Set([
   "PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_UNTRACKED_FILES",
   "PI_CLAUDE_SUPERVISOR_REVIEW_TIMEOUT_MS",
   "PI_CLAUDE_SUPERVISOR_EVENT_LOG_MAX_BYTES",
+  "PI_CLAUDE_SUPERVISOR_DEADLINE_MS",
+  "PI_CLAUDE_SUPERVISOR_DEADLINE_GRACE_MS",
+  "PI_CLAUDE_SUPERVISOR_DEADLINE_WARNING_MS",
+  "PI_CLAUDE_SUPERVISOR_NO_OUTPUT_TIMEOUT_MS",
 ]);
 
 export interface AutonomyDefaults {
@@ -109,6 +113,71 @@ export function evidenceMaxUntrackedFiles(env: NodeJS.ProcessEnv = process.env):
   return readBoundedInteger(env.PI_CLAUDE_SUPERVISOR_EVIDENCE_MAX_UNTRACKED_FILES, 512, 16, 10_000);
 }
 
+export const DEFAULT_DEADLINE_MS = 4 * 60 * 60_000;
+export const DEFAULT_DEADLINE_GRACE_MS = 30 * 60_000;
+export const DEFAULT_DEADLINE_WARNING_MS = 15 * 60_000;
+export const DEFAULT_NO_OUTPUT_TIMEOUT_MS = 20 * 60_000;
+
+/**
+ * Cumulative wall-clock budget for a task's Worker turns (5 minutes to 7 days);
+ * "0" disables the deadline. A duration suffix (`8h`, `90m`, `2h30m`) is
+ * accepted as well as plain milliseconds.
+ */
+export function deadlineMs(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DEADLINE_MS, DEFAULT_DEADLINE_MS, 5 * 60_000, 7 * 24 * 60 * 60_000);
+}
+
+/**
+ * Close-out window after the deadline: the Worker is asked to finish and the
+ * candidate is verified instead of the Worker being stopped outright. "0"
+ * restores the immediate stop at the deadline. Up to 24 hours.
+ */
+export function deadlineGraceMs(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DEADLINE_GRACE_MS, DEFAULT_DEADLINE_GRACE_MS, 60_000, 24 * 60 * 60_000);
+}
+
+/** How long before the deadline the Decision Worker is warned (up to 24 hours); "0" disables the warning. */
+export function deadlineWarningMs(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_DEADLINE_WARNING_MS, DEFAULT_DEADLINE_WARNING_MS, 60_000, 24 * 60 * 60_000);
+}
+
+/** Stop a Worker that has produced no output for this long (1 minute to 24 hours); "0" disables the check. */
+export function noOutputTimeoutMs(env: NodeJS.ProcessEnv = process.env): number {
+  return readBoundedDurationWithZeroOptOut(env.PI_CLAUDE_SUPERVISOR_NO_OUTPUT_TIMEOUT_MS, DEFAULT_NO_OUTPUT_TIMEOUT_MS, 60_000, 24 * 60 * 60_000);
+}
+
+const DURATION_UNITS_MS: Record<string, number> = { ms: 1, s: 1_000, m: 60_000, h: 60 * 60_000, d: 24 * 60 * 60_000 };
+
+/**
+ * Parse a duration such as `8h`, `90m`, `2h30m`, `45s` or plain milliseconds
+ * into milliseconds; undefined for anything else (including negative values).
+ */
+export function parseDurationMs(value: string | undefined): number | undefined {
+  const trimmed = value?.trim().toLowerCase();
+  if (!trimmed) return undefined;
+  if (/^\d+$/u.test(trimmed)) {
+    const parsed = Number(trimmed);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+  }
+  if (!/^(?:\d+(?:\.\d+)?(?:ms|s|m|h|d))+$/u.test(trimmed)) return undefined;
+  let total = 0;
+  for (const match of trimmed.matchAll(/(\d+(?:\.\d+)?)(ms|s|m|h|d)/gu)) {
+    total += Number(match[1]) * DURATION_UNITS_MS[match[2]];
+  }
+  return Number.isSafeInteger(total) ? total : undefined;
+}
+
+/** Format milliseconds as a compact duration (`2h13m`, `45s`, `0s`) for status lines and notices. */
+export function formatDurationMs(ms: number): string {
+  const total = Math.max(0, Math.round(ms / 1_000));
+  const hours = Math.floor(total / 3_600);
+  const minutes = Math.floor((total % 3_600) / 60);
+  const seconds = total % 60;
+  if (hours > 0) return minutes > 0 ? `${hours}h${minutes}m` : `${hours}h`;
+  if (minutes > 0) return seconds > 0 && total < 600 ? `${minutes}m${seconds}s` : `${minutes}m`;
+  return `${seconds}s`;
+}
+
 export function loadSupervisorEnvironment(): string | undefined {
   const path = process.env.PI_CLAUDE_SUPERVISOR_ENV_FILE ?? join(homedir(), ".config", "pi-claude-supervisor", "env");
   if (!existsSync(path)) return undefined;
@@ -148,6 +217,15 @@ function readBoundedIntegerWithZeroOptOut(value: string | undefined, fallback: n
   return readBoundedInteger(value, fallback, minimum, maximum);
 }
 
+/** Like readBoundedIntegerWithZeroOptOut, but also accepts a duration suffix (`8h`, `90m`); out-of-range values keep the fallback. */
+function readBoundedDurationWithZeroOptOut(value: string | undefined, fallback: number, minimum: number, maximum: number): number {
+  if (value === undefined) return fallback;
+  const parsed = parseDurationMs(value);
+  // "0", "0m", "0h": any zero duration is the opt-out, not a below-minimum typo.
+  if (parsed === 0) return 0;
+  return parsed !== undefined && parsed >= minimum && parsed <= maximum ? parsed : fallback;
+}
+
 function readTrimmedString(value: string | undefined): string | undefined {
   const trimmed = value?.trim();
   return trimmed ? trimmed : undefined;

package/src/cwd-lease.ts

@@ -651,6 +651,11 @@ async function cgroupHasProcesses(path: string): Promise<boolean> {
   }
 }
 
+/** True while the Pi process that acquired the lease is still alive (pid and start time both match). */
+export async function leaseOwnerLive(lease: CwdLeaseRecord): Promise<boolean> {
+  return processIdentityLive(lease.ownerPid, lease.ownerStartTime);
+}
+
 async function canTakeoverLease(lease: CwdLeaseRecord): Promise<TakeoverProof | undefined> {
   // The old supervisor owner must be gone. A dead owner is not enough when
   // the detached Worker itself is still alive. Compare start time as well as

package/src/decision-worker.ts

@@ -26,6 +26,21 @@ export interface DecisionContext {
   maxTurns: number;
   repairRound?: number;
   spec?: TaskSpec;
+  /** Wall-clock budget of the task; absent when no deadline is configured. */
+  deadline?: DecisionDeadlineContext;
+}
+
+export interface DecisionDeadlineContext {
+  /** Cumulative wall-clock budget for the task's Worker turns. */
+  totalMs: number;
+  /** Close-out window after the deadline before the Supervisor stops the Worker; 0 means the stop is immediate. */
+  graceMs: number;
+  /** Time left before the deadline; 0 once it has passed. */
+  remainingMs: number;
+  /** True once the deadline has passed and the task is in its close-out window. */
+  closeOut: boolean;
+  /** During close-out: time left before the Supervisor stops the Worker outright. */
+  closeOutRemainingMs?: number;
 }
 
 export interface DecisionWorkerLike {
@@ -277,7 +292,7 @@ Task id: ${redactText(context.taskId)}
 Working directory: ${redactText(context.cwd)}
 Maximum automatic turns: ${context.maxTurns}
 Current repair round: ${context.repairRound ?? 0}
-Task specification: ${boundedJson(context.spec ?? { goal: context.task })}
+${deadlineInstructions(context.deadline)}Task specification: ${boundedJson(context.spec ?? { goal: context.task })}
 
 Return exactly one JSON object and no markdown:
 {"action":"continue|redirect|answer|allow_permission|deny_permission|verify|retry|stop|park|wait|noop",...}
@@ -303,7 +318,39 @@ wait for a human to be online. For an exited event choose verify, park or stop;
 verify. Choose wait when the Worker's result says it is waiting for its own background agents,
 tasks or monitors: their completion re-invokes the Worker automatically, a message would only
 interrupt it, and the Supervisor asks you again if the Worker has not resumed within the wait
-timeout. A completed turn or a permission request always requires a concrete action.`;
+timeout. A completed turn or a permission request always requires a concrete action.${deadlinePolicy(context.deadline)}`;
+}
+
+function deadlineInstructions(deadline: DecisionDeadlineContext | undefined): string {
+  if (!deadline) return "";
+  const closeOut = deadline.graceMs > 0
+    ? `then a ${formatMinutes(deadline.graceMs)} close-out window before the Supervisor stops the Worker`
+    : "with no close-out window: the Supervisor stops the Worker at the deadline";
+  return `Wall-clock budget: ${formatMinutes(deadline.totalMs)} for the whole task, ${closeOut}.\n`;
+}
+
+function deadlinePolicy(deadline: DecisionDeadlineContext | undefined): string {
+  if (!deadline) return "";
+  const wrapUp = `
+Time budget: CURRENT CONTEXT reports deadlineRemainingMinutes. While it is small (roughly the
+length of one build-and-test cycle), stop waiting on long background work: use continue or
+redirect to tell Claude Code to integrate what is finished, run the required checks, commit,
+and stop, so the candidate can be verified before the deadline.`;
+  if (deadline.graceMs <= 0) {
+    return `${wrapUp} There is no close-out window: a Worker still running at the deadline is
+stopped outright, so choose verify as soon as the result is committed rather than waiting.`;
+  }
+  return `${wrapUp} Once closeOut is true the
+deadline has passed and only closeOutRemainingMinutes are left before the Worker is stopped:
+choose verify as soon as the Worker is idle, or one concise continue/redirect that tells it to
+commit what is complete and stop; wait is no longer available during close-out and an idle
+Worker is verified instead.`;
+}
+
+function formatMinutes(ms: number): string {
+  const minutes = Math.round(ms / 60_000);
+  if (minutes >= 120 && minutes % 60 === 0) return `${minutes / 60} hours`;
+  return `${minutes} minutes`;
 }
 
 /**
@@ -318,7 +365,19 @@ async function askDecision(
   timeoutMs: number,
   options: { instructionsPrefix?: string; onUsage?: (usage: PiUsageSample) => void } = {},
 ): Promise<string> {
-  const currentContext = { state: context.state, turn: context.turn, maxTurns: context.maxTurns, repairRound: context.repairRound ?? 0 };
+  const currentContext = {
+    state: context.state,
+    turn: context.turn,
+    maxTurns: context.maxTurns,
+    repairRound: context.repairRound ?? 0,
+    ...(context.deadline ? {
+      deadlineRemainingMinutes: Math.round(context.deadline.remainingMs / 60_000),
+      closeOut: context.deadline.closeOut,
+      ...(context.deadline.closeOut && context.deadline.closeOutRemainingMs !== undefined
+        ? { closeOutRemainingMinutes: Math.round(context.deadline.closeOutRemainingMs / 60_000) }
+        : {}),
+    } : {}),
+  };
   const prompt = `${options.instructionsPrefix ?? ""}UNTRUSTED SUPERVISOR EVENT:\n${boundedEventJson(event)}\n\nCURRENT CONTEXT:\n${boundedJson(currentContext)}\n\nChoose one action now.`;
   return promptForText(session, prompt, timeoutMs, "Decision Worker request", MAX_DECISION_RESPONSE_BYTES, { role: "decision", onUsage: options.onUsage });
 }

package/src/index.ts

@@ -8,13 +8,13 @@ import { EventLog } from "./events.ts";
 import { redactSensitive } from "./redaction.ts";
 import { ProcessWorkerAdapter } from "./worker/process-adapter.ts";
 import { automaticWorkerEnvironment } from "./worker/environment.ts";
-import { TmuxWorkerAdapter, attachCommand } from "./worker/tmux-adapter.ts";
-import { Supervisor, type DecisionSessionClosedInfo, type HumanInterventionNotice, type SupervisorProgress, type SupervisorTokenUsage } from "./supervisor.ts";
+import { TmuxWorkerAdapter, attachCommand, sweepDeadTmuxSockets } from "./worker/tmux-adapter.ts";
+import { Supervisor, extendedDeadlineMs, type DecisionSessionClosedInfo, type HumanInterventionNotice, type SupervisorProgress, type SupervisorTokenUsage } from "./supervisor.ts";
 import { evaluateCommand } from "./policy.ts";
 import { HumanWebhookNotifier } from "./notifications.ts";
-import { autoInstallHooks, autonomyDefaults, closeWorkerOnCompletion, decisionCompactionTokens, decisionModel, decisionSessionRetentionDays, eventLogMaxBytes, loadSupervisorEnvironment, progressHeartbeatMs, reviewTimeoutMs, reviewerModel, tmuxMode, workerAutocompactTokens, workerMcpConfigPath, workerModel } from "./config.ts";
+import { autoInstallHooks, autonomyDefaults, closeWorkerOnCompletion, deadlineGraceMs, deadlineMs, deadlineWarningMs, decisionCompactionTokens, decisionModel, decisionSessionRetentionDays, eventLogMaxBytes, formatDurationMs, loadSupervisorEnvironment, noOutputTimeoutMs, parseDurationMs, progressHeartbeatMs, reviewTimeoutMs, reviewerModel, tmuxMode, workerAutocompactTokens, workerMcpConfigPath, workerModel } from "./config.ts";
 import { DecisionSessionStore, type DecisionSessionRecord } from "./decision-session-store.ts";
-import { CwdLeaseStore, type CwdLeaseHandle, pathsOverlap, workerIdentity } from "./cwd-lease.ts";
+import { CwdLeaseStore, type CwdLeaseHandle, leaseOwnerLive, pathsOverlap, workerIdentity } from "./cwd-lease.ts";
 import { normalizeTaskSpec } from "./acceptance.ts";
 import { PiReadOnlyReviewer } from "./reviewer.ts";
 import { resolvePiModel } from "./pi-model.ts";
@@ -128,6 +128,9 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
   // with /supervise uninstall-hooks; the relay is a ~1 ms no-op when no
   // Supervisor is listening, so leaving it installed costs nothing.
   let hookInstallNotice: string | undefined;
+  // A Worker killed with its cgroup leaves its tmux socket behind; sweep the
+  // ones no server answers on so the temp directory does not fill with them.
+  if (transport === "tmux") sweepDeadTmuxSockets();
   if (hookServer) {
     hookServerReady = (async () => {
       await writeRelayScript(relayPath);
@@ -366,12 +369,9 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
         const [operation = "status", ...rest] = tokens;
         let message = "";
         if (operation === "start" || operation === "adopt-tmux") {
-          let specPath: string | undefined;
-          if (rest[0] === "--spec") specPath = rest.splice(0, 2)[1];
-          else {
-            const specIndex = rest.findIndex((value) => value.startsWith("--spec="));
-            if (specIndex >= 0) specPath = rest.splice(specIndex, 1)[0]?.slice("--spec=".length);
-          }
+          const specPath = takeOption(rest, "--spec");
+          const deadlineOption = takeOption(rest, "--deadline");
+          const taskDeadlineMs = deadlineOption === undefined ? deadlineMs() : parseTaskDeadline(deadlineOption);
           const tmuxSession = operation === "adopt-tmux" ? rest.shift() : undefined;
           const task = rest.join(" ").trim();
           const fileSpec = specPath ? await readTaskSpecFile(specPath, ctx.cwd) : undefined;
@@ -384,7 +384,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           // own events through hooks exactly like an owned one.
           const taskAutomation = (operation !== "adopt-tmux" || tmuxMode() === "interactive") && automation && spec.autonomy.unattended;
           const interactive = taskAutomation && adapter.capabilities().transport === "tmux" && tmuxMode() === "interactive";
-          if (!goal) throw new Error(operation === "adopt-tmux" ? "Usage: /supervise adopt-tmux [--spec <file>] <tmux-session> <task>" : "Usage: /supervise start [--spec <file>] <task>");
+          if (!goal) throw new Error(operation === "adopt-tmux" ? "Usage: /supervise adopt-tmux [--spec <file>] [--deadline <duration>] <tmux-session> <task>" : "Usage: /supervise start [--spec <file>] [--deadline <duration>] <task>");
           if (operation === "adopt-tmux" && adapter.capabilities().transport !== "tmux") throw new Error("/supervise adopt-tmux requires PI_CLAUDE_SUPERVISOR_TRANSPORT=tmux");
           if (operation === "adopt-tmux" && interactive && !await userHooksInstalled(claudeUserSettingsPath())) {
             await hookServerReady?.catch(() => {});
@@ -455,6 +455,10 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                 approval,
                 automation: taskAutomation,
                 interactive,
+                deadlineMs: taskDeadlineMs,
+                deadlineGraceMs: deadlineGraceMs(),
+                deadlineWarningMs: deadlineWarningMs(),
+                noOutputTimeoutMs: noOutputTimeoutMs(),
                 hookSource: interactive ? hookServer : undefined,
                 hookSettingsPath,
                 keepWorkerOnCompletion: interactive ? !closeWorkerOnCompletion() : undefined,
@@ -640,9 +644,13 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
             pendingCwds.delete(cwdKey);
           }
         } else if (operation === "recover") {
+          const usage = "Usage: /supervise recover [--takeover] [--extend <duration>] <task-id>";
+          const extendOption = takeOption(rest, "--extend", ["--takeover"]);
           const takeover = rest.includes("--takeover");
           const taskId = rest.find((value) => value !== "--takeover");
-          if (!taskId || rest.some((value) => value !== "--takeover" && value !== taskId)) throw new Error("Usage: /supervise recover [--takeover] <task-id>");
+          if (!taskId || rest.some((value) => value !== "--takeover" && value !== taskId)) throw new Error(usage);
+          const extendMs = extendOption === undefined ? undefined : parseDurationMs(extendOption);
+          if (extendOption !== undefined && extendMs === undefined) throw new Error(`--extend expects a duration such as 30m, 2h or 0 (close out now): ${extendOption}`);
           if (shuttingDown) throw new Error("Pi session is shutting down");
           if (sessions.has(taskId)) throw new Error(`Task session is already loaded: ${taskId}`);
           const record = await decisionStore.load(taskId);
@@ -651,7 +659,17 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           if (staleRecovery && !takeover) throw new Error(`Decision Worker recovery is stale (${record.recoveryState}); retry with --takeover only after verifying the old Worker is gone: ${taskId}`);
           if (!await decisionStore.sessionFileExists(taskId)) throw new Error(`Decision Worker session file is missing or unsafe: ${taskId}`);
           if (record.maxTurns > 0 && record.turn >= record.maxTurns) throw new Error(`Cannot recover task after its turn budget was exhausted: ${taskId}`);
-          if (record.deadlineMs > 0 && Date.now() - Date.parse(record.startedAt) >= record.deadlineMs) throw new Error(`Cannot recover task after its wall-clock deadline: ${taskId}`);
+          if (extendMs !== undefined && record.deadlineMs <= 0) throw new Error(`Task has no wall-clock deadline to extend: ${taskId}`);
+          const elapsedMs = Math.max(0, Date.now() - Date.parse(record.startedAt));
+          // A task past its budget is not lost: `--extend` grants a fresh budget
+          // from now (0 opens the close-out at once, verifying the repository as
+          // it stands), which the recovered Supervisor persists as the deadline.
+          const recoveryDeadlineMs = extendMs === undefined ? record.deadlineMs : extendedDeadlineMs(record.deadlineMs, elapsedMs, extendMs);
+          // With --extend the new deadline is measured from now by construction
+          // (`--extend 0` deliberately lands on it, so the close-out opens at once).
+          if (extendMs === undefined && recoveryDeadlineMs > 0 && elapsedMs >= recoveryDeadlineMs) {
+            throw new Error(`Cannot recover task after its wall-clock deadline (${formatDurationMs(elapsedMs - recoveryDeadlineMs)} ago); pass --extend <duration> to grant a close-out budget from now, or /supervise discard ${taskId} to drop the record`);
+          }
           const cwdKey = await canonicalCwd(record.cwd);
           await releaseSettledReservations();
           if (shuttingDown) throw new Error("Pi session is shutting down");
@@ -783,7 +801,9 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
                   : undefined,
                 ...(automaticRecovery && record.resolvedExecutable ? { expectedClaudeExecutable: record.resolvedExecutable } : {}),
                 maxTurns: record.maxTurns,
-                deadlineMs: record.deadlineMs,
+                deadlineMs: recoveryDeadlineMs,
+                deadlineGraceMs: deadlineGraceMs(),
+                deadlineWarningMs: deadlineWarningMs(),
                 noOutputTimeoutMs: record.noOutputTimeoutMs,
                 startedAt: record.startedAt,
                 baseCommit: record.baseCommit,
@@ -903,6 +923,33 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
             pendingStartSessions.delete(session);
             pendingCwds.delete(cwdKey);
           }
+        } else if (operation === "discard") {
+          const [taskId, ...extra] = rest;
+          if (!taskId || extra.length > 0) throw new Error("Usage: /supervise discard <task-id>");
+          if (sessions.has(taskId)) throw new Error(`Task session is loaded in this Pi; use /supervise stop ${taskId} instead`);
+          const record = await decisionStore.load(taskId);
+          if (!record || record.state !== "active") throw new Error(`No recoverable Decision Worker session: ${taskId}`);
+          // "starting"/"registered"/"recovered_idle" mean another Pi owns a
+          // recovery of this task; only a settled record may be dropped here.
+          if (!["ready", "interrupted"].includes(record.recoveryState)) throw new Error(`Decision Worker recovery is in progress elsewhere (${record.recoveryState}); discard only after that Pi has released it: ${taskId}`);
+          // The cwd lease is the ownership record: a live owner means the task
+          // is running in another Pi ("ready" is also its normal state); a dead
+          // owner's lease still guards the cwd against a possibly-live detached
+          // Worker and is only reclaimed through recover --takeover's cleanup
+          // proof, which needs this record. Neither may be discarded from here.
+          const lease = (await cwdLeaseStore.list()).find((candidate) => candidate.taskId === taskId);
+          if (lease) {
+            if (await leaseOwnerLive(lease)) throw new Error(`Task is still owned by a live Pi (pid ${lease.ownerPid}); stop it there instead of discarding it: ${taskId}`);
+            // An adopted session's tmux server is the user's own and stays
+            // alive, so a takeover can never prove the Worker gone; adopting
+            // the session again hands the dead owner's lease over in place.
+            if (lease.worker?.ownership === "adopted" && lease.worker.sessionName) {
+              throw new Error(`Task still holds the cwd lease for ${redactText(lease.cwd)} (owner pid ${lease.ownerPid} is gone); adopt the session again with /supervise adopt-tmux ${lease.worker.sessionName} <task> to take the lease over, then discard this record`);
+            }
+            throw new Error(`Task still holds the cwd lease for ${redactText(lease.cwd)} (owner pid ${lease.ownerPid} is gone); run /supervise recover --takeover --extend 0 ${taskId} to prove the old Worker is gone and close the task out, then stop it if needed`);
+          }
+          await decisionStore.close(taskId);
+          message = `Discarded recoverable task ${taskId} (cwd ${redactText(record.cwd)}); its Decision Worker session file is kept until retention pruning`;
         } else if (operation === "sessions") {
           const recoverable = await decisionStore.list({ activeOnly: true });
           message = formatSessions(sessions, recoverable, tmuxModeLabel());
@@ -913,7 +960,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
         } else if (operation === "status") {
           const { session, sessionId } = resolveSession(sessions, activeTaskId, rest, true);
           message = session
-            ? `task=${sessionId} state=${session.state} worker=${session.handle?.id ?? "none"}${tmuxModeLabel() ? ` mode=${tmuxModeLabel()}` : ""} ${formatUsageDetail(session.usage)}`
+            ? `task=${sessionId} state=${session.state} worker=${session.handle?.id ?? "none"}${tmuxModeLabel() ? ` mode=${tmuxModeLabel()}` : ""}${formatDeadline(session.deadline)} ${formatUsageDetail(session.usage)}`
             : formatSessions(sessions, await decisionStore.list({ activeOnly: true }), tmuxModeLabel());
         } else if (operation === "capabilities") {
           message = JSON.stringify(adapter.capabilities(), null, 2);
@@ -963,7 +1010,7 @@ export default function piClaudeSupervisor(pi: ExtensionAPI): void {
           } else if (operation === "resume-auto") {
             await session.resumeAutomation(); message = `Automatic decisions resumed: ${sessionId}.`;
           } else {
-            throw new Error("Usage: /supervise start|adopt-tmux|recover [--takeover]|sessions|status|poll [all|taskId]|send [taskId]|pause [taskId]|resume [taskId]|stop [taskId]|verify [taskId]|approve [taskId] <allow|deny>|takeover [taskId]|resume-auto [taskId]|capabilities|install-hooks|uninstall-hooks");
+            throw new Error("Usage: /supervise start [--spec <file>] [--deadline <duration>]|adopt-tmux [--spec <file>] [--deadline <duration>]|recover [--takeover] [--extend <duration>]|discard <task-id>|sessions|status|poll [all|taskId]|send [taskId]|pause [taskId]|resume [taskId]|stop [taskId]|verify [taskId]|approve [taskId] <allow|deny>|takeover [taskId]|resume-auto [taskId]|capabilities|install-hooks|uninstall-hooks");
           }
         }
         if (hookInstallNotice) { notify(ctx, hookInstallNotice); hookInstallNotice = undefined; }
@@ -1056,13 +1103,52 @@ function requiresWorkerCleanup(error: unknown): boolean {
   return Boolean(error && typeof error === "object" && (error as { workerCleanupRequired?: unknown }).workerCleanupRequired === true);
 }
 
+/**
+ * Remove a `--name value` or `--name=value` option and return its value.
+ * `--name value` is recognised only in the leading option block (walking
+ * over other options and their values; `flags` take no value), so a task
+ * description that mentions `--deadline` is left alone; `--name=value` is
+ * accepted anywhere, as `--spec=` always was.
+ */
+function takeOption(rest: string[], name: string, flags: readonly string[] = []): string | undefined {
+  for (let index = 0; index < rest.length && rest[index].startsWith("--"); index += 1) {
+    if (rest[index] === name) return rest.splice(index, 2)[1];
+    if (rest[index].startsWith(`${name}=`)) return rest.splice(index, 1)[0]?.slice(name.length + 1);
+    // Another option: its value (when it has one and it is not inline) is the next token.
+    if (!flags.includes(rest[index]) && !rest[index].includes("=")) index += 1;
+  }
+  const inline = rest.findIndex((value) => value.startsWith(`${name}=`));
+  return inline >= 0 ? rest.splice(inline, 1)[0]?.slice(name.length + 1) : undefined;
+}
+
+/** `--deadline` accepts `8h`, `90m`, `2h30m`, plain milliseconds, or `0` to disable the deadline for this task; the same 5m–7d range as `DEADLINE_MS`. */
+function parseTaskDeadline(value: string): number {
+  const parsed = parseDurationMs(value);
+  if (parsed === undefined) throw new Error(`--deadline expects a duration such as 8h, 90m or 0 (disabled): ${value}`);
+  if (parsed !== 0 && (parsed < 5 * 60_000 || parsed > 7 * 24 * 60 * 60_000)) throw new Error("--deadline must be between 5m and 7d, or 0 to disable the deadline");
+  return parsed;
+}
+
+/** A recoverable record's budget: how much is left, or how long ago it expired (recover then needs `--extend`). */
+function formatRecordDeadline(record: DecisionSessionRecord): string {
+  if (record.deadlineMs <= 0) return "";
+  const remaining = record.deadlineMs - (Date.now() - Date.parse(record.startedAt));
+  return remaining > 0 ? ` deadline=${formatDurationMs(remaining)} left` : ` deadline=expired ${formatDurationMs(-remaining)} ago (recover --extend)`;
+}
+
+function formatDeadline(deadline: Supervisor["deadline"]): string {
+  if (!deadline) return "";
+  if (!deadline.closeOut) return ` deadline=${formatDurationMs(deadline.remainingMs)} left`;
+  return ` deadline=close-out (${formatDurationMs(deadline.closeOutRemainingMs ?? 0)} left)`;
+}
+
 function formatSessions(sessions: Map<string, Supervisor>, recoverable: DecisionSessionRecord[] = [], tmuxModeLabel?: string): string {
   const modeSuffix = tmuxModeLabel ? ` mode=${tmuxModeLabel}` : "";
   const active = [...sessions.entries()]
     .map(([taskId, session]) => `${taskId} state=${session.state} cwd=${session.task?.cwd ?? "-"} worker=${session.handle?.id ?? "-"}${modeSuffix}`);
   const pending = recoverable
     .filter((record) => !sessions.has(record.taskId))
-    .map((record) => `${record.taskId} state=recoverable recovery=${record.recoveryState} cwd=${record.cwd} worker=${record.recoveryWorker?.id ?? "-"}${modeSuffix}`);
+    .map((record) => `${record.taskId} state=recoverable recovery=${record.recoveryState} cwd=${record.cwd} worker=${record.recoveryWorker?.id ?? "-"}${modeSuffix}${formatRecordDeadline(record)}`);
   return [...active, ...pending].join("\n") || "No task sessions.";
 }
 

package/src/policy.ts

@@ -333,7 +333,8 @@ function evaluateCommandInternal(command: string, depth: number): PolicyResult {
 }
 
 function evaluateTokens(rawTokens: readonly ShellToken[], depth: number): PolicyResult {
-  const { tokens, embedded } = resolveDataTokens(rawTokens);
+  const { tokens: dataResolved, embedded } = resolveDataTokens(rawTokens);
+  const tokens = resolveLiteralBindings(dataResolved);
   if (depth < 4) {
     for (const body of embedded) {
       const nestedResult = evaluateCommandInternal(body, depth + 1);
@@ -363,6 +364,61 @@ function evaluateTokens(rawTokens: readonly ShellToken[], depth: number): Policy
   return { decision: "allow", reason: "command is allowed for unattended local development" };
 }
 
+/**
+ * `NAME=literal` and `for NAME in literal…` bind a name to text the policy can
+ * see, so a later `$NAME` is not an unseen argument: `for c in 5dae138 feff500;
+ * do git show $c; done` and `S=/tmp/x && cat > $S/log` are literal commands.
+ * Every bound value is substituted (a loop over `status push` yields
+ * `git status push …`, which the boundary checks still catch), and a name
+ * rebound to dynamic text is forgotten again.
+ */
+function resolveLiteralBindings(tokens: readonly ShellToken[]): ShellToken[] {
+  const bindings = new Map<string, string>();
+  const resolved: ShellToken[] = [];
+  const substitute = (token: ShellToken): ShellToken => {
+    if (token.operator || token.data || !token.dynamic || bindings.size === 0) return token;
+    const value = token.value.replace(/\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/gu, (match, name: string) => bindings.get(name) ?? match);
+    if (value === token.value) return token;
+    const dynamic = /[$`*?[\]{}~]/u.test(value) && !/^[[\]{}]+$/u.test(value);
+    return { ...token, value, dynamic };
+  };
+  let commandPosition = true;
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = substitute(tokens[index]!);
+    resolved.push(token);
+    if (token.operator) { commandPosition = SEGMENT_SPLIT_OPERATORS.has(token.value); continue; }
+    const word = token.value;
+    if (commandPosition) {
+      const assignment = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/su.exec(word);
+      if (assignment) {
+        if (token.dynamic) bindings.delete(assignment[1]!);
+        else bindings.set(assignment[1]!, assignment[2]!);
+        continue;
+      }
+      if (word.toLowerCase() === "for") {
+        const name = tokens[index + 1]?.value;
+        const inWord = tokens[index + 2]?.value.toLowerCase();
+        if (name && /^[A-Za-z_][A-Za-z0-9_]*$/u.test(name) && inWord === "in") {
+          const values: string[] = [];
+          let cursor = index + 3;
+          let literal = true;
+          for (; cursor < tokens.length; cursor += 1) {
+            const item = tokens[cursor]!;
+            if (item.operator || item.value.toLowerCase() === "do") break;
+            const substituted = substitute(item);
+            if (substituted.dynamic || substituted.data) literal = false;
+            values.push(substituted.value);
+          }
+          if (literal && values.length > 0) bindings.set(name, values.join(" "));
+          else bindings.delete(name);
+        }
+      }
+      if (!COMMAND_POSITION_KEYWORDS.has(word.toLowerCase())) commandPosition = false;
+    }
+  }
+  return resolved;
+}
+
 /**
  * A quoted heredoc body means whatever its consumer makes of it. Fed to a shell
  * (`bash <<'EOF'`, `cat <<'EOF' | sh`, `eval "$(cat <<'EOF' …)"`) it is a
@@ -534,7 +590,10 @@ function lexShell(input: string): { tokens: ShellToken[]; error?: string } {
     // Brace, tilde and pathname expansion can change command names, targets or
     // Git refs after this lexical pass. Treat all unquoted expansion markers as
     // dynamic rather than attempting to model Bash's expansion order.
-    if ("*?[]{}~".includes(character)) { dynamic = true; value += character; started = true; continue; }
+    // A tilde expands only at the start of a word (or of an assignment value);
+    // `HEAD~1` and `a~b` are literal text.
+    if (character === "~") { if (value === "" || /[=:]$/u.test(value)) dynamic = true; value += character; started = true; continue; }
+    if ("*?[]{}".includes(character)) { dynamic = true; value += character; started = true; continue; }
     if (";&|<>".includes(character)) {
       if (character === "<" && next === "<") {
         const third = input[index + 2];

package/src/supervisor.ts

@@ -3,7 +3,8 @@ import { join } from "node:path";
 import { EventLog, type SupervisorEvent } from "./events.ts";
 import { SupervisorStateMachine } from "./state.ts";
 import { evaluatePermission, isRoutinePermission } from "./policy.ts";
-import { PiDecisionWorker, type DecisionAction, type DecisionWorkerFactory, type DecisionWorkerLike, type PiModel } from "./decision-worker.ts";
+import { PiDecisionWorker, type DecisionAction, type DecisionContext, type DecisionDeadlineContext, type DecisionWorkerFactory, type DecisionWorkerLike, type PiModel } from "./decision-worker.ts";
+import { DEFAULT_DEADLINE_GRACE_MS, DEFAULT_DEADLINE_MS, DEFAULT_DEADLINE_WARNING_MS, DEFAULT_NO_OUTPUT_TIMEOUT_MS, formatDurationMs } from "./config.ts";
 import { collectRepositoryEvidence, repositoryBranch, repositoryCommitExists, repositoryHead, repositoryIsAncestor, repositoryWorkTree, verifyAll, type RepositoryEvidence, type VerificationCommand } from "./verifier.ts";
 import { normalizeTaskSpec } from "./acceptance.ts";
 import { redactSensitive } from "./redaction.ts";
@@ -28,6 +29,8 @@ import type {
 } from "./types.ts";
 
 const DEFAULT_REVIEW_TIMEOUT_MS = 600_000;
+/** A repair round shorter than this cannot finish inside the close-out window; block the candidate instead. */
+const MIN_CLOSE_OUT_REPAIR_MS = 60_000;
 
 export interface DecisionSessionReadyInfo {
   taskId: string;
@@ -96,6 +99,17 @@ export interface SupervisorStartOptions {
   maxTurns?: number;
   /** Maximum wall-clock runtime; defaults to 4 hours for long development tasks. Set to 0 to disable. */
   deadlineMs?: number;
+  /**
+   * Close-out window after the deadline: the Decision Worker is told the
+   * budget is spent, an idle Worker is verified instead of stopped, and the
+   * Worker is stopped outright only once this window has also elapsed.
+   * Defaults to 30 minutes; 0 stops the Worker at the deadline as before.
+   * Only automatic tasks have a close-out (there is nobody else to verify);
+   * a manual task is stopped at the deadline regardless of this value.
+   */
+  deadlineGraceMs?: number;
+  /** Warn the Decision Worker this long before the deadline; defaults to 15 minutes. Set to 0 to disable. */
+  deadlineWarningMs?: number;
   /** Maximum time without worker output; defaults to 20 minutes. Set to 0 to disable. */
   noOutputTimeoutMs?: number;
   /** After a `wait` decision, how long the Worker may stay silent before the Decision Worker is asked again; defaults to 10 minutes. Set to 0 to disable. */
@@ -198,6 +212,8 @@ export class Supervisor {
   #workerOutput = "";
   #lastWorkerResult?: Record<string, unknown>;
   #lastTurnCompleted?: WorkerEvent;
+  /** Key of the completed turn whose decision is still in flight; the deadline must not verify underneath it. */
+  #pendingDecisionKey?: string;
   /** Armed by a `wait` decision: re-asks the Decision Worker if the Worker never resumes on its own. */
   #waitTimer?: NodeJS.Timeout;
   #waitTimeoutMs = 10 * 60_000;
@@ -210,8 +226,17 @@ export class Supervisor {
   #lifecycleTail: Promise<void> = Promise.resolve();
   #pendingEvents: Array<Omit<SupervisorEvent, "seq" | "at">> = [];
   #preemptiveStop?: Promise<void>;
-  #deadlineMs = 4 * 60 * 60_000;
-  #noOutputTimeoutMs = 20 * 60_000;
+  #deadlineMs = DEFAULT_DEADLINE_MS;
+  #deadlineGraceMs = DEFAULT_DEADLINE_GRACE_MS;
+  #deadlineWarningMs = DEFAULT_DEADLINE_WARNING_MS;
+  /**
+   * Each deadline notice is emitted once per task; the close-out itself is
+   * derived from elapsed time. `warningReplayed` records whether the warning's
+   * re-ask reached the Decision Worker, or is still owed because a decision
+   * was in flight when the warning fired.
+   */
+  #deadlineNotices = { approaching: false, reached: false, warningReplayed: false };
+  #noOutputTimeoutMs = DEFAULT_NO_OUTPUT_TIMEOUT_MS;
   #noOutputBaselineAt?: number;
   #verificationAbortController?: AbortController;
   #progressPhase?: SupervisorProgressPhase;
@@ -274,6 +299,8 @@ export class Supervisor {
   get candidateParked() { return this.#candidateParked; }
   /** True after the persistent worker was detached from this Supervisor. */
   get released() { return this.#released; }
+  /** Wall-clock budget of the active task, or undefined when no deadline is configured. */
+  get deadline(): DecisionDeadlineContext | undefined { return this.#deadlineContext(); }
   /** Structural copy of the Worker + Pi-side token/cost accounting for this task. */
   get usage(): SupervisorTokenUsage {
     return {
@@ -301,6 +328,7 @@ export class Supervisor {
     this.#workerOutput = "";
     this.#lastWorkerResult = undefined;
     this.#lastTurnCompleted = undefined;
+    this.#pendingDecisionKey = undefined;
     this.#preemptiveStop = undefined;
     this.#automation = (options.automation ?? false) && spec.autonomy.unattended;
     this.#onDecisionSessionProgress = options.onDecisionSessionProgress;
@@ -327,8 +355,13 @@ export class Supervisor {
     this.#repairRound = options.initialRepairRound ?? 0;
     this.#lastFindingSignature = options.initialFindingSignature;
     this.#turn = options.initialTurn ?? 0;
-    this.#deadlineMs = options.deadlineMs ?? 4 * 60 * 60_000;
-    this.#noOutputTimeoutMs = options.noOutputTimeoutMs ?? 20 * 60_000;
+    this.#deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS;
+    // The close-out is driven by the Decision Worker; without automation the
+    // deadline keeps its plain meaning and the Worker is stopped when it passes.
+    this.#deadlineGraceMs = this.#automation ? Math.max(0, options.deadlineGraceMs ?? DEFAULT_DEADLINE_GRACE_MS) : 0;
+    this.#deadlineWarningMs = Math.max(0, options.deadlineWarningMs ?? DEFAULT_DEADLINE_WARNING_MS);
+    this.#deadlineNotices = { approaching: false, reached: false, warningReplayed: false };
+    this.#noOutputTimeoutMs = options.noOutputTimeoutMs ?? DEFAULT_NO_OUTPUT_TIMEOUT_MS;
     this.#waitTimeoutMs = options.waitTimeoutMs ?? 10 * 60_000;
     this.#noOutputBaselineAt = undefined;
     this.#verificationAbortController = undefined;
@@ -420,8 +453,9 @@ export class Supervisor {
       this.#assertStartNotAborted(startAbortController.signal);
       if (this.#automation) {
         const createDecisionWorker: DecisionWorkerFactory = options.decisionWorkerFactory ?? ((decisionOptions) => new PiDecisionWorker(decisionOptions));
+        const deadline = this.#deadlineContext();
         this.#decision = createDecisionWorker({
-          context: { taskId, task: spec.goal, cwd: options.cwd, state: this.#machine.state, turn: this.#turn, maxTurns: this.#task.maxTurns, repairRound: this.#repairRound, spec },
+          context: { taskId, task: spec.goal, cwd: options.cwd, state: this.#machine.state, turn: this.#turn, maxTurns: this.#task.maxTurns, repairRound: this.#repairRound, spec, ...(deadline ? { deadline } : {}) },
           sessionFile: options.decisionSessionFile,
           sessionDir: options.decisionSessionDir ? join(options.decisionSessionDir, taskId) : undefined,
           model: this.#decisionModel,
@@ -733,8 +767,7 @@ export class Supervisor {
       // recorded above so resumeAutomation can replay it once automation resumes.
       const suppressTurnCompletedForHuman = this.#humanRequired && event.type === "turn_completed";
       if (this.#decision && !skipDecisionNotify && !suppressTurnCompletedForHuman && (event.type === "permission_request" || event.type === "turn_completed" || event.type === "exited")) {
-        this.#decision.updateContext({ state: this.#machine.state, turn: this.#turn, repairRound: this.#repairRound });
-        this.#decision.notify(event);
+        this.#notifyDecision(event);
       }
       this.#handledEvents.add(key);
       this.#deferredWorkerEvents.delete(key);
@@ -822,6 +855,7 @@ export class Supervisor {
 
   async #decisionFailure(event: WorkerEvent, error: unknown): Promise<void> {
     return this.#exclusive(async () => {
+      this.#settlePendingDecision(event);
       if (this.#releasing || this.#released) {
         await this.#appendDecisionIgnored(event, undefined);
         return;
@@ -847,6 +881,7 @@ export class Supervisor {
 
   async #applyDecision(action: DecisionAction, event: WorkerEvent): Promise<void> {
     return this.#exclusive(async () => {
+      this.#settlePendingDecision(event);
       const task = this.#task;
       const handle = this.#handle;
       if (this.#releasing || this.#released) {
@@ -858,9 +893,14 @@ export class Supervisor {
         await this.#appendEvent({ type: "decision_deferred", taskId: task.taskId, workerId: handle.id, data: { action: action.action, reason: action.reason, eventType: event.type } }).catch(() => {});
         return;
       }
+      // A repeated `wait` for the same event (the wait timer's re-ask, or a
+      // deadline-phase replay) must re-arm the timer, so it is never deduped;
+      // every other action is applied once per event.
       const actionKey = `${workerEventKey(event)}:${action.action}`;
-      if (this.#handledEvents.has(actionKey)) return;
-      this.#handledEvents.add(actionKey);
+      if (action.action !== "wait") {
+        if (this.#handledEvents.has(actionKey)) return;
+        this.#handledEvents.add(actionKey);
+      }
       await this.#appendEvent({ type: "decision_made", taskId: task.taskId, workerId: handle.id, data: { action: action.action, reason: action.reason, confidence: action.confidence } });
       if (action.action === "allow_permission" || action.action === "deny_permission") {
         if (event.type !== "permission_request" || !this.#adapter.respondPermission) {
@@ -914,23 +954,33 @@ export class Supervisor {
         return;
       }
       if (action.action === "wait") {
+        // The deadline warning fired while this decision was in flight, so it
+        // was made from a pre-warning view of the clock: ask once more with
+        // the current clock before settling for a wait.
+        if (this.#deadlineNotices.approaching && !this.#deadlineNotices.warningReplayed && !this.#inCloseOut() && this.#decision?.replay
+          && this.#machine.state === "waiting" && event.type === "turn_completed" && await this.#workerIdle(handle)) {
+          this.#deadlineNotices.warningReplayed = true;
+          this.#clearWaitTimer();
+          this.#notifyDecision(event, true);
+          return;
+        }
+        // Once the deadline has passed there is nothing left to wait for: an
+        // idle Worker is verified now, before the close-out window runs out.
+        // A Worker that has resumed on its own keeps its turn; its next
+        // completed turn is decided under close-out as usual.
+        if (this.#inCloseOut() && this.#machine.state === "waiting" && await this.#workerIdle(handle)) {
+          await this.#noteDeadlineReached();
+          await this.#appendEvent({ type: "decision_overridden", taskId: task.taskId, workerId: handle.id, data: { action: "wait", override: "verify", reason: "task deadline reached; wait is unavailable during close-out", eventType: event.type } });
+          await this.#startVerification(handle, event, "deadline close-out");
+          return;
+        }
         // The Worker will be re-invoked by its own background work; send
         // nothing, but re-ask if it stays silent for the wait timeout.
         this.#armWaitTimer(event);
         return;
       }
       if (action.action === "verify") {
-        if (this.#machine.state === "waiting" && canRepairInPlace(this.#adapter)) {
-          this.#machine.transition("verifying");
-          await this.#verifyInternal();
-          return;
-        }
-        if (this.#machine.state === "waiting") {
-          await this.#adapter.stop(handle, "Decision Worker requested verification");
-          await this.#pollInternal(true);
-        }
-        if (this.#machine.state === "verifying") await this.#verifyInternal();
-        else await this.#parkCandidate(`Decision Worker requested verification from state ${this.#machine.state}`, event);
+        await this.#startVerification(handle, event, "Decision Worker");
         return;
       }
       if (action.action === "noop") {
@@ -960,6 +1010,48 @@ export class Supervisor {
     });
   }
 
+  /**
+   * Move an idle Worker into verification the way a `verify` decision does:
+   * in place when the transport supports it, otherwise by stopping the
+   * Worker first. `origin` names who asked, for the stop reason and the park
+   * message.
+   */
+  async #startVerification(handle: WorkerHandle, event: WorkerEvent | undefined, origin: string): Promise<void> {
+    if (this.#machine.state === "waiting" && canRepairInPlace(this.#adapter)) {
+      this.#machine.transition("verifying");
+      await this.#verifyInternal();
+      return;
+    }
+    if (this.#machine.state === "waiting") {
+      await this.#adapter.stop(handle, `${origin} requested verification`);
+      await this.#pollInternal(true);
+    }
+    if (this.#machine.state === "verifying") await this.#verifyInternal();
+    else await this.#parkCandidate(`${origin} requested verification from state ${this.#machine.state}`, event);
+  }
+
+  /** Refresh the Decision Worker's context and deliver (or re-deliver) an event; a completed turn is then pending a decision. */
+  #notifyDecision(event: WorkerEvent, replay = false): void {
+    if (!this.#decision) return;
+    // A Decision Worker without replay support gets nothing re-delivered, so
+    // nothing must be marked as pending on its account.
+    if (replay && !this.#decision.replay) return;
+    this.#decision.updateContext(this.#decisionContextPatch());
+    if (event.type === "turn_completed") this.#pendingDecisionKey = workerEventKey(event);
+    if (replay) this.#decision.replay!(event);
+    else this.#decision.notify(event);
+  }
+
+  #settlePendingDecision(event: WorkerEvent): void {
+    if (this.#pendingDecisionKey && this.#pendingDecisionKey === workerEventKey(event)) this.#pendingDecisionKey = undefined;
+  }
+
+  /** True when the adapter reports no active Worker turn; a status failure counts as busy. */
+  async #workerIdle(handle: WorkerHandle): Promise<boolean> {
+    const status = await this.#adapter.getStatus(handle).catch(() => undefined);
+    return Boolean(status) && !status!.activeRequests;
+  }
+
   /**
    * A decision about a completed turn is stale once the Worker has started a
    * new turn on its own (a background agent, task or monitor of its own
@@ -992,8 +1084,7 @@ export class Supervisor {
         const status = await this.#adapter.getStatus(handle).catch(() => undefined);
         if (status?.activeRequests) return;
         await this.#appendEvent({ type: "wait_expired", taskId: this.#task?.taskId, workerId: handle.id, data: { waitTimeoutMs: this.#waitTimeoutMs } }).catch(() => {});
-        this.#decision.updateContext({ state: this.#machine.state, turn: this.#turn, repairRound: this.#repairRound });
-        this.#decision.replay?.(event);
+        this.#notifyDecision(event, true);
       }).catch(() => { /* the watchdog still covers a silent Worker */ });
     }, this.#waitTimeoutMs);
     this.#waitTimer.unref?.();
@@ -1134,8 +1225,7 @@ export class Supervisor {
         // it has resumed on its own, its next Stop brings a fresh turn.
         const status = await this.#adapter.getStatus(this.#handle).catch(() => undefined);
         if (status?.activeRequests) return;
-        this.#decision.updateContext({ state: this.#machine.state, turn: this.#turn, repairRound: this.#repairRound });
-        this.#decision.replay?.(this.#lastTurnCompleted);
+        this.#notifyDecision(this.#lastTurnCompleted, true);
       }
     });
   }
@@ -1610,6 +1700,13 @@ export class Supervisor {
       await this.#appendEvent({ type: "candidate_blocked", taskId: task.taskId, workerId: handle.id, data: { reason: `${reason}; Worker transport does not support in-place repair` } });
       return false;
     }
+    // A repair round that the outright stop would cut short only wastes the
+    // findings: keep them on a blocked candidate instead.
+    const closeOut = this.#deadlineContext();
+    if (closeOut?.closeOut && (closeOut.closeOutRemainingMs ?? 0) < MIN_CLOSE_OUT_REPAIR_MS) {
+      await this.#appendEvent({ type: "candidate_blocked", taskId: task.taskId, workerId: handle.id, data: { reason: `${reason}; the task's close-out window is exhausted (${formatDurationMs(closeOut.closeOutRemainingMs ?? 0)} left), no repair round can finish` } });
+      return false;
+    }
     const status = await this.#adapter.getStatus(handle);
     if (!status.running || !["running", "waiting", "verifying"].includes(this.#machine.state)) {
       await this.#appendEvent({ type: "candidate_blocked", taskId: task.taskId, workerId: handle.id, data: { reason: `${reason}; Worker is no longer available for automatic repair` } });
@@ -1617,8 +1714,15 @@ export class Supervisor {
     }
     this.#repairRound += 1;
     task.repairRound = this.#repairRound;
-    const instruction = repairInstruction(result, reason, this.#repairRound);
-    await this.#appendEvent({ type: "repair_requested", taskId: task.taskId, workerId: handle.id, data: { round: this.#repairRound, reason, instruction } });
+    // After the deadline a repair round races the close-out window: tell the
+    // Worker how long it has so it commits what is complete instead of
+    // starting more work the outright stop would discard.
+    const deadline = this.#deadlineContext();
+    const closeOutHint = deadline?.closeOut && deadline.closeOutRemainingMs !== undefined
+      ? ` The task's wall-clock budget is spent: you have about ${formatDurationMs(deadline.closeOutRemainingMs)} before the Supervisor stops this session. Address only what is required above, commit what is complete, and stop.`
+      : "";
+    const instruction = repairInstruction(result, reason, this.#repairRound) + closeOutHint;
+    await this.#appendEvent({ type: "repair_requested", taskId: task.taskId, workerId: handle.id, data: { round: this.#repairRound, reason, instruction, ...(deadline?.closeOut ? { closeOutRemainingMs: deadline.closeOutRemainingMs } : {}) } });
     this.#reportProgress("repair", `sending repair round ${this.#repairRound}`, true);
     if (this.#machine.state === "verifying") this.#machine.transition("running");
     this.#repairSendInProgress = true;
@@ -1826,7 +1930,7 @@ export class Supervisor {
     }
     this.#reportProgress("worker", `Worker ${this.#machine.state}; heartbeat`, false);
     const now = Date.now();
-    const taskStartedAt = Date.parse(this.#task.startedAt);
+    const elapsed = this.#deadlineElapsedMs(now);
     // The deadline is cumulative across recovery, but the no-output timer
     // starts when this worker process starts. Otherwise a slow Decision Worker
     // startup or a recovered task can be stopped on its first watchdog tick
@@ -1834,12 +1938,24 @@ export class Supervisor {
     const workerStartedAt = Date.parse(this.#handle.startedAt);
     const observedLastOutputAt = status.lastOutputAt ? Date.parse(status.lastOutputAt) : workerStartedAt;
     const lastOutputAt = Math.max(observedLastOutputAt, this.#noOutputBaselineAt ?? 0);
-    const reason = this.#deadlineMs > 0 && now - taskStartedAt >= this.#deadlineMs
+    const deadlineReached = this.#deadlineMs > 0 && elapsed >= this.#deadlineMs;
+    // The deadline itself opens a close-out window; the outright stop waits
+    // for the grace period as well (an empty grace keeps the old immediate stop).
+    const reason = deadlineReached && elapsed >= this.#deadlineMs + this.#deadlineGraceMs
       ? "worker deadline exceeded"
       : this.#machine.state !== "paused" && this.#noOutputTimeoutMs > 0 && now - lastOutputAt >= this.#noOutputTimeoutMs
         ? "worker produced no output before timeout"
         : undefined;
-    if (!reason) return;
+    if (!reason) {
+      if (deadlineReached) await this.#enterCloseOut(status, elapsed);
+      else if (this.#deadlineMs > 0 && this.#deadlineWarningMs > 0 && !this.#deadlineNotices.approaching && this.#deadlineMs - elapsed <= this.#deadlineWarningMs) {
+        await this.#warnDeadlineApproaching(status, this.#deadlineMs - elapsed);
+      }
+      return;
+    }
+    // A close-out window that was skipped entirely (a task recovered past its
+    // budget) still leaves the deadline notice ahead of the stop in the log.
+    if (deadlineReached && this.#deadlineGraceMs > 0) await this.#noteDeadlineReached(elapsed).catch(() => {});
     let timeoutEventError: unknown;
     try {
       await this.#appendEvent({ type: "worker_watchdog_timeout", taskId: this.#task.taskId, workerId: this.#handle.id, data: { reason } });
@@ -1856,6 +1972,121 @@ export class Supervisor {
     if (timeoutEventError) throw timeoutEventError;
   }
 
+  #deadlineElapsedMs(now = Date.now()): number {
+    return this.#task ? Math.max(0, now - Date.parse(this.#task.startedAt)) : 0;
+  }
+
+  /**
+   * True while the task is in its close-out window: the deadline has passed
+   * and a grace window exists. With no grace there is no close-out, only the
+   * outright stop on the next watchdog tick.
+   */
+  #inCloseOut(now = Date.now()): boolean {
+    return Boolean(this.#task) && this.#deadlineMs > 0 && this.#deadlineGraceMs > 0 && this.#deadlineElapsedMs(now) >= this.#deadlineMs;
+  }
+
+  #deadlineContext(now = Date.now()): DecisionDeadlineContext | undefined {
+    if (!this.#task || this.#deadlineMs <= 0) return undefined;
+    const elapsed = this.#deadlineElapsedMs(now);
+    const closeOut = this.#deadlineGraceMs > 0 && elapsed >= this.#deadlineMs;
+    return {
+      totalMs: this.#deadlineMs,
+      graceMs: this.#deadlineGraceMs,
+      remainingMs: Math.max(0, this.#deadlineMs - elapsed),
+      closeOut,
+      ...(closeOut ? { closeOutRemainingMs: Math.max(0, this.#deadlineMs + this.#deadlineGraceMs - elapsed) } : {}),
+    };
+  }
+
+  /** The per-event context refresh sent to the Decision Worker before every notification or replay. */
+  #decisionContextPatch(): Partial<DecisionContext> {
+    const deadline = this.#deadlineContext();
+    return { state: this.#machine.state, turn: this.#turn, repairRound: this.#repairRound, ...(deadline ? { deadline } : {}) };
+  }
+
+  /**
+   * The deadline is near: record it once, refresh the Decision Worker's view
+   * of the clock and, if the Worker is idle under a `wait`, ask the Decision
+   * Worker again so it can steer the Worker toward a wrap-up while there is
+   * still time to verify the result.
+   */
+  async #warnDeadlineApproaching(status: WorkerStatus, remainingMs: number): Promise<void> {
+    if (!this.#task || !this.#handle) return;
+    this.#deadlineNotices.approaching = true;
+    // A failed append leaves the event queued for the next flush; the clock
+    // refresh below must happen either way.
+    let appendError: unknown;
+    try {
+      await this.#appendEvent({ type: "worker_deadline_approaching", taskId: this.#task.taskId, workerId: this.#handle.id, data: { deadlineMs: this.#deadlineMs, graceMs: this.#deadlineGraceMs, remainingMs } });
+    } catch (error) {
+      appendError = error;
+    }
+    this.#reportProgress("worker", `deadline in ${formatDurationMs(remainingMs)}${this.#deadlineGraceMs > 0 ? `; close-out window ${formatDurationMs(this.#deadlineGraceMs)}` : ""}`, true);
+    if (!this.#decision) {
+      this.#deadlineNotices.warningReplayed = true;
+      if (appendError) throw appendError;
+      return;
+    }
+    this.#decision.updateContext(this.#decisionContextPatch());
+    // A decision in flight was prompted with the pre-warning clock; the
+    // re-ask is then owed to its `wait`, see #applyDecision. Any other
+    // reason not to re-ask now (human, busy Worker, no turn) is final.
+    if (!this.#pendingDecisionKey && (this.#humanRequired || this.#candidateParked || this.#machine.state !== "waiting" || !this.#lastTurnCompleted || status.activeRequests)) {
+      this.#deadlineNotices.warningReplayed = true;
+    } else if (!this.#pendingDecisionKey) {
+      this.#deadlineNotices.warningReplayed = true;
+      this.#clearWaitTimer();
+      this.#notifyDecision(this.#lastTurnCompleted!, true);
+    }
+    if (appendError) throw appendError;
+  }
+
+  /** Record the deadline once, whichever path notices it first (the watchdog tick or a decision applied under close-out). */
+  async #noteDeadlineReached(elapsed = this.#deadlineElapsedMs()): Promise<void> {
+    if (this.#deadlineNotices.reached || !this.#task || !this.#handle) return;
+    this.#deadlineNotices.reached = true;
+    const closeOutRemainingMs = Math.max(0, this.#deadlineMs + this.#deadlineGraceMs - elapsed);
+    let appendError: unknown;
+    try {
+      await this.#appendEvent({ type: "worker_deadline_reached", taskId: this.#task.taskId, workerId: this.#handle.id, data: { deadlineMs: this.#deadlineMs, graceMs: this.#deadlineGraceMs, elapsedMs: elapsed, closeOutRemainingMs } });
+    } catch (error) {
+      appendError = error;
+    }
+    this.#reportProgress("worker", `deadline reached after ${formatDurationMs(elapsed)}; closing out within ${formatDurationMs(closeOutRemainingMs)}`, true);
+    this.#decision?.updateContext(this.#decisionContextPatch());
+    if (appendError) throw appendError;
+  }
+
+  /**
+   * The deadline has passed. Record it once, then drive the close-out: an
+   * idle automatic Worker is verified now; a busy one is decided under
+   * close-out when its turn completes; the outright stop waits for the grace
+   * window. Without automation the notice is the operator's cue to verify.
+   */
+  async #enterCloseOut(status: WorkerStatus, elapsed: number): Promise<void> {
+    const task = this.#task;
+    const handle = this.#handle;
+    if (!task || !handle) return;
+    await this.#noteDeadlineReached(elapsed);
+    if (!this.#automation || !this.#decision || this.#humanRequired || this.#candidateParked) return;
+    // An idle Worker that never completed a turn under this Supervisor (an
+    // adopted session, or one recovered past its budget) still reports
+    // `running`: the running -> waiting classification lives in #pollInternal,
+    // which nothing else calls while the Worker is alive.
+    if (this.#machine.state === "running" && !status.activeRequests) await this.#pollInternal();
+    // A decision still in flight for the last turn owns the next step: it is
+    // applied under close-out (a `wait` becomes verify) once it arrives.
+    if (this.#pendingDecisionKey || this.#machine.state !== "waiting" || this.#verificationAbortController || status.activeRequests) return;
+    this.#clearWaitTimer();
+    await this.#appendEvent({ type: "deadline_close_out", taskId: task.taskId, workerId: handle.id, data: { action: "verify", reason: "task deadline reached with an idle Worker" } });
+    try {
+      await this.#startVerification(handle, this.#lastTurnCompleted, "deadline close-out");
+    } catch (error) {
+      // Verification failures are parked inside #verifyInternal; audit the rest.
+      await this.#appendEvent({ type: "worker_event_error", taskId: task.taskId, workerId: handle.id, data: { error: safeMessage(error), eventType: "deadline_close_out" } }).catch(() => {});
+    }
+  }
+
   /**
    * Best-effort accounting for a Worker `result` stream-json record; `total_cost_usd`
    * is cumulative for the Worker's own process session, so a value smaller than the
@@ -2104,6 +2335,16 @@ function removeFlagWithValue(args: readonly string[], flag: string): string[] {
   return result;
 }
 
+/**
+ * The deadline (in ms since the task started) that grants `extendMs` more
+ * from now: measured from the later of the current deadline and the present,
+ * so extending an expired task by 30 minutes means 30 minutes from now, and
+ * extending by 0 opens its close-out immediately.
+ */
+export function extendedDeadlineMs(currentDeadlineMs: number, elapsedMs: number, extendMs: number): number {
+  return Math.max(currentDeadlineMs, elapsedMs) + Math.max(0, extendMs);
+}
+
 function isProtectedBranch(branch: string): boolean {
   return /^(?:main|master|trunk|integration|develop)$/iu.test(branch) || /(?:^|\/)(?:main|master|integration)$/iu.test(branch);
 }

package/src/worker/tmux-adapter.ts

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
-import { constants as fsConstants } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { constants as fsConstants, lstatSync, readdirSync, unlinkSync } from "node:fs";
 import { access, chmod, lstat, mkdir, open, readdir, readFile, realpath, rm, rmdir, stat, truncate, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { delimiter, dirname, isAbsolute, join } from "node:path";
@@ -798,6 +798,7 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
       if (record.owned) {
         await this.#stopGuardian(record).catch((error) => { record.cleanupError ??= asError(error); });
         await this.#run(record, ["kill-server"], undefined, undefined, true).catch(() => {});
+        removeDeadTmuxSocket(record.handle.tmuxSocket);
       } else await this.#detachPipe(record);
     }
     const deadline = Date.now() + 25_000;
@@ -1670,6 +1671,7 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
       if (isMissingSession(error)) record.serverKilled = true;
       else record.cleanupError = asError(error);
     }
+    if (record.serverKilled) removeDeadTmuxSocket(record.handle.tmuxSocket);
     if (!record.serverKilled) await this.#ensurePaneGone(record);
     if (record.cgroupPath) {
       try {
@@ -2281,9 +2283,49 @@ function normalizeForMatch(value: string): string {
   return value.trim().replace(/\s+/gu, " ");
 }
 
-/** True for a prompt Claude Code injected itself (`<task-notification>`, `<system-reminder>`), which a human never typed. */
+/**
+ * A tmux server removes its socket when it exits normally, but not when it is
+ * killed with its cgroup; a dead `pi-cs-*.sock` is unlinked once no server
+ * answers on it. `sweepDeadTmuxSockets` does the same for every socket the
+ * adapter's naming scheme left behind in the temp directory.
+ */
+function removeDeadTmuxSocket(socketPath: string | undefined): void {
+  if (!socketPath || !/[\\/]pi-cs-[0-9a-f-]+\.sock$/u.test(socketPath)) return;
+  try {
+    const probe = spawnSync("tmux", ["-S", socketPath, "list-sessions"], { stdio: "ignore", timeout: 2_000 });
+    // A server that answers, or a socket something else holds open (the probe
+    // timed out), is left alone.
+    if (probe.status === 0 || probe.signal) return;
+    unlinkSync(socketPath);
+  } catch { /* already gone, or not ours to remove */ }
+}
+
+export function sweepDeadTmuxSockets(directory = tmpdir()): number {
+  let removed = 0;
+  let names: string[];
+  try { names = readdirSync(directory); } catch { return 0; }
+  for (const name of names) {
+    if (!/^pi-cs-[0-9a-f-]+\.sock$/u.test(name)) continue;
+    const socketPath = join(directory, name);
+    try {
+      if (!lstatSync(socketPath).isSocket()) continue;
+      const probe = spawnSync("tmux", ["-S", socketPath, "list-sessions"], { stdio: "ignore", timeout: 2_000 });
+      if (probe.status === 0 || probe.signal) continue;
+      unlinkSync(socketPath);
+      removed += 1;
+    } catch { /* skip */ }
+  }
+  return removed;
+}
+
+/**
+ * True for a prompt Claude Code injected itself, which a human never typed:
+ * `<task-notification>`, `<system-reminder>`, `<agent-message …>` and the
+ * other hyphenated runtime wrappers it frames delivered content with. A
+ * person's own message does not begin with such a tag.
+ */
 function isClaudeRuntimePrompt(prompt: string): boolean {
-  return /^\s*<(?:task-notification|system-reminder)\b/u.test(prompt);
+  return /^\s*<[a-z]+(?:-[a-z]+)+(?:\s|>)/u.test(prompt);
 }
 
 /**
@@ -2407,7 +2449,10 @@ function isPaneIdentityError(error: unknown): boolean {
 }
 
 function isMissingSession(error: unknown): boolean {
-  return error instanceof Error && /(can't find session|no server running|session not found|failed to connect)/iu.test(error.message);
+  // tmux leaves its socket behind on exit ("no server running") unless it was
+  // unlinked, in which case it reports "error connecting … (No such file or
+  // directory)"; both mean the same thing here.
+  return error instanceof Error && /(can't find session|no server running|session not found|failed to connect|error connecting to [^\n]*No such file or directory)/iu.test(error.message);
 }
 
 function isMissingFile(error: unknown): boolean {