Merge pull request #22 from roodriigoooo/refactor/worker-spawn-policy

Refactor/worker spawn policy

Author: roodriigoooo

docs/architecture.md

@@ -17,12 +17,15 @@ Each module owns its data, its interface, and its tests. Adapters at the seam ta
 | Bundle Commands | `extensions/checkpoint-commands.ts` | `list` / `delete` support for saved bundles. |
 | Bundle Selector | `extensions/checkpoint-selector.ts` | Interactive accept/exclude before optional summarization. |
 | Loaded Artifact Context | `extensions/loaded-artifact-context.ts` | Mounted source slots, reference/full chip expansion, consume-on-use queue. |
-| Background Work | `extensions/background-work.ts` | Worker state transitions, protocol semantics, pre-flight task docs, synthetic status artifacts, heartbeat dedup. |
+| Worker Lifecycle | `extensions/worker-lifecycle.ts` | Pure status transitions and lifecycle selectors: review/respawn/harvest eligibility, dock-terminal age, and prune disposition. |
+| Background Work | `extensions/background-work.ts` | Protocol payload shaping, pre-flight task docs, synthetic status artifacts, and heartbeat artifact dedup. |
 | Worker Review | `extensions/worker-review.ts` | Shared Worker + Artifact projection: state, result artifact, summary, recommendations, and status-card text. |
 | Worker Conflicts | `extensions/worker-conflicts.ts` | Edited-file overlap detection across workers; warning text for dock, dashboard, and promote confirmation. |
 | Worker Verdict | `extensions/worker-verdict.ts` | Worker decision lifecycle: candidate ranking, verdict actions, decision-ledger context, and change-set promotion. |
+| Worker Change Review | `extensions/worker-change-review.ts` | One review operation over a deterministic change set: built-in diff, Hunk fallback, comment disposition, and worker-only comment delivery. It cannot promote or mount artifacts. |
+| Hunk Diff Review | `extensions/worker-diff-review.ts` | Hunk process adapter: availability, exact patch extraction, launch, comment harvesting, and comment formatting. |
 | Worker Commands | `extensions/worker-commands.ts` | `spawn` / `tell` / `delete` / `load` / `unload` / completion. |
-| Worker Store | `extensions/worker-store.ts` | Shared tmux session topology, `send-keys -l` stdin (single line) and `paste-buffer` (multiline), task doc write, session seeding. |
+| Worker Store | `extensions/worker-store.ts` | Shared tmux session topology, status-file locking/atomic transition persistence, `send-keys -l` stdin (single line) and `paste-buffer` (multiline), task doc write, session seeding. |
 | Worker Events | `extensions/worker-events.ts` | NDJSON append + tail + rotation. |
 | Worker Snapshot Cache | `extensions/worker-dock-cache.ts` | mtime-cached status/artifacts read, `fs.watch`, sticky recent-event ring. |
 | Worker Eviction | `extensions/worker-eviction.ts` | Dock idle-hide window, prune-after-hours sweep. |
@@ -31,6 +34,11 @@ Each module owns its data, its interface, and its tests. Adapters at the seam ta
 | Extension Surface | `extensions/docket.ts` (via `globalThis.__docket`) | `registerWorkerKind`, `listWorkerKinds`, `onWorkerEvent`. |
 | Navigator | `extensions/docket-navigator.ts` | View model, ranking, selection state, mode/source transitions. |
 | Command Router | `extensions/docket-command-router.ts` | Routes parsed intents to the modules above. |
+| Shared Session Runtime | `extensions/shared-session-runtime.ts` | Parent/worker-neutral registration: `/docket` routing, message rendering, mounted artifact expansion, checkpoint lifecycle, and session cleanup. |
+| Parent Runtime | `extensions/parent-runtime.ts` | Parent-only worker watch/dock startup and teardown. The parent owns cache refresh, reconciliation, harvest, tmux status, and dock animation. |
+| Worker Runtime | `extensions/worker-runtime.ts` | Worker-only guardrail/protocol registration plus heartbeat lifecycle. The worker owns protocol tools, nudges, shell fallback, event capture, and allowed child spawning. |
+| Docket Views | `extensions/docket-views/` | Artifact/file viewers, shared layout primitives, and router/verdict action type boundaries. Runtime state is not imported into views. |
+| Docket Keymap | `extensions/docket-keymap.ts` | Normalized physical-key bindings, conflict checking, and shared card/footer/help hint rendering for interactive views. |
 
 ## Worker lifecycle
 
@@ -42,6 +50,8 @@ Each module owns its data, its interface, and its tests. Adapters at the seam ta
 6. Worker calls `docket_done` / `docket_fail` → state goes terminal → row enters `ready` / `failed` until evicted (`worker.dockIdleHideMinutes`) or pruned (`worker.pruneAfterHours`). When the prune sweep removes a terminal worker that never got a verdict (its id is absent from the decision ledger), it records a `worker_evicted_unreviewed` event first so the debt is counted before the record is gone.
 7. If the worker *process* dies, `remain-on-exit` keeps the dead pane. The dock's harvest sweep (`isPaneHarvestCandidate` → `WorkerStore.harvestPaneTail`) captures the last 200 lines to `pane-tail.txt`, kills the window, and stamps `paneCapturedAt` on the status so the probe never repeats. The tail surfaces as a `terminal tail` artifact in review and as the last lines on the failed verdict card. Workers in a terminal state whose pane is still alive (a protocol `docket_fail` with pi still running) are left untouched so you can keep chatting with them.
 
+For a ready worker, the verdict card can open the deterministic change-set artifact directly or ask Hunk to annotate its exact patch. `Worker Change Review` owns the fallback to the built-in diff and comment send/copy/ignore handling. Only a successful send returns `comments-sent`; `Worker Verdict` then records the chat decision and advances the queue.
+
 ## Worker protocol
 
 One contract for every kind. The MD body of a kind extends the universal guardrails; it does not replace them.

docs/configuration.md

@@ -73,7 +73,6 @@ Evidence bundles are bundle-first: by default `/docket save` writes a determinis
 | `worker.pruneAfterHours` | 24 | auto-prune `ended` worker dirs after this many hours; 0 disables. |
 | `worker.tmuxStatusLine` | false | write a compact summary to `docket-workers`' `status-right`. |
 | `worker.captureTerminal` | false | enable `tmux pipe-pane` to `<worker-dir>/pane.log` per worker. |
-| `worker.autoRespawn` | false | reserved; today `/docket respawn` is manual. |
 | `worker.autoEmbedSummary` | false | when true, append a short summary (outcome + 1-line summary + up to 5 recommended bullets) to the parent session as a worker reaches `ready`. Default false keeps the parent JSONL fully manual — the inbox card still surfaces the ready worker; nothing is auto-injected. |
 | `worker.parentSeedPolicy` | `none` | default parent-seed policy for `/docket spawn` when neither `--seed`/`--fresh` nor the kind sets one. `"none"` (default) spawns fresh workers with no parent context; `"full"` seeds the worker with the parent session JSONL (reuses prompt cache prefix but inherits full parent context). Use as a project-wide escape hatch when most workers need parent context. |
 | `worker.guardrailsPath` | bundled | absolute or cwd-relative path to a guardrail file appended to every worker prompt. |
@@ -96,7 +95,7 @@ Bundled kinds (`default`, `scout`, `patcher`) live in `extensions/worker-kinds/`
 | `name` | — | required; kebab-case slug used by `--as` |
 | `description` | — | one-line shown in `/docket kinds` |
 | `model` | parent | optional model override (`provider/model` string) |
-| `thinking` | `medium` | `off` / `low` / `medium` / `high` |
+| `thinking` | parent/default | optional Pi thinking override: `off` / `minimal` / `low` / `medium` / `high` / `xhigh` |
 | `read_only` | false | when true, appendix tells the worker not to edit files |
 | `default_worktree` | true | spawn this kind in a detached worktree by default |
 | `parent_seed` | `none` | `none` for a fresh worker; `full` to seed the worker session with the parent's JSONL (reuses prompt cache prefix but inherits full parent context — use only when the worker needs it). Per-spawn `--seed`/`--fresh` flags override. |

extensions/background-work.ts

@@ -1,5 +1,6 @@
 import { gitSnapshotLabel } from "./git-context.js";
 import type { Artifact, GitSnapshot } from "./types.js";
+import { deriveWorkerLifecycleState, isPaneHarvestEligible } from "./worker-lifecycle.js";
 
 export type WorkerState = "starting" | "active" | "idle" | "needs_input" | "ready" | "failed" | "error" | "ended";
 export type WorkerDerivedState = "starting" | "thinking" | "stale" | "needs_input" | "ready_open_todos" | "ready" | "empty" | "failed" | "idle" | "reviewed";
@@ -88,6 +89,8 @@ export type WorkerStatus = {
 	createdAt: string;
 	updatedAt: string;
 	state: WorkerState;
+	/** Unique launch generation; prevents an old process-exit hook from changing a respawned worker. */
+	runToken?: string;
 	pid?: number;
 	sessionFile?: string;
 	model?: string;
@@ -423,22 +426,7 @@ export function workerQuestions(worker: WorkerStatus): WorkerQuestion[] {
 }
 
 export function deriveWorkerState(worker: WorkerStatus, now = Date.now()): WorkerDerivedState {
-	if (worker.state === "needs_input") return "needs_input";
-	// Reviewed workers stay dim until new protocol activity or parent input clears reviewedAt.
-	// Heartbeats do NOT clear it (a done worker still ticks updatedAt but should stay reviewed).
-	if (worker.reviewedAt && (worker.state === "ready" || worker.state === "ended" || worker.state === "failed" || worker.state === "error")) return "reviewed";
-	if (worker.state === "failed" || worker.state === "error") return "failed";
-	if (worker.state === "ready") return "ready";
-	if (worker.state === "ended") {
-		if ((worker.artifactCount ?? 0) === 0) return "empty";
-		return "ready";
-	}
-	const ageMs = now - Date.parse(worker.updatedAt);
-	if (Number.isFinite(ageMs) && ageMs > 90_000) return "stale";
-	if (worker.state === "active") return "thinking";
-	if (worker.state === "starting") return "starting";
-	if (worker.state === "idle") return "idle";
-	return "idle";
+	return deriveWorkerLifecycleState(worker, now);
 }
 
 export function workerStateRank(worker: WorkerStatus, now = Date.now()): number {
@@ -578,11 +566,9 @@ export function workerStatusArtifact(worker: WorkerStatus, now = Date.now()): Ar
 	};
 }
 
-const PANE_HARVEST_STATES: ReadonlySet<WorkerState> = new Set(["failed", "error", "ended"]);
-
 /** True when the parent's dock sweep should probe this worker's tmux pane for a post-mortem capture. */
 export function isPaneHarvestCandidate(worker: WorkerStatus): boolean {
-	return PANE_HARVEST_STATES.has(worker.state) && !worker.paneCapturedAt;
+	return isPaneHarvestEligible(worker);
 }
 
 export const PANE_TAIL_MAX_LINES = 200;

extensions/checkpoint-selector.ts

@@ -1,5 +1,6 @@
 import type { ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
-import { Box, Key, Text, matchesKey, truncateToWidth, type Component, type TUI } from "@mariozechner/pi-tui";
+import { Box, Text, truncateToWidth, type Component, type TUI } from "@mariozechner/pi-tui";
+import { createEvidenceBundleKeymap, formatKeyHints } from "./docket-keymap.js";
 import type { Artifact, ArtifactKind, CheckpointMode } from "./types.js";
 
 export type CheckpointSelectionState = {
@@ -86,18 +87,19 @@ class CheckpointSelectorView implements Component {
 		const selected = clampSelected(this.state.selected, this.artifacts);
 		this.state = selected === this.state.selected ? this.state : { ...this.state, selected };
 
-		if (matchesKey(data, Key.escape) || data === "q" || matchesKey(data, Key.ctrl("c"))) {
+		const action = createEvidenceBundleKeymap().resolve(data);
+		if (action === "close") {
 			this.done(null);
 			return;
 		}
-		if (data === "j" || matchesKey(data, Key.down)) this.state = { ...this.state, selected: clampSelected(selected + 1, this.artifacts) };
-		else if (data === "k" || matchesKey(data, Key.up)) this.state = { ...this.state, selected: Math.max(0, selected - 1) };
-		else if (data === "g") this.state = { ...this.state, selected: 0 };
-		else if (data === "G") this.state = { ...this.state, selected: Math.max(0, this.artifacts.length - 1) };
-		else if (data === " ") this.state = toggleCheckpointSelection(this.state);
-		else if (data === "a") this.state = selectAllCheckpointArtifacts(this.state);
-		else if (data === "n") this.state = selectNoCheckpointArtifacts(this.state);
-		else if (matchesKey(data, Key.enter)) {
+		if (action === "down") this.state = { ...this.state, selected: clampSelected(selected + 1, this.artifacts) };
+		else if (action === "up") this.state = { ...this.state, selected: Math.max(0, selected - 1) };
+		else if (action === "top") this.state = { ...this.state, selected: 0 };
+		else if (action === "bottom") this.state = { ...this.state, selected: Math.max(0, this.artifacts.length - 1) };
+		else if (action === "toggle") this.state = toggleCheckpointSelection(this.state);
+		else if (action === "all") this.state = selectAllCheckpointArtifacts(this.state);
+		else if (action === "none") this.state = selectNoCheckpointArtifacts(this.state);
+		else if (action === "save") {
 			const selectedArtifacts = selectedCheckpointArtifacts(this.artifacts, this.state);
 			if (selectedArtifacts.length === 0) this.message = "select at least one artifact or q cancel";
 			else this.done(selectedArtifacts);
@@ -124,7 +126,7 @@ class CheckpointSelectorView implements Component {
 		const muted = (s: string) => this.theme.fg("muted", s);
 		const warning = (s: string) => this.theme.fg("warning", s);
 		const stats = checkpointSelectionStats(this.artifacts, this.state);
-		const header = `${accent(this.theme.bold("docket · checkpoint"))} ${dim(this.mode)} ${dim("·")} ${stats.selected}/${stats.total} selected ${dim("·")} ~${stats.estimatedTokens} tok`;
+		const header = `${accent(this.theme.bold("docket · evidence bundle"))} ${dim(this.mode)} ${dim("·")} ${stats.selected}/${stats.total} selected ${dim("·")} ~${stats.estimatedTokens} tok`;
 		container.addChild(new Text(truncateToWidth(header, innerWidth - 2), 1, 0));
 
 		const windowSize = 14;
@@ -146,7 +148,7 @@ class CheckpointSelectorView implements Component {
 		for (let i = visible.length; i < windowSize; i++) container.addChild(new Text("", 1, 0));
 
 		if (this.message) container.addChild(new Text(warning(this.message), 1, 0));
-		else container.addChild(new Text(dim("space toggle · a all · n none · enter create · q cancel"), 1, 0));
+		else container.addChild(new Text(dim(formatKeyHints(createEvidenceBundleKeymap(), "footer")), 1, 0));
 
 		this.cachedLines = container.render(width);
 		this.cachedWidth = width;

extensions/docket-command-router.ts

@@ -13,7 +13,7 @@ import type { Artifact, CheckpointIndexEntry } from "./types.js";
 import type { WorkerCommands } from "./worker-commands.js";
 import type { WorkerStore } from "./worker-store.js";
 import { findVerdictWorker, runWorkerVerdict, runWorkerVerdictQueue, type DocketVerdictAction } from "./worker-verdict.js";
-import type { HunkReviewAction, HunkReviewComment, HunkReviewResult } from "./worker-diff-review.js";
+import type { WorkerChangeReviewOutcome, WorkerChangeReviewPreference } from "./worker-change-review.js";
 
 export type DocketBrowserAction = { action: "inspect" | "openFile" | "promoteWorker" | "reference" | "injectFull" | "copy" | "save" | "search" | "tellWorker" | "verdict"; artifact?: Artifact };
 
@@ -64,8 +64,7 @@ export type DocketCommandRouterDeps = {
 	markWorkerUnloaded(worker: WorkerStatus): void;
 	markAllWorkersUnloaded(): void;
 	promoteWorkerChangeSet(artifact: Artifact): Promise<boolean>;
-	reviewWorkerChangeSetInHunk(worker: WorkerStatus, changeSet: Artifact): Promise<HunkReviewResult>;
-	chooseHunkReviewAction(worker: WorkerStatus, comments: HunkReviewComment[]): Promise<HunkReviewAction>;
+	reviewWorkerChangeSet(worker: WorkerStatus, changeSet: Artifact, options: { preferred: WorkerChangeReviewPreference }): Promise<WorkerChangeReviewOutcome>;
 	applyWorkerState(state: "needs_input" | "ready" | "failed", text?: string): Promise<void>;
 	createCheckpoint(options: CheckpointCreateOptions): Promise<void>;
 	createHandoffCheckpoint(): Promise<void>;

extensions/docket-config.ts

@@ -20,8 +20,6 @@ export type DocketWorkerConfig = {
 	tmuxStatusLine?: boolean;
 	/** When true, every spawned worker also runs tmux pipe-pane to <worker-dir>/pane.log for post-hoc debug. */
 	captureTerminal?: boolean;
-	/** When true, /docket offers to re-window orphan workers when the shared tmux session is gone but their dirs are still live. */
-	autoRespawn?: boolean;
 	/** Default parent-seed policy when neither `--seed`/`--fresh` nor the kind sets one. `"none"` (default) spawns fresh workers; `"full"` seeds the worker with the parent session JSONL. */
 	parentSeedPolicy?: "full" | "none";
 	/** When true, a short summary message is appended to the parent session when a worker reaches ready. Default false: nothing enters the parent JSONL automatically — the inbox card still surfaces the ready worker. */
@@ -58,7 +56,6 @@ export const DEFAULT_CONFIG: DocketConfig = {
 		maxSpawnDepth: 2,
 		tmuxStatusLine: false,
 		captureTerminal: false,
-		autoRespawn: false,
 		autoEmbedSummary: false,
 		parentSeedPolicy: "none",
 	},