pi-claude-supervisor 0.7.3 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 All notable changes to this project will be documented here.
 
+## [0.8.1](https://github.com/btnalit/pi-claude-supervisor/compare/v0.8.0...v0.8.1) (2026-09-20)
+
+
+### Bug Fixes
+
+* **policy:** let a Worker keep its own memory, and make denials actionable ([605fb58](https://github.com/btnalit/pi-claude-supervisor/commit/605fb5860b38ee9023ad980b3101708cadd39fb2))
+* **policy:** make the memory write root actually reachable, and drop the cwd-identity relaxation ([8a1bfc5](https://github.com/btnalit/pi-claude-supervisor/commit/8a1bfc55f97421997b0a8c87f0b1ae9cd7c94ba9))
+* **tmux:** accept an adopted pane whose cwd path went stale but is the same directory ([207219c](https://github.com/btnalit/pi-claude-supervisor/commit/207219c1fec218d1eecf1920c5ba9a2806935a8f))
+
+## [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)
 
 

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,52 @@ 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 denial is a capability boundary the Worker has to route around by itself, so
+each one names a remedy it can act on: a dynamic argument says to substitute the
+literal value so the command can be read, and an outside-cwd write names the
+write roots this Worker actually holds (and nothing when it holds none). Those
+roots are what the permission policy accepts beside the task cwd: the scratchpad
+Claude reports at SessionStart, and its per-project memory directory, derived
+from the session's own `transcript_path`. The transcript path is captured from
+any hook event, since an adopted session never replays SessionStart, and it is
+untrusted input, so the shape is verified rather than trusted — it must be
+`<…>/.claude/projects/<slug>/<session>.jsonl` whose slug is the one Claude
+derives from this task's cwd, which rejects a subagent transcript and any path
+naming another project. A root is honored before it exists (Claude creates the
+memory directory on first write) and through a symlinked ancestor.
+
+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.3",
+  "version": "0.8.1",
   "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

@@ -9,12 +9,12 @@ import { redactSensitive } from "./redaction.ts";
 import { ProcessWorkerAdapter } from "./worker/process-adapter.ts";
 import { automaticWorkerEnvironment } from "./worker/environment.ts";
 import { TmuxWorkerAdapter, attachCommand, sweepDeadTmuxSockets } from "./worker/tmux-adapter.ts";
-import { Supervisor, type DecisionSessionClosedInfo, type HumanInterventionNotice, type SupervisorProgress, type SupervisorTokenUsage } from "./supervisor.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";
@@ -369,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;
@@ -387,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(() => {});
@@ -458,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,
@@ -643,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);
@@ -654,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");
@@ -786,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,
@@ -906,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());
@@ -916,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);
@@ -966,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; }
@@ -1059,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

@@ -1,5 +1,5 @@
 import { lstatSync, realpathSync, statSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 export type PolicyDecision = "allow" | "review" | "deny";
 
@@ -26,7 +26,12 @@ export function evaluatePermission(toolName: string, input: unknown, cwd = proce
     const paths = fileToolPaths(input);
     if (paths.length === 0) return { decision: "deny", reason: `${toolName} request has no recognizable file path` };
     const violation = paths.map((path) => ({ path, classification: classifyWritePath(path, cwd, options.writeRoots) })).find((entry) => entry.classification !== undefined);
-    if (violation?.classification === "outside-cwd") return { decision: "deny", reason: `Worker cannot write outside the task working directory: ${violation.path}` };
+    if (violation?.classification === "outside-cwd") {
+      // Only name an alternative the Worker actually has: writeRoots is empty
+      // for a bridge Worker and before an adopted session's first hook event.
+      const alternatives = (options.writeRoots ?? []).length > 0 ? `; scratch work may go under ${(options.writeRoots ?? []).join(", ")}` : "";
+      return { decision: "deny", reason: `Worker cannot write outside the task working directory: ${violation.path}${alternatives}` };
+    }
     if (violation?.classification === "git-metadata") return { decision: "deny", reason: "Worker cannot write Git metadata or protected branch refs" };
     return { decision: "allow", reason: `local Claude file tool is allowed by the task policy: ${toolName}` };
   }
@@ -50,19 +55,47 @@ function fileToolPaths(input: unknown): string[] {
 
 type WritePathViolation = "outside-cwd" | "git-metadata";
 
+/**
+ * `realpath` of the deepest ancestor that exists, with the not-yet-created tail
+ * re-appended. Plain `realpathSync` throws for a directory the Worker is about
+ * to create, and the caller cannot tell that apart from a hostile path.
+ */
+function resolveExistingPath(path: string): string {
+  let current = resolve(path);
+  const missing: string[] = [];
+  for (;;) {
+    try { return join(realpathSync(current), ...[...missing].reverse()); }
+    catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") return resolve(path);
+      const parent = dirname(current);
+      if (parent === current) return resolve(path);
+      missing.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
 function classifyWritePath(value: string, cwd: string, writeRoots: readonly string[] = []): WritePathViolation | undefined {
   if (value.replaceAll("\\", "/").split("/").some((segment) => segment.toLowerCase() === ".git")) return "git-metadata";
   // A path inside an extra write root (Claude's own scratchpad) is judged
   // against that root instead of the cwd, with the same symlink/metadata rules.
   for (const root of writeRoots) {
     if (!isAbsolute(root) || !isAbsolute(value)) continue;
-    const rel = relative(root, value);
+    // Resolve both sides before comparing: a write root reached through a
+    // symlinked ancestor (a dotfile-managed ~/.claude, /var on macOS) would
+    // otherwise be judged outside itself. The final component stays unresolved
+    // so the per-segment symlink and `.git` checks below still see it.
+    const resolvedRoot = resolveExistingPath(root);
+    const resolvedValue = join(resolveExistingPath(dirname(value)), basename(value));
+    const rel = relative(resolvedRoot, resolvedValue);
     if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) continue;
-    return classifyWritePath(value, root);
+    return classifyWritePath(resolvedValue, resolvedRoot);
   }
-  let root: string;
-  try { root = realpathSync(cwd); }
-  catch { return "git-metadata"; }
+  // A write root need not exist yet: Claude creates its memory directory on
+  // the first write, and failing closed there denied the very write the
+  // outside-cwd message points at.
+  const root = resolveExistingPath(cwd);
   const raw = value.replaceAll("\\", "/");
   const canonicalRoot = root.replaceAll("\\", "/").replace(/\/+$/u, "") || "/";
   let components: string[];
@@ -212,7 +245,7 @@ function evaluateRepositoryBoundary(tokens: readonly ShellToken[], canonical: st
   // Dynamic text in an ordinary local command (`for f in …; echo "$f"`) or in
   // another statement (`npm test; echo "exit $?"`) is Claude's own business.
   if ((hasDynamicArgument && hasDynamicCommandName(tokens)) || segmentsOf(tokens).some((segment) => hasDynamicSensitiveArgument(segment))) {
-    return { decision: "deny", reason: "a repository, package, network or shell command with a dynamic argument cannot be capability-checked" };
+    return { decision: "deny", reason: "a repository, package, network or shell command with a dynamic argument cannot be capability-checked; substitute the literal value for the shell variable so the command can be read, or use the Write/Edit tools when the intent is to change a file" };
   }
   if (/\bgit\b[\s\S]*\b(?:push|merge(?!-)|send-pack|receive-pack|update-ref)\b/iu.test(canonical)
     || /\bgit-(?:send|receive|upload)-pack\b/iu.test(canonical)

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

@@ -3,7 +3,7 @@ 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";
+import { basename, delimiter, dirname, isAbsolute, join } from "node:path";
 import type {
   PermissionDecision,
   WorkerAdapter,
@@ -1344,6 +1344,11 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
     if (expected?.pid !== undefined && pane.pid !== expected.pid) throw new Error("tmux pane pid changed; refusing identity-unverified handoff");
     if (pane.dead) throw new Error("cannot adopt a dead tmux pane");
     record.handle.pid = pane.pid;
+    // Compared as reported, not by inode identity: the hook relay routes events
+    // by the SHA-256 of realpath(cwd), so a pane whose cwd merely *resolves* to
+    // the same directory under a different spelling would be adopted and then
+    // never deliver a single hook event -- an unsupervised Worker that looks
+    // supervised. A mismatch means the pane cannot be governed, so it is refused.
     const currentPath = await this.#run(record, ["display-message", "-p", "-t", record.target, "#{pane_current_path}"]);
     if (currentPath.stdout.trim() !== cwd) throw new Error(`tmux session cwd mismatch: expected ${cwd}, got ${currentPath.stdout.trim()}`);
     const command = (await this.#run(record, ["display-message", "-p", "-t", record.target, "#{pane_current_command}"])).stdout.trim();
@@ -1989,12 +1994,16 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
     }
     record.lastOutputAt = new Date().toISOString();
     const event = request.event;
+    // Every hook event carries `transcript_path`, and an adopted session never
+    // replays SessionStart, so capture it here rather than only at startup:
+    // it is what locates Claude's own per-project memory directory below.
+    if (!record.transcriptPath && isSafeAbsolutePath(event.transcript_path)) record.transcriptPath = event.transcript_path;
     switch (event.hook_event_name) {
       case "SessionStart": {
         record.claudeSessionId ??= event.session_id;
         record.handle.sessionId = event.session_id;
-        if (event.transcript_path) record.transcriptPath = event.transcript_path;
-        if (typeof event.scratchpad_dir === "string" && isAbsolute(event.scratchpad_dir) && !event.scratchpad_dir.includes("\0")) record.scratchpadDir = event.scratchpad_dir;
+        if (isSafeAbsolutePath(event.transcript_path)) record.transcriptPath = event.transcript_path;
+        if (isSafeAbsolutePath(event.scratchpad_dir)) record.scratchpadDir = event.scratchpad_dir;
         record.sessionStartReceived = true;
         return {};
       }
@@ -2068,6 +2077,7 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
     // itself away in respondPermission and hang the relay.
     record.permissionResponses.delete(requestId);
     const toolUseId = event.tool_use_id ?? requestId;
+    const writeRoots = writeRootsOf(record);
     this.#emit(record, {
       type: "permission_request",
       handle: record.handle,
@@ -2078,7 +2088,7 @@ export class TmuxWorkerAdapter implements WorkerAdapter {
         input: event.tool_input,
         raw: event as unknown as Record<string, unknown>,
         phase,
-        ...(record.scratchpadDir ? { writeRoots: [record.scratchpadDir] } : {}),
+        ...(writeRoots.length > 0 ? { writeRoots } : {}),
       },
     });
     return new Promise<HookRelayReply>((resolve) => {
@@ -2151,6 +2161,44 @@ function bridgeEnvironment(env: NodeJS.ProcessEnv, cwd: string, command: string,
   return result;
 }
 
+/** Same shape the decision-session registry requires of an untrusted absolute path. */
+function isSafeAbsolutePath(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 4_096
+    && isAbsolute(value) && String(redactSensitiveText(value)) === value;
+}
+
+/**
+ * Claude's per-project memory directory for this task, or undefined when the
+ * reported transcript path is not this project's session transcript.
+ *
+ * `transcript_path` is untrusted hook input, so the shape is checked rather
+ * than trusted: it must be `<…>/.claude/projects/<slug>/<session>.jsonl` whose
+ * `<slug>` is the one Claude derives from this task's cwd. That rejects a
+ * subagent transcript (`<slug>/<session>/subagents/agent-*.jsonl`, which would
+ * otherwise freeze a bogus root) and any path naming another project, a home
+ * directory, or somewhere inside the repository.
+ */
+export function memoryRootFor(transcriptPath: string | undefined, cwd: string): string | undefined {
+  if (!transcriptPath || !cwd) return undefined;
+  const sessionDir = dirname(transcriptPath);
+  const projectsDir = dirname(sessionDir);
+  if (basename(projectsDir) !== "projects" || basename(dirname(projectsDir)) !== ".claude") return undefined;
+  if (basename(sessionDir) !== cwd.replaceAll("/", "-")) return undefined;
+  return join(sessionDir, "memory");
+}
+
+/**
+ * The directories outside the task cwd that the Worker may still write: its own
+ * per-session scratchpad, and Claude's per-project memory directory.
+ */
+export function writeRootsOf(record: { scratchpadDir?: string; transcriptPath?: string; handle?: { cwd: string } }): string[] {
+  const roots: string[] = [];
+  if (record.scratchpadDir) roots.push(record.scratchpadDir);
+  const memory = memoryRootFor(record.transcriptPath, record.handle?.cwd ?? "");
+  if (memory) roots.push(memory);
+  return roots;
+}
+
 export function attachCommand(handle: Pick<WorkerHandle, "tmuxSocket" | "sessionName">): string {
   const target = shellQuote(handle.sessionName ?? "");
   return handle.tmuxSocket ? `tmux -S ${shellQuote(handle.tmuxSocket)} attach -t ${target}` : `tmux attach -t ${target}`;