@gavin-hu/my-pi-agent 0.11.4 → 0.13.0

package/extensions/goal/clarify.ts

@@ -1,24 +1,24 @@
 /**
- * Host orchestration for the goal comprehension step: the nested clarifier
- * calls, their cancellable TUI loaders, the in-command questionnaire, and the
- * confirm/edit dialog.
+ * Host orchestration for the goal comprehension step: the clarifier call, its
+ * cancellable TUI loader, the in-command questionnaire, and the confirm/edit
+ * dialog.
  *
- * The loop's target is understanding what the user wants. The first call asks
- * the model whether it understands the goal and, if not, what it needs to know;
- * the command asks those questions through host dialogs; a second call folds the
- * answers into the final restatement; the editor lets the user confirm or
- * correct it. The flow never throws and never half-applies: a failed,
- * timed-out, cancelled, or unusable comprehension falls back to the text the
- * user typed, and a dismissed dialog cancels the whole command.
+ * The loop's target is understanding what the user wants. One call asks the
+ * model whether it understands the goal and, when it cannot yet, what it needs
+ * to know; the command asks those questions through host dialogs and carries
+ * the answers into the editor, where the user confirms or corrects the goal.
+ * The flow never throws and never half-applies: a failed, timed-out, cancelled,
+ * or unusable comprehension falls back to the text the user typed, and a
+ * dismissed dialog cancels the whole command.
  */
 
 import { BorderedLoader, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { UserMessage } from "@earendil-works/pi-ai";
 import { sanitizeLine } from "../../lib/format.ts";
 import { type Clarification, type ClarifyAnswer, type ClarifyQuestion, parseClarification } from "./clarify-parse.ts";
-import { buildClarifyMessages, buildRefineMessages } from "./clarify-prompt.ts";
+import { buildClarifyMessages } from "./clarify-prompt.ts";
 
-/** Bound on each clarifier model call, in milliseconds. */
+/** Bound on the clarifier model call, in milliseconds. */
 const CLARIFY_TIMEOUT_MS = 30_000;
 
 /** The slice of the context the clarify step reads. */
@@ -27,9 +27,6 @@ export type ClarifyContext = Pick<ExtensionContext, "mode" | "ui" | "signal" | "
 /** Loader text shown while the comprehension call runs. */
 const LOADER_MESSAGE = "Understanding goal…";
 
-/** Loader text shown while the goal is restated from the answers. */
-const REFINE_LOADER_MESSAGE = "Updating the goal…";
-
 /** The confirm/edit dialog title, reading as a confirmation of understanding. */
 const EDITOR_TITLE = "Confirm the goal — Enter to save, Esc to cancel";
 
@@ -79,74 +76,54 @@ function assistantText(response: { content?: unknown }): string {
 	return parts.join("\n");
 }
 
-/** Runs a nested operation, optionally behind the TUI loader. */
-type CompleterRun = <T>(fn: (signal: AbortSignal | undefined) => Promise<T>) => Promise<T | undefined>;
-
-/** The context slice the completer needs. */
-type CompleterContext = Pick<ExtensionContext, "model" | "modelRegistry" | "signal">;
-
 /**
- * Build one clarifier caller.
+ * One clarifier model call, behind the TUI loader.
  *
- * `buildMessages` produces the request; the call runs through `run` (the loader
- * wrapper) with an `AbortController` aborted on timeout, on the session signal,
- * or when the loader is cancelled. Any throw becomes `undefined`, so a provider
- * failure never blocks the command.
+ * The call is aborted on timeout, on the session signal, or when the loader is
+ * cancelled, and any failure becomes `undefined` so a provider error never
+ * blocks the command. Nothing from the conversation is sent: the model must not
+ * invent scope the user did not state.
  */
-function createCompleter(
-	ctx: CompleterContext,
-	timeoutMs: number,
-	run: CompleterRun,
-	buildMessages: () => { systemPrompt: string; messages: UserMessage[] },
-): () => Promise<string | undefined> {
-	return async () => {
-		const model = ctx.model;
-		if (!model) return undefined;
-
-		const { systemPrompt, messages } = buildMessages();
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), timeoutMs);
-		const onAbort = () => controller.abort();
-		ctx.signal?.addEventListener("abort", onAbort, { once: true });
-		try {
-			return await run(async (signal) => {
-				if (signal) signal.addEventListener("abort", () => controller.abort(), { once: true });
-				const response = await ctx.modelRegistry.complete(
-					model,
-					{ systemPrompt, messages },
-					{ signal: controller.signal, cacheRetention: "none" },
-				);
-				if (response.stopReason === "aborted") return undefined;
-				return assistantText(response);
-			});
-		} catch {
-			return undefined;
-		} finally {
-			clearTimeout(timer);
-			ctx.signal?.removeEventListener("abort", onAbort);
-		}
-	};
-}
-
-/** Run one clarifier call behind its loader and return the raw reply. */
-async function completeOnce(
+async function askClarifier(
 	ctx: ClarifyContext,
-	loaderMessage: string,
 	buildMessages: () => { systemPrompt: string; messages: UserMessage[] },
 ): Promise<string | undefined> {
-	return createCompleter(ctx, CLARIFY_TIMEOUT_MS, (run) => withLoader(ctx, loaderMessage, run), buildMessages)();
+	const model = ctx.model;
+	if (!model) return undefined;
+
+	const { systemPrompt, messages } = buildMessages();
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), CLARIFY_TIMEOUT_MS);
+	const onAbort = () => controller.abort();
+	ctx.signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		return await withLoader(ctx, LOADER_MESSAGE, async (signal) => {
+			if (signal) signal.addEventListener("abort", () => controller.abort(), { once: true });
+			const response = await ctx.modelRegistry.complete(
+				model,
+				{ systemPrompt, messages },
+				{ signal: controller.signal, cacheRetention: "none" },
+			);
+			if (response.stopReason === "aborted") return undefined;
+			return assistantText(response);
+		});
+	} catch {
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+		ctx.signal?.removeEventListener("abort", onAbort);
+	}
 }
 
 /**
- * One comprehension call on the session model, parsed into a
- * {@link Clarification}.
+ * The comprehension call, parsed into a {@link Clarification}.
  *
  * Returns `undefined` when there is no dialog UI or no model, or when the call
  * fails, times out, is cancelled, or returns nothing usable.
  */
 export async function clarifyGoalPrompt(ctx: ClarifyContext, text: string): Promise<Clarification | undefined> {
 	if (!ctx.hasUI || !ctx.model) return undefined;
-	return parseClarification(await completeOnce(ctx, LOADER_MESSAGE, () => buildClarifyMessages(text)));
+	return parseClarification(await askClarifier(ctx, () => buildClarifyMessages(text)));
 }
 
 /**
@@ -155,7 +132,7 @@ export async function clarifyGoalPrompt(ctx: ClarifyContext, text: string): Prom
  * A question with options uses a selector; a free-form question uses a text
  * input. Resolves `undefined` when any dialog is dismissed, so the caller cancels
  * the whole command; an empty answer is skipped. The answer is sanitized to one
- * line, since it is folded into a model message and later the goal.
+ * line, since it is folded into the goal the editor holds.
  */
 async function askQuestions(
 	ctx: Pick<ClarifyContext, "ui">,
@@ -178,19 +155,15 @@ async function askQuestions(
 }
 
 /**
- * Fold the user's answers into the final restatement of the goal.
+ * Carry the answers into the editor as notes under the restatement.
  *
- * Returns `undefined` on any failure, so the caller falls back to the first
- * restatement.
+ * No model call rewrites the goal from the answers, so they are shown verbatim
+ * with the question that asked for them: the user folds them into the sentence
+ * or deletes them, and whatever the editor holds is what gets recorded.
  */
-async function refineWithAnswers(
-	ctx: ClarifyContext,
-	original: string,
-	goal: string,
-	answers: readonly ClarifyAnswer[],
-): Promise<string | undefined> {
-	const reply = await completeOnce(ctx, REFINE_LOADER_MESSAGE, () => buildRefineMessages(original, goal, answers));
-	return parseClarification(reply)?.goal || undefined;
+function withAnswers(goal: string, answers: readonly ClarifyAnswer[]): string {
+	if (answers.length === 0) return goal;
+	return [goal, "", ...answers.map((answer) => `Also: ${answer.question} → ${answer.answer}`)].join("\n");
 }
 
 /** Open the confirm/edit dialog, or cancel when it is dismissed. */
@@ -201,7 +174,7 @@ async function editOrCancel(ctx: ClarifyContext, prefill: string): Promise<GoalP
 
 /**
  * Run the understanding loop for `/goal <prompt>`: comprehend, ask what is
- * missing, re-comprehend, then let the user confirm or correct the goal.
+ * missing, then let the user confirm or correct the goal.
  *
  * Without a dialog UI or a model the typed text is used unchanged, so the
  * command never blocks on the loop in print or JSON mode. A failed comprehension
@@ -224,11 +197,7 @@ export async function prepareGoalPrompt(ctx: ClarifyContext, typed: string): Pro
 			ctx.ui.notify("Goal not set.", "info");
 			return { action: "cancel" };
 		}
-		if (answers.length > 0) {
-			const refined = await refineWithAnswers(ctx, typed, proposed, answers);
-			if (refined) proposed = refined;
-			else ctx.ui.notify("Could not update the goal from your answers; edit it below.", "info");
-		}
+		proposed = withAnswers(proposed, answers);
 	}
 	return editOrCancel(ctx, proposed);
 }

package/extensions/goal/commands.ts

@@ -23,23 +23,37 @@ import { GOAL_ENTRY_TYPE, type Goal } from "./types.ts";
 /** Title of the record-only edit dialog, spelling out both exits. */
 const EDIT_TITLE = "Goal — Enter to save, Esc to cancel";
 
-/** Completion values for the goal keywords: `set`/`edit`/`raw` take an argument. */
-const GOAL_COMPLETIONS = [
-	{ value: "set ", label: "set" },
-	{ value: "edit ", label: "edit" },
-	{ value: "raw ", label: "raw" },
-	{ value: "clear", label: "clear" },
-	{ value: "done", label: "done" },
-	{ value: "achieved", label: "achieved" },
-	{ value: "help", label: "help" },
-	{ value: "-h", label: "-h" },
-	{ value: "--help", label: "--help" },
+/**
+ * One reserved `/goal` verb: the word, what a bare occurrence means, and whether
+ * it takes the rest of the line as its argument.
+ */
+type GoalVerb =
+	| { word: string; kind: "usage" | "clear" | "done"; argument: "none" }
+	| { word: string; kind: "raw"; argument: "required" }
+	| { word: string; kind: "record"; argument: "required" | "optional" };
+
+/**
+ * The single list behind the parser, the completions, and the help text, so a
+ * new verb cannot land in one of them and be missing from another.
+ * `set`/`edit` share the `record` kind; the two words are interchangeable.
+ */
+export const GOAL_VERBS: readonly GoalVerb[] = [
+	{ word: "set", kind: "record", argument: "optional" },
+	{ word: "edit", kind: "record", argument: "optional" },
+	{ word: "raw", kind: "raw", argument: "required" },
+	{ word: "clear", kind: "clear", argument: "none" },
+	{ word: "done", kind: "done", argument: "none" },
+	{ word: "achieved", kind: "done", argument: "none" },
+	{ word: "help", kind: "usage", argument: "none" },
+	{ word: "-h", kind: "usage", argument: "none" },
+	{ word: "--help", kind: "usage", argument: "none" },
 ];
 
-/** `/goal set <text>` and `/goal edit <text>`: `text` is optional. */
-const RECORD_PATTERN = /^(set|edit)(?:\s+([\s\S]*))?$/i;
-/** `/goal raw <text>`: `text` is required. */
-const RAW_PATTERN = /^raw(?:\s+([\s\S]*))?$/i;
+/** Completion values: a verb that takes an argument completes with a space. */
+const GOAL_COMPLETIONS = GOAL_VERBS.map((verb) => ({
+	value: verb.argument === "none" ? verb.word : `${verb.word} `,
+	label: verb.word,
+}));
 
 /** One parsed `/goal` invocation. */
 export type GoalCommand =
@@ -55,30 +69,22 @@ export type GoalCommand =
 /**
  * Parse `/goal`'s argument into one command.
  *
- * Keywords match whole words, so `setfoo` and `edit-foo` are free-form prompts,
- * not malformed keywords. Only `help`/`clear`/`done`/`achieved` are reserved
- * without an argument; anything else is a prompt.
+ * Only the first word is looked up, so a keyword matches a whole word: `setfoo`
+ * and `edit-foo` are free-form prompts, not malformed keywords, and a verb that
+ * takes no argument leaves the whole line a prompt (`clear the cache`). Anything
+ * unlisted is a prompt.
  */
 export function parseGoalCommand(input: string): GoalCommand {
 	const text = input.trim();
 	if (!text) return { kind: "show" };
 
-	const keyword = text.toLowerCase();
-	if (keyword === "help" || keyword === "-h" || keyword === "--help") return { kind: "usage" };
-	if (keyword === "clear") return { kind: "clear" };
-	if (keyword === "done" || keyword === "achieved") return { kind: "done" };
-
-	const record = RECORD_PATTERN.exec(text);
-	if (record) {
-		const objective = (record[2] ?? "").trim();
-		return objective ? { kind: "record", text: objective } : { kind: "editor" };
-	}
-	const raw = RAW_PATTERN.exec(text);
-	if (raw) {
-		const objective = (raw[1] ?? "").trim();
-		return objective ? { kind: "raw", text: objective } : { kind: "usage" };
-	}
-	return { kind: "prompt", text };
+	const head = text.split(/\s+/, 1)[0] ?? "";
+	const rest = text.slice(head.length).trim();
+	const verb = GOAL_VERBS.find((candidate) => candidate.word === head.toLowerCase());
+	if (!verb) return { kind: "prompt", text };
+	if (verb.argument === "none") return rest ? { kind: "prompt", text } : { kind: verb.kind };
+	if (verb.kind === "raw") return rest ? { kind: "raw", text: rest } : { kind: "usage" };
+	return rest ? { kind: "record", text: rest } : { kind: "editor" };
 }
 
 /**
@@ -87,7 +93,7 @@ export function parseGoalCommand(input: string): GoalCommand {
  * once the prefix contains a space (or the start of the prompt does not look
  * like a keyword) the argument is left to the user.
  */
-function completeGoalArg(prefix: string): Array<{ value: string; label: string }> | null {
+export function completeGoalArg(prefix: string): Array<{ value: string; label: string }> | null {
 	const text = prefix.trimStart();
 	if (text.includes(" ")) return null;
 	const items = GOAL_COMPLETIONS.filter((item) => item.label.startsWith(text));

package/extensions/goal/format.ts

@@ -51,10 +51,18 @@ export function goalObjective(goal: Goal, theme: Theme): string {
 	return goal.status === "achieved" ? paint(theme, "faint", goal.objective) : paint(theme, "label", goal.objective);
 }
 
-/** Model-facing result text. */
-export function formatGoalText(goal: Goal | null): string {
+/**
+ * Model-facing result text. `openTodos` counts the todo items the branch still
+ * has open, so marking a goal achieved can point at work the list still holds.
+ */
+export function formatGoalText(goal: Goal | null, openTodos = 0): string {
 	if (goal === null) return "Goal cleared.";
-	if (goal.status === "achieved") return `Goal achieved: ${goal.objective}`;
+	if (goal.status === "achieved") {
+		const text = `Goal achieved: ${goal.objective}`;
+		if (openTodos <= 0) return text;
+		const items = openTodos === 1 ? "1 todo item is" : `${openTodos} todo items are`;
+		return `${text}\n${items} still open; close or clear the list if that work is done.`;
+	}
 	return `Goal: ${goal.objective}\nKeep this objective in mind as you work, and mark it achieved with the goal tool when it is done.`;
 }
 
@@ -72,7 +80,7 @@ export const GOAL_HELP = [
 	"Set a goal with /goal <what you want to accomplish> and start working on it.",
 	"/goal raw <prompt> records your words verbatim, without confirming them first.",
 	"/goal set <prompt> records the goal without starting work; /goal edit [<prompt>] changes it.",
-	"/goal done  ·  /goal clear  ·  /goal help",
+	"/goal done (or achieved)  ·  /goal clear  ·  /goal help (or -h / --help)",
 ].join("\n");
 
 /** Truncate an objective to `max` display columns, appending `…` when cut. */

package/extensions/goal/schema.ts

@@ -9,10 +9,14 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 import { sanitizeLine } from "../../lib/format.ts";
+import { MAX_GOAL_OBJECTIVE } from "../../lib/goal-state.ts";
 import { GOAL_ACTIONS, GOAL_STATUSES, type Goal, type GoalStatus } from "./types.ts";
 
-/** Maximum length of the objective. */
-export const MAX_OBJECTIVE = 2000;
+/**
+ * Maximum length of the objective. Owned by `lib/goal-state.ts`, so a reader of
+ * the published state applies the same limit as this validator.
+ */
+export const MAX_OBJECTIVE = MAX_GOAL_OBJECTIVE;
 
 const GoalStatusEnum = StringEnum(GOAL_STATUSES, {
 	description: 'Whether the goal is still being pursued. Defaults to "active".',

package/extensions/goal/tools.ts

@@ -11,6 +11,7 @@ import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { sanitizeLine } from "../../lib/format.ts";
 import { GOAL_TOOL } from "../../lib/tool-names.ts";
+import { lastTodos } from "../../lib/todo-state.ts";
 import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
 import { rejectionLine, reuseCallText, toolCallTitle } from "../../lib/tui/tool.ts";
 import { paint } from "../../lib/tui/tokens.ts";
@@ -18,7 +19,7 @@ import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { formatCallText, formatGoalText } from "./format.ts";
 import type { GoalRuntime } from "./runtime.ts";
 import { GoalParams, GoalResult, normalizeGoal, type GoalArgs } from "./schema.ts";
-import { GoalResult as GoalResultView } from "./tui.ts";
+import { GoalHeader } from "./tui.ts";
 import type { GoalAction, GoalDetails } from "./types.ts";
 
 export const TOOL_NAME = GOAL_TOOL;
@@ -45,13 +46,30 @@ function toStructuredContent(details: GoalDetails): Record<string, JsonValue> {
 	return content;
 }
 
+/**
+ * How many items the branch's todo list still has open.
+ *
+ * `todo` is the *how* to the goal's *what*, so completing one while the other
+ * still holds work is worth saying out loud. The list is read from the branch
+ * (`lib/todo-state.ts`), so no todo module is imported.
+ */
+function openTodoCount(entries: Iterable<unknown>): number {
+	return lastTodos(entries).filter((todo) => todo.status !== "completed").length;
+}
+
 /**
  * Build the tool result for one call. A rejected call (`error` set) carries the
  * unchanged goal so the model can retry, and is marked `isError`.
  */
-function goalResult(details: GoalDetails, error?: string) {
+function goalResult(details: GoalDetails, options: { error?: string; openTodos?: number } = {}) {
+	const { error, openTodos = 0 } = options;
 	return {
-		content: [{ type: "text" as const, text: error === undefined ? formatGoalText(details.goal) : `Error: ${error}` }],
+		content: [
+			{
+				type: "text" as const,
+				text: error === undefined ? formatGoalText(details.goal, openTodos) : `Error: ${error}`,
+			},
+		],
 		details,
 		structuredContent: toStructuredContent(details),
 		...(error === undefined ? {} : { isError: true as const }),
@@ -82,10 +100,14 @@ export function registerTools(pi: ExtensionAPI, runtime: GoalRuntime): void {
 				const goal = normalizeGoal(args);
 				const action = goal === null ? "clear" : goal.status === "achieved" ? "achieve" : "set";
 				runtime.setGoal(goal, ctx);
-				return goalResult({ goal, action });
+				const openTodos = action === "achieve" ? openTodoCount(ctx.sessionManager.getBranch()) : 0;
+				return goalResult({ goal, action }, { openTodos });
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
-				return goalResult({ goal: runtime.getGoal(), action: attemptedAction(args), error: message }, message);
+				return goalResult(
+					{ goal: runtime.getGoal(), action: attemptedAction(args), error: message },
+					{ error: message },
+				);
 			}
 		},
 
@@ -115,9 +137,7 @@ export function registerTools(pi: ExtensionAPI, runtime: GoalRuntime): void {
 				return text;
 			}
 			const view =
-				context.lastComponent instanceof GoalResultView
-					? context.lastComponent
-					: new GoalResultView(details.goal, theme);
+				context.lastComponent instanceof GoalHeader ? context.lastComponent : new GoalHeader(details.goal, theme);
 			view.update(details.goal, theme);
 			return view;
 		},

package/extensions/goal/tui.ts

@@ -44,7 +44,7 @@ export class GoalWidget implements Component {
 }
 
 /** Transcript result block: the status header, separated from the call line. */
-export class GoalResult implements Component {
+export class GoalHeader implements Component {
 	private goal: Goal;
 	private theme: Theme;
 

package/extensions/goal/types.ts

@@ -15,8 +15,12 @@ export const GOAL_ACTIONS = ["set", "achieve", "clear"] as const;
 
 export type GoalAction = (typeof GOAL_ACTIONS)[number];
 
-/** Custom-entry type used to persist a goal set outside the tool (the `/goal` command). */
-export const GOAL_ENTRY_TYPE = "goal";
+/**
+ * Custom-entry type used to persist a goal set outside the tool (the `/goal`
+ * command). Owned by `lib/goal-state.ts` because another extension's reader
+ * dispatches on it; re-exported here so goal's own modules keep one import.
+ */
+export { GOAL_ENTRY_TYPE } from "../../lib/goal-state.ts";
 
 /** How an achieved goal renders in the persistent widget. */
 export type AchievedStyle = "show" | "hide";

package/extensions/job/README.md

@@ -38,10 +38,11 @@ How the `job` call and its result look in the transcript — the call line as a
   killing, and clearing.
 - Reports finished jobs to the model at the start of the next turn, or — for
   jobs started with `wake: true` — by triggering one turn.
-- Kills session-owned jobs on shutdown so no process is left behind; start a
-  job with `detached: true` to keep it running and reattach next session. A
-  detached POSIX job points its own output straight at its log file, so it keeps
-  logging after this process ends.
+- Kills session-owned jobs on shutdown so no process is left behind; on POSIX,
+  start a job with `detached: true` to keep it running and reattach next session.
+  A detached job points its own output straight at its log file, so it keeps
+  logging after this process ends. Windows has neither a process group to leave
+  nor a shell `EXIT` trap, so it refuses the detach instead of faking one.
 
 ## Tool
 
@@ -53,7 +54,7 @@ How the `job` call and its result look in the transcript — the call line as a
 | `cwd` | Working directory (`start`); defaults to the session cwd. |
 | `label` | Short display label (`start`); defaults to the command. |
 | `wake` | Wake the agent with one triggered turn when it finishes (`start`). |
-| `detached` | Leave it running when the session ends (`start`). |
+| `detached` | Leave it running when the session ends (`start`); POSIX only, refused on Windows. |
 | `stdin` | Give the job a stdin pipe so `send` can write to it (`start`); not with `detached`. |
 | `id` | Job id such as `j1` (`status`/`logs`/`send`/`kill`/`wait`/`clear`). |
 | `lines` | Log lines to return (`logs`, 1–2000). |
@@ -191,7 +192,7 @@ document, project wins):
 | `enabled` | `true` | Track jobs at all. |
 | `showStatus` | `true` | Show the `▸ N` / `✗ N` status chips. |
 | `wakeOnFinish` | `false` | Wake the agent when any job finishes. |
-| `detachedByDefault` | `false` | Leave jobs running when the session ends. |
+| `detachedByDefault` | `false` | Leave jobs running when the session ends; inert on Windows. |
 | `maxJobs` | `20` | Finished jobs kept before the oldest are pruned. |
 | `maxLogLines` | `100` | Log lines returned by `logs`. |
 | `maxLogBytes` | `8388608` | Bytes a log segment may reach before it rotates to `<id>.log.1`; `0` keeps logs unbounded. |
@@ -214,8 +215,8 @@ rewritten.
 - **`unknown` still has no exit code on some paths.** A POSIX job is wrapped in
   an `EXIT` trap that writes `$?` to a per-job `.status` file, so a job
   reattached after its session died reports its real exit code. `exec cmd`
-  replaces the shell and bypasses the trap, and Windows has no equivalent, so
-  those jobs settle as `unknown`.
+  replaces the shell and bypasses the trap, and a Windows job has no equivalent,
+  so those settle as `unknown`.
 - **Another session's jobs are shown, but not managed here.** Records are merged
   from every session file so ids stay unique and a peer's job is not reaped, and
   `list`/`/jobs` show them tagged `peer` (a dead session's records are adopted
@@ -236,10 +237,13 @@ rewritten.
   keep appending to the moved inode, or lose everything. Its log therefore grows
   without the `maxLogBytes` cap; `logs` still reads a bounded tail, and the file
   can be emptied by hand.
-- **Windows is best-effort.** Tree-kill uses `taskkill /T`; POSIX uses process
-  groups. A detached job only escapes the parent process on POSIX, where its
-  shell writes the log directly; on Windows it keeps the parent pipe and is
-  captured only until the session ends.
+- **Windows cannot detach a job.** There is no process group to leave and no
+  shell `EXIT` trap, so `detached: true` is refused with the three alternatives
+  (`detached: false`, WSL, a `subagent`) rather than starting a job that would
+  die with the session while claiming to outlive it. `job.detachedByDefault` is
+  inert there instead of failing every start with a config set on another
+  machine, and `doctor` names both facts. Tree-kill is still `taskkill /T`, and a
+  job reported only after its process is gone settles as `unknown`.
 
 ## Non-goals
 

package/extensions/job/runtime.ts

@@ -127,6 +127,8 @@ export interface RuntimeOptions {
 	killTree?: KillTreeFn;
 	startToken?: StartTokenFn;
 	now?: () => number;
+	/** Platform seam: whether this is Windows. Defaults to the running platform. */
+	isWindows?: () => boolean;
 	/** Fixed config, for tests; production loads it per cwd. */
 	config?: JobsConfig;
 }
@@ -202,6 +204,7 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 	const killTree = options.killTree ?? defaultKillTree;
 	const startToken = options.startToken ?? defaultStartToken;
 	const now = options.now ?? (() => Date.now());
+	const isWindows = options.isWindows ?? (() => process.platform === "win32");
 
 	const jobs = new Map<string, Job>();
 	const handles = new Map<string, Handle>();
@@ -717,7 +720,20 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 		if (!config.enabled) throw new Error("jobs are disabled.");
 		ui.attach(ctx);
 		const wantsStdin = startOptions.stdin === true;
-		const detached = startOptions.detached ?? config.detachedByDefault;
+		// Windows has no process group to leave and no shell `EXIT` trap to record an
+		// exit code, so a job there cannot outlive the session: refusing an explicit
+		// detach is the honest answer, and it happens before any id is reserved.
+		// `detachedByDefault` stays inert instead of failing every start with a config
+		// the user set on another machine; `doctor` names that.
+		const windows = isWindows();
+		if (windows && startOptions.detached === true) {
+			throw new Error(
+				"A detached job cannot outlive the session on Windows: there is no process group to leave " +
+					"and no shell EXIT trap to record its exit code. Start it with `detached: false`, " +
+					"run it under WSL, or move the work into a `subagent`.",
+			);
+		}
+		const detached = windows ? false : (startOptions.detached ?? config.detachedByDefault);
 		// A detached job outlives this process, so a stdin pipe owned by this session
 		// would hand it EOF the moment the session ends; refuse instead of silently
 		// dropping the pipe (or the detach).
@@ -732,14 +748,15 @@ export function createJobsRuntime(options: RuntimeOptions = {}): JobsRuntime {
 		// so a peer that advanced the shared counter cannot hand us a live job's id.
 		const id = store.nextId(jobs.keys());
 		const logPath = store.logPath(id);
-		const statusPath = process.platform === "win32" ? null : store.statusPath(id);
-		// A detached POSIX job points its own output at the log, so it keeps logging
-		// and survives after this process ends; Windows keeps the parent pipe.
-		const detachOutput = detached && process.platform !== "win32";
+		// Only a POSIX shell has an `EXIT` trap to record a status, and only a detached
+		// job points its own output at the log so it keeps logging after this process
+		// ends (which on Windows is never: `detached` is false there).
+		const statusPath = windows ? null : store.statusPath(id);
+		const detachOutput = detached;
 
 		// Wrap the command so a POSIX shell records its exit status; the path travels
 		// in the environment so the shell never has to quote it.
-		const program = withExitTrap(startOptions.command, process.platform === "win32", detachOutput);
+		const program = withExitTrap(startOptions.command, windows, detachOutput);
 		const env: NodeJS.ProcessEnv = { ...process.env };
 		if (statusPath) env[STATUS_ENV] = statusPath;
 		if (detachOutput) env[LOG_ENV] = logPath;

package/extensions/job/status.ts

@@ -7,8 +7,10 @@
  * shell never has to quote it). A later session reads that file when it finds a
  * dead pid and reports `exited`/`failed` instead of `unknown`.
  *
- * Windows shells have no equivalent trap, so those jobs keep the old behavior:
- * a reattached job with no code stays `unknown`.
+ * Windows shells have no equivalent trap. A Windows job is never detached (the
+ * runtime refuses it), so the missing trap is not a second limitation: a job
+ * reported only after its process is gone still settles as `unknown`, which
+ * `doctor` names.
  */
 
 import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";