killeros 2.0.3 → 2.0.5

package/CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [2.0.5] - 2026-08-11
+
+### Added
+
+- Added shuffled session-stable suggestions to the empty three-line prompt editor.
+
+### Fixed
+
+- Preserved complete UTF-8 characters in truncated `/init` evidence and chunked lifecycle-hook output, and kept filesystem-root paths visible in notification titles.
+- Kept the startup-tip shuffle deck across session rebinds so every tip appears before the bank repeats.
+- Rejected matchers on `agent_settled` lifecycle hooks instead of silently bypassing their tool-name guard.
+- Made the goal update status schema compatible with Google models while preserving strict completion and blocking values.
+- Kept multiline custom-answer drafts within tiny terminal row limits by rendering a clipped single-line preview.
+- Preserved existing spaces and tabs after the cursor when applying slash-command autocomplete.
+- Made `/init` abort safely when Git ignore inspection fails or returns untrusted output, preventing ignored files from entering model evidence.
+- Wrapped long interactive questions to the current terminal width while keeping the question UI within the terminal height.
+- Made `/goal pause` and `/goal clear` save terminal state before immediately stopping active goal work.
+- Kept failed goal edits and replacements visible and fail-closed without restarting a stale objective.
+- Required one durable blocker key on three consecutive goal turns before a goal can be marked blocked.
+
+## [2.0.4] - 2026-08-10
+
+### Changed
+
+- Rebuilt `/init` around a packaged four-section guideline-synthesis workflow that preserves compatible root policy without requiring an external skill.
+- Removed live blue slash-command coloring while retaining slash autocomplete, the framed multiline editor, and Shift+Enter.
+
+### Fixed
+
+- Prevented `/init` from reading Git-ignored files, known secrets, private keys, linked or non-regular files, other guidance, dependencies, and files outside its frozen evidence map.
+- Protected root `AGENTS.md` from concurrent replacement and reported incompatible policy conflicts without writing.
+- Made `/clear` confirm before aborting active work, wait for settlement, and then start the new session.
+- Preserved explicit Responses API verbosity and reasoning-summary settings while applying concise defaults only to absent fields.
+- Cancelled lifecycle hook process trees with bounded cleanup when Pi aborts the parent request.
+- Kept `/init` middleware from freezing shared tool input and preserved custom editors installed by other extensions.
+- Removed private Pi editor-state access in favor of public rendering contracts.
+
 ## [2.0.3] - 2026-08-09
 
 ### Added

package/Killeros.ts

@@ -15,10 +15,12 @@ import { createGoalRuntime, createInitRuntime } from "./killeros/runtime.ts";
 import { registerShellUi } from "./killeros/shell-ui.ts";
 import { registerVariants } from "./killeros/variants.ts";
 
-export { CONCISE_SYSTEM_PROMPT, isConcisedEnabled } from "./killeros/concise.ts";
+export { CONCISE_SYSTEM_PROMPT, isConciseEnabled, isConcisedEnabled } from "./killeros/concise.ts";
 export { contextPercentRemaining, formatCost, formatContextProgress } from "./killeros/footer.ts";
 export { executeHook } from "./killeros/hooks.ts";
-export { INIT_WORKFLOW_PROMPT, writeInitAgentsFile } from "./killeros/init.ts";
+export { INIT_WORKFLOW_PROMPT } from "./killeros/init.ts";
+export { buildInitEvidence, listInitEvidence, readInitEvidence } from "./killeros/init-evidence.ts";
+export { captureInitTargetBaseline, installInitAgentsFile, validateGeneratedGuidance, writeInitAgentsFile } from "./killeros/init-target.ts";
 
 export interface KillerosOptions {
   completionNotifications?: CompletionNotificationDependencies;

package/README.md

@@ -31,7 +31,7 @@ pi install git:github.com/KyrosHendrix/pi-KillerOS
 Pin an install to a release:
 
 ```bash
-pi install git:github.com/KyrosHendrix/pi-KillerOS@v2.0.3
+pi install git:github.com/KyrosHendrix/pi-KillerOS@v2.0.5
 ```
 
 Add `-l` to either command for a project-only install. Restart Pi after installing.
@@ -41,17 +41,17 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 - 52-column Compact startup card with inline version, polished model/provider identity, adjacent `/model`, directory, conditional Git branch, and a shuffled session-stable tip
 - Cohesive dark theme with coral accents and neutral tool-call containers across pending, success, and error states
 - Animated orange 12-frame activity glyph loop at 120 ms per frame, with orange shuffled Claude-adjacent verbs changing every 2.5 seconds, a gray `(esc to interrupt · thinking)` status with bold `esc`, and a quiet hidden-thinking label
-- Framed multiline editor with Shift+Enter support and live command-blue highlighting for recognized slash command prefixes
+- Full-width framed multiline editor with a shuffled session-stable empty-state suggestion, Shift+Enter support, and slash-command autocomplete; KillerOS preserves an editor factory configured by another extension
 - Responsive footer with polished model/provider identity, plain-language context, and active goal state remaining; reasoning, Git branch, elapsed time, cost, and path cut down by available width
 - Pi-owned context compaction with active goals continuing from Pi's settled boundary after manual, threshold, and overflow compaction
 - Optional completion sounds after successful or failed settled requests, excluding manual aborts
 - `/variants` selector and direct reasoning-level arguments
-- Codex-style `/goal` with an interactive status/action panel, durable objectives, pause, resume, edit, confirmed panel clearing, automatic continuation, and explicit completion
-- Claude Code-style `/init` that scans the repository and generates a concise root `AGENTS.md` without setup questions
+- Codex-style `/goal` with an interactive status/action panel, durable objectives, immediate pause and clear cancellation, automatic continuation, explicit completion, and durable blocker audits
+- Automatic `/init` guideline synthesis with a frozen safe evidence map, protected existing policy, and the four packaged behavioral sections adapted from `writing-great-guidelines`
 - `question` tool with height-bounded option windows, configured Pi keybindings, live option/input progress, proposal previews, custom answers, history, cancellation, and compact expandable transcript rendering
 - Mid-prompt slash completion with current Pi `0.82.1` commands, extensions, prompts, and skills; paths, URLs, and invalid commands remain plain text
-- `/clear` for a confirmed new session, plus `/exit` for graceful shutdown
-- Concise system-prompt guidance without modifying completed assistant messages
+- Goal-aware `/clear` that confirms, aborts active work, waits for settlement, and starts a new session, plus `/exit` for graceful shutdown
+- Concise system-prompt guidance and supported native concise defaults that preserve explicit provider settings
 
 ## Commands
 
@@ -60,9 +60,9 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 /goal                     Open current goal status and valid actions
 /goal <objective>         Set an objective and start working
 /goal edit                Edit and reactivate the current goal
-/goal pause               Stop automatic continuation
+/goal pause               Stop the current goal turn and automatic continuation
 /goal resume              Resume automatic continuation
-/goal clear               Remove the current goal
+/goal clear               Stop current goal work and remove the goal
 /variants                 Open the reasoning-level selector
 /variants high            Set a reasoning level directly
 /notification             Configure the completion sound
@@ -70,9 +70,13 @@ Add `-l` to either command for a project-only install. Restart Pi after installi
 /exit                     Quit Pi gracefully
 ```
 
-`/goal` requires a saved session in TUI or RPC mode. Goal state is stored in versioned session entries on the active branch and restored after reload, resume, fork, or tree navigation. Active goals inject their unchanged objective every turn and continue one settled turn at a time. The model must use KillerOS’s private goal tool to mark verified completion or a blocker repeated across at least three goal turns; final prose alone does not end the loop. Aborted turns, provider failures, and continuation failures pause safely. Replacing unfinished work requires confirmation, and `/goal edit` requires TUI mode.
+`/goal` requires a saved session in TUI or RPC mode. Goal state is stored in versioned session entries on the active branch and restored after reload, resume, fork, or tree navigation. Active goals inject their unchanged objective every turn and continue one settled turn at a time. The model must use KillerOS’s private goal tool to mark verified completion. Blocking requires one stable lowercase blocker key recorded on three consecutive goal turns; a changed key, skipped turn, resume, or edit resets the streak. Final prose alone does not end the loop.
 
-`/init` builds a bounded project map, reads high-value manifests, documentation, and CI configuration, and lets the active model inspect additional implementation files before generating root `AGENTS.md`. Existing `AGENTS.md` and `CLAUDE.md` content is intentionally excluded so stale guidance is not inherited. The command asks no setup questions, starts no second model process, writes only `AGENTS.md`, and reloads Pi resources when finished.
+`/goal pause` and `/goal clear` save paused or cleared state before aborting current goal work, so settlement cannot restart it. Aborted turns, provider failures, and continuation failures otherwise pause safely. Failed edit and replacement writes dispatch no edited objective; an active prior objective pauses fail-closed, while inactive durable state remains unchanged. Replacing unfinished work requires confirmation, and `/goal edit` requires TUI mode.
+
+`/init` freezes a safe project-file map and exposes only dedicated read and list operations while it generates root `AGENTS.md`. Git-ignored files, known secret paths, private-key formats, other guidance, dependencies, links, non-regular files, and files outside that map are unavailable. Existing root `AGENTS.md` is separate protected policy: compatible rules are preserved, a real policy conflict leaves it unchanged with a reason, and any concurrent target change aborts installation without replacing the newer file.
+
+The generated file uses the four behavioral sections adapted from `writing-great-guidelines`; no external skill installation is required. `/init` asks no setup questions, starts no second model process, writes no other file, and reloads Pi resources only after a successful write.
 
 Supported reasoning levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. KillerOS limits choices to levels supported by the current model.
 
@@ -90,7 +94,7 @@ Manual `/compact` aborts the current goal turn before summarization, so KillerOS
 
 For trusted projects, KillerOS loads `AGENTS.local.md` after Pi's shared repository context. A one-line `@path` or `@~/path` file imports personal guidance from another location.
 
-Lifecycle hooks are loaded from `.pi/killeros-hooks.json` at session start. Supported event keys are `tool_call`, `tool_result`, and `agent_settled`; matchers are JavaScript regular expressions over Pi tool names. Hook commands run from the repository root with `KILLEROS_EVENT`, `KILLEROS_TOOL`, and `KILLEROS_PAYLOAD` environment variables. Failed `tool_call` hooks block the tool, while later-event failures notify the user.
+Lifecycle hooks are loaded from `.pi/killeros-hooks.json` at session start. Supported event keys are `tool_call`, `tool_result`, and `agent_settled`. Optional matchers are JavaScript regular expressions over Pi tool names, so they are valid only for `tool_call` and `tool_result`; KillerOS rejects an `agent_settled` hook that defines a matcher. Hook commands run from the repository root with `KILLEROS_EVENT`, `KILLEROS_TOOL`, and `KILLEROS_PAYLOAD` environment variables. Failed `tool_call` hooks block the tool, while later-event failures notify the user. Aborting the parent request stops the hook process tree with bounded graceful and forced cleanup without reporting cancellation as a hook failure.
 
 ## Behavior by mode
 

package/killeros/commands.ts

@@ -8,8 +8,9 @@ async function confirmNewSession(ctx: ExtensionCommandContext): Promise<boolean>
 
 export function registerAliases(pi: ExtensionAPI): void {
   const startNewSession = async (_args: string, ctx: ExtensionCommandContext): Promise<void> => {
-    await ctx.waitForIdle();
     if (!await confirmNewSession(ctx)) return;
+    if (!ctx.isIdle()) ctx.abort();
+    await ctx.waitForIdle();
     await ctx.newSession();
   };
   pi.registerCommand("clear", { description: "Start a new session after confirmation", handler: startNewSession });
@@ -54,13 +55,6 @@ const BUILTIN_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
   { name: "quit", description: "Quit Pi" },
 ];
 
-export function availableCommandNames(pi: ExtensionAPI): ReadonlySet<string> {
-  return new Set([
-    ...BUILTIN_COMMANDS.map((command) => command.name),
-    ...pi.getCommands().map((command) => command.name),
-  ]);
-}
-
 const COMMAND_SYNTAX_HINTS: Readonly<Record<string, string>> = {
   goal: "/goal [objective|clear|edit|pause|resume]",
   variants: "/variants [level]",
@@ -156,12 +150,11 @@ export function registerSlashAutocomplete(pi: ExtensionAPI): void {
         usage.set(tagged.killerosCommand, (usage.get(tagged.killerosCommand) ?? 0) + 1);
         const line = lines[cursorLine] ?? "";
         const beforeCursor = line.slice(0, cursorCol);
-        let afterCursor = line.slice(cursorCol);
+        const afterCursor = line.slice(cursorCol);
         const match = beforeCursor.match(/(?:^|[ \t])\/([^\s/]*)$/);
         if (!match || match.index === undefined) return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
         const slashIndex = match.index + (match[0].startsWith("/") ? 0 : 1);
         const newBefore = beforeCursor.slice(0, slashIndex) + item.value;
-        if (item.value.endsWith(" ") && afterCursor.startsWith(" ")) afterCursor = afterCursor.trimStart();
         const nextLines = [...lines];
         nextLines[cursorLine] = newBefore + afterCursor;
         return { lines: nextLines, cursorLine, cursorCol: newBefore.length };

package/killeros/concise.ts

@@ -41,22 +41,26 @@ function applyConciseModelSettings(payload: unknown, api: unknown, modelId: unkn
   const supportsVerbosity = api === "openai-codex-responses"
     || api === "openai-responses" && typeof modelId === "string" && /^gpt-5(?:[.-]|$)/u.test(modelId);
   let updated = payload;
-  if (supportsVerbosity) {
-    updated = {
-      ...updated,
-      text: { ...(isRecord(payload.text) ? payload.text : {}), verbosity: "low" },
-    };
+  const text = isRecord(payload.text) ? payload.text : undefined;
+  if (supportsVerbosity && !Object.hasOwn(text ?? {}, "verbosity")) {
+    updated = { ...updated, text: { ...(text ?? {}), verbosity: "low" } };
   }
-  if (supportsSummary && isRecord(payload.reasoning)) {
-    updated = { ...updated, reasoning: { ...payload.reasoning, summary: "concise" } };
+  const reasoning = isRecord(payload.reasoning) ? payload.reasoning : undefined;
+  if (supportsSummary && reasoning && !Object.hasOwn(reasoning, "summary")) {
+    updated = { ...updated, reasoning: { ...reasoning, summary: "concise" } };
   }
   return updated;
 }
 
-export function isConcisedEnabled(): boolean {
+export function isConciseEnabled(): boolean {
   return true;
 }
 
+/** @deprecated Use isConciseEnabled instead. */
+export function isConcisedEnabled(): boolean {
+  return isConciseEnabled();
+}
+
 export function registerConcisePrompt(pi: ExtensionAPI): void {
   pi.on("before_agent_start", (event) => ({
     systemPrompt: `${event.systemPrompt}\n\n${CONCISE_SYSTEM_PROMPT}`,

package/killeros/goals.ts

@@ -1,20 +1,20 @@
+import { StringEnum } from "@earendil-works/pi-ai";
 import { type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, type ThemeColor } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { MAX_NODE_TIMER_MS } from "./limits.ts";
 import { BoundedText } from "./bounded-text.ts";
-import { CONCISE_SYSTEM_PROMPT } from "./concise.ts";
 import { formatTime, formatTokens } from "./display.ts";
 import { reportError } from "./errors.ts";
 import { resolvePersonalInstructions } from "./personal-instructions.ts";
-import type { GoalRuntime, GoalState, GoalStatus, InitRuntime } from "./runtime.ts";
+import type { GoalBlockerAudit, GoalRuntime, GoalState, GoalStatus, InitRuntime } from "./runtime.ts";
 
 const GOAL_ENTRY_TYPE = "killeros-goal";
 const GOAL_CONTINUATION_TYPE = "killeros-goal-continuation";
 const GOAL_OBJECTIVE_LIMIT = 4_000;
 const GOAL_VERSION = 1;
 
-type GoalEntryEvent = "set" | "replace" | "edit" | "turn" | "pause" | "resume" | "blocked" | "complete" | "error" | "clear" | "checkpoint";
+type GoalEntryEvent = "set" | "replace" | "edit" | "turn" | "pause" | "resume" | "blocked" | "complete" | "error" | "clear" | "checkpoint" | "blocker-audit";
 interface GoalEntryData {
   version: 1;
   event: GoalEntryEvent;
@@ -24,6 +24,7 @@ interface GoalEntryData {
 interface GoalTransitionOptions {
   resetBlockedAudit?: boolean;
   resumeAfterManualCompaction?: true;
+  blockerAudit?: GoalBlockerAudit;
 }
 
 interface RestoredGoalState {
@@ -32,7 +33,7 @@ interface RestoredGoalState {
 }
 
 const GoalUpdateParams = Type.Object({
-  status: Type.Union([Type.Literal("complete"), Type.Literal("blocked")], {
+  status: StringEnum(["complete", "blocked"] as const, {
     description: "Mark the active goal complete or blocked",
   }),
   evidence: Type.String({
@@ -40,11 +41,19 @@ const GoalUpdateParams = Type.Object({
     maxLength: 2_000,
     description: "Concise evidence that the objective is complete, or the repeated blocker and attempted workarounds",
   }),
+  blockerKey: Type.Optional(Type.String({
+    minLength: 1,
+    maxLength: 120,
+    pattern: "^[a-z0-9][a-z0-9._-]{0,119}$",
+    description: "Stable lowercase key identifying the repeated blocker",
+  })),
 });
 
 interface GoalUpdateDetails {
-  status: "complete" | "blocked";
+  status: "complete" | "blocked" | "blocker-audit";
   evidence: string;
+  blockerKey?: string;
+  streak?: number;
 }
 
 function isGoalStatus(value: unknown): value is GoalStatus {
@@ -55,6 +64,17 @@ function finiteNonNegative(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
 
+function isGoalBlockerAudit(value: unknown, turns: number, status: GoalStatus): value is GoalBlockerAudit {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value as Partial<GoalBlockerAudit>;
+  if (typeof candidate.key !== "string"
+    || !/^[a-z0-9][a-z0-9._-]{0,119}$/u.test(candidate.key)
+    || !Number.isInteger(candidate.streak) || (candidate.streak ?? 0) < 1 || (candidate.streak ?? 0) > 3
+    || !Number.isInteger(candidate.lastTurn) || (candidate.lastTurn ?? 0) < 1 || (candidate.lastTurn ?? 0) > turns) return false;
+  if (status === "complete") return false;
+  return status === "blocked" ? candidate.streak === 3 : candidate.streak! < 3;
+}
+
 function parseGoalState(value: unknown): GoalState | undefined {
   if (!value || typeof value !== "object") return undefined;
   const candidate = value as Partial<GoalState>;
@@ -72,6 +92,7 @@ function parseGoalState(value: unknown): GoalState | undefined {
     || !finiteNonNegative(candidate.baselineTokens)
     || candidate.activeStartedAt !== undefined && !finiteNonNegative(candidate.activeStartedAt)
     || candidate.result !== undefined && typeof candidate.result !== "string"
+    || candidate.blockerAudit !== undefined && !isGoalBlockerAudit(candidate.blockerAudit, candidate.turns!, candidate.status)
     || candidate.resumeAfterManualCompaction !== undefined && candidate.resumeAfterManualCompaction !== true
     || candidate.resumeAfterManualCompaction === true && candidate.status !== "paused") {
     return undefined;
@@ -90,6 +111,7 @@ function parseGoalState(value: unknown): GoalState | undefined {
     baselineTokens: candidate.baselineTokens,
     result: candidate.result,
     resumeAfterManualCompaction: candidate.resumeAfterManualCompaction,
+    blockerAudit: candidate.blockerAudit,
   };
 }
 
@@ -183,6 +205,7 @@ function transitionGoal(
     updatedAt: now,
     activeStartedAt: status === "active" ? now : undefined,
     blockedAuditStartTurn: options.resetBlockedAudit ? stopped.turns : stopped.blockedAuditStartTurn,
+    blockerAudit: options.resetBlockedAudit ? undefined : options.blockerAudit ?? stopped.blockerAudit,
     result,
     resumeAfterManualCompaction: options.resumeAfterManualCompaction,
   };
@@ -191,6 +214,24 @@ function transitionGoal(
   return next;
 }
 
+function clearGoalExecutionFlags(runtime: GoalRuntime): void {
+  runtime.continuationScheduled = false;
+  runtime.goalTurnInFlight = false;
+  runtime.agentEndObserved = false;
+  runtime.lastStopReason = undefined;
+  runtime.lastError = undefined;
+}
+
+async function stopGoalRun(runtime: GoalRuntime, ctx: ExtensionCommandContext, shouldStop: boolean): Promise<void> {
+  if (!shouldStop) return;
+  try {
+    ctx.abort();
+    await ctx.waitForIdle();
+  } finally {
+    clearGoalExecutionFlags(runtime);
+  }
+}
+
 function goalStatusLabel(status: GoalStatus): string {
   return `${status.charAt(0).toLocaleUpperCase()}${status.slice(1)}`;
 }
@@ -223,6 +264,7 @@ export function pauseGoalAfterFailure(
   ctx: ExtensionContext,
   reason: string,
   recoveryInstruction = "Run /goal resume after resolving the problem.",
+  notify = true,
 ): void {
   if (runtime.state?.status !== "active") return;
   try {
@@ -238,7 +280,7 @@ export function pauseGoalAfterFailure(
     runtime.continuationScheduled = false;
     runtime.requestRender?.();
   }
-  ctx.ui.notify(`Goal paused: ${reason}\n${recoveryInstruction}`, "error");
+  if (notify) ctx.ui.notify(`Goal paused: ${reason}\n${recoveryInstruction}`, "error");
 }
 
 function pauseGoalForPossibleManualCompaction(
@@ -304,6 +346,7 @@ function scheduleGoalContinuation(
     || runtime.continuationHeld
     || runtime.goalTurnInFlight
     || initState.active
+    || !ctx.isIdle()
     || ctx.hasPendingMessages()) return false;
   const current = runtime.state;
   runtime.continuationScheduled = true;
@@ -338,7 +381,7 @@ function goalInstructions(state: GoalState, heading: string): string {
     "Continue making concrete progress toward this unchanged objective. Re-check repository state and prior results instead of repeating work.",
     "Do not stop merely because one response is complete: KillerOS will start another goal turn while the goal remains active.",
     "Before declaring completion, audit every part of the objective and verify the relevant results. Then call killeros_goal_update with status complete and concise evidence.",
-    "Call killeros_goal_update with status blocked only when the same external impasse has prevented progress for three consecutive goal turns; name the blocker and attempted workarounds.",
+    "Call killeros_goal_update with status blocked and the same lowercase blockerKey on each turn where one external impasse persists; attempts one and two record the audit, and attempt three marks the goal blocked.",
     "Never use the goal tool to pause, resume, edit, replace, or clear the objective. Those transitions belong to the user.",
   ].join("\n");
 }
@@ -355,7 +398,6 @@ function goalContinuationMessage(state: GoalState, ctx: ExtensionContext): strin
       sections.push(`<personal_instructions source=${JSON.stringify(personal.source)}>\n${personal.content}\n</personal_instructions>`);
     }
   }
-  sections.push(CONCISE_SYSTEM_PROMPT);
   return sections.join("\n\n");
 }
 
@@ -400,7 +442,7 @@ export function registerGoal(
   pi.registerTool<typeof GoalUpdateParams, GoalUpdateDetails>({
     name: "killeros_goal_update",
     label: "Goal update",
-    description: "Mark the active KillerOS long-running goal complete after verification, or blocked after the same impasse persists for three consecutive goal turns.",
+    description: "Mark the active KillerOS long-running goal complete after verification, or record the same blocker key on three consecutive goal turns before blocking it.",
     parameters: GoalUpdateParams,
     executionMode: "sequential",
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -410,13 +452,40 @@ export function registerGoal(
       if (!state || state.status !== "active") throw new Error("There is no active KillerOS goal to update");
       const evidence = params.evidence.trim();
       if (!evidence) throw new Error("Goal evidence must not be empty");
-      if (params.status === "blocked" && state.turns - state.blockedAuditStartTurn < 3) {
-        throw new Error("A goal cannot be marked blocked before three goal turns in the current audit; keep working and audit the same blocker again");
+      if (params.status === "complete") {
+        transitionGoal(pi, runtime, "complete", "complete", evidence, { resetBlockedAudit: true });
+        return {
+          content: [{ type: "text", text: `Goal marked complete: ${evidence}` }],
+          details: { status: "complete", evidence },
+        };
       }
-      transitionGoal(pi, runtime, params.status, params.status, evidence);
+      if (!runtime.goalTurnInFlight) throw new Error("A blocker audit can only be recorded during an active KillerOS goal turn");
+      const blockerKey = params.blockerKey;
+      if (!blockerKey || !/^[a-z0-9][a-z0-9._-]{0,119}$/u.test(blockerKey)) {
+        throw new Error("A blocked goal update requires a stable lowercase blockerKey");
+      }
+      const previous = state.blockerAudit;
+      const sameTurn = previous?.key === blockerKey && previous.lastTurn === state.turns;
+      const consecutive = previous?.key === blockerKey && previous.lastTurn === state.turns - 1;
+      const streak = sameTurn ? previous.streak : consecutive ? previous.streak + 1 : 1;
+      const blockerAudit = { key: blockerKey, streak, lastTurn: state.turns };
+      if (streak < 3) {
+        const next: GoalState = {
+          ...state,
+          revision: state.revision + 1,
+          updatedAt: Date.now(),
+          blockerAudit,
+        };
+        persistGoalState(pi, runtime, "blocker-audit", next);
+        return {
+          content: [{ type: "text", text: `Blocker audit ${streak}/3 recorded; the goal remains active: ${evidence}` }],
+          details: { status: "blocker-audit", evidence, blockerKey, streak },
+        };
+      }
+      transitionGoal(pi, runtime, "blocked", "blocked", evidence, { blockerAudit });
       return {
-        content: [{ type: "text", text: `Goal marked ${params.status}: ${evidence}` }],
-        details: { status: params.status, evidence },
+        content: [{ type: "text", text: `Goal marked blocked: ${evidence}` }],
+        details: { status: "blocked", evidence, blockerKey, streak },
       };
     },
     renderCall(args, theme) {
@@ -425,7 +494,8 @@ export function registerGoal(
     renderResult(result, options, theme) {
       const details = result.details;
       if (!details) return new BoundedText(theme.fg("dim", "Goal updated"));
-      const text = `${theme.fg(details.status === "complete" ? "success" : "warning", details.status === "complete" ? "✓ Complete" : "! Blocked")}${theme.fg("dim", ` · ${details.evidence}`)}`;
+      const label = details.status === "complete" ? "✓ Complete" : details.status === "blocked" ? "! Blocked" : `! Blocker audit ${details.streak}/3`;
+      const text = `${theme.fg(details.status === "complete" ? "success" : "warning", label)}${theme.fg("dim", ` · ${details.evidence}`)}`;
       return new BoundedText(text, options.expanded ? undefined : 3);
     },
   });
@@ -546,10 +616,11 @@ export function registerGoal(
           ctx.ui.notify("No goal is set", "info");
           return;
         }
+        const shouldStopGoalRun = runtime.goalTurnInFlight || runtime.continuationScheduled;
+        let saved = false;
         try {
           persistGoalState(pi, runtime, "clear", undefined);
-          runtime.continuationScheduled = false;
-          ctx.ui.notify("Goal cleared", "info");
+          saved = true;
         } catch (error) {
           if (runtime.state?.status === "active") {
             pauseGoalAfterFailure(
@@ -558,11 +629,24 @@ export function registerGoal(
               ctx,
               `the requested clear could not be saved: ${error instanceof Error ? error.message : String(error)}`,
               "Automatic continuation is stopped. Retry /goal clear to remove the goal.",
+              false,
             );
           } else {
             reportError(ctx, "Goal could not be cleared", error);
+            return;
           }
         }
+        try {
+          await stopGoalRun(runtime, ctx, shouldStopGoalRun);
+        } catch (error) {
+          reportError(ctx, saved ? "Goal cleared, but the active goal turn could not be confirmed stopped" : "Goal paused, but the active goal turn could not be confirmed stopped", error);
+          return;
+        }
+        if (saved) {
+          ctx.ui.notify("Goal cleared", "info");
+        } else {
+          ctx.ui.notify("Goal paused: the requested clear could not be saved\nAutomatic continuation is stopped. Retry /goal clear to remove the goal.", "error");
+        }
         return;
       }
 
@@ -599,18 +683,34 @@ export function registerGoal(
           ctx.ui.notify(`Goal is ${runtime.state.status}; only an active goal can be paused`, "warning");
           return;
         }
+        const shouldStopGoalRun = runtime.goalTurnInFlight || runtime.continuationScheduled;
+        let saved = false;
+        let failureReason: string | undefined;
         try {
           transitionGoal(pi, runtime, "pause", "paused");
-          ctx.ui.notify("Goal paused. Run /goal resume to continue.", "info");
+          saved = true;
         } catch (error) {
+          failureReason = `the requested pause could not be saved: ${error instanceof Error ? error.message : String(error)}`;
           pauseGoalAfterFailure(
             pi,
             runtime,
             ctx,
-            `the requested pause could not be saved: ${error instanceof Error ? error.message : String(error)}`,
+            failureReason,
             "Automatic continuation is stopped. If session storage is still unavailable, retry /goal pause after it recovers.",
+            false,
           );
         }
+        try {
+          await stopGoalRun(runtime, ctx, shouldStopGoalRun);
+        } catch (error) {
+          reportError(ctx, "Goal paused, but the active goal turn could not be confirmed stopped", error);
+          return;
+        }
+        if (saved) {
+          ctx.ui.notify("Goal paused. Run /goal resume to continue.", "info");
+        } else {
+          ctx.ui.notify(`Goal paused: ${failureReason}\nAutomatic continuation is stopped. If session storage is still unavailable, retry /goal pause after it recovers.`, "error");
+        }
         return;
       }
 
@@ -689,6 +789,7 @@ export function registerGoal(
           updatedAt: now,
           activeStartedAt: now,
           blockedAuditStartTurn: current.turns,
+          blockerAudit: undefined,
           result: undefined,
           resumeAfterManualCompaction: undefined,
         };
@@ -697,13 +798,17 @@ export function registerGoal(
           runtime.continuationScheduled = false;
           if (scheduleGoalContinuation(pi, runtime, initState, ctx)) ctx.ui.notify("Goal updated and active", "info");
         } catch (error) {
-          pauseGoalAfterFailure(
-            pi,
-            runtime,
-            ctx,
-            `Goal could not be edited: ${error instanceof Error ? error.message : String(error)}`,
-            "Automatic continuation is stopped. Retry /goal edit after session storage recovers.",
-          );
+          if (runtime.state?.status === "active") {
+            pauseGoalAfterFailure(
+              pi,
+              runtime,
+              ctx,
+              `Goal could not be edited: ${error instanceof Error ? error.message : String(error)}`,
+              "Automatic continuation is stopped. Retry /goal edit after session storage recovers.",
+            );
+          } else {
+            reportError(ctx, "Goal could not be edited", error);
+          }
         }
         return;
       }
@@ -763,8 +868,19 @@ export function registerGoal(
           ctx.ui.notify("Goal active. KillerOS will continue until completion, a repeated blocker, or pause.", "info");
         }
       } catch (error) {
-        reportError(ctx, "Goal could not be started", error);
-        scheduleGoalContinuation(pi, runtime, initState, ctx);
+        if (!unfinished) {
+          reportError(ctx, "Goal could not be started", error);
+        } else if (runtime.state?.status === "active") {
+          pauseGoalAfterFailure(
+            pi,
+            runtime,
+            ctx,
+            `Goal could not be replaced: ${error instanceof Error ? error.message : String(error)}`,
+            "Automatic continuation is stopped. Retry replacement after session storage recovers.",
+          );
+        } else {
+          reportError(ctx, "Goal could not be replaced", error);
+        }
       }
   };
 
@@ -802,6 +918,8 @@ export function registerGoalSettlement(
     if (!wasGoalTurn || runtime.state?.status !== "active" || initState.active) {
       if (continuationWasScheduled && runtime.state?.status === "active" && !initState.active) {
         pauseGoalAfterFailure(pi, runtime, ctx, "the goal continuation ended before an agent turn started");
+      } else if (runtime.state?.status === "active" && !initState.active) {
+        scheduleGoalContinuation(pi, runtime, initState, ctx);
       }
       return;
     }