@deltafleet/goalkeeper 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to Goalkeeper are documented here.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] - 2026-05-18
+
+- Added `goalkeeper-close.mjs` so agents can shut down Goalkeeper sessions when a goal completes.
+- Added the `close` event type and `closed` event status.
+- Added shutdown instructions so Goalkeeper stops applying checkpoint-first recovery to unrelated questions after completion.
+
 ## [0.2.1] - 2026-05-18
 
 - Simplified public invocation copy to `Use goalkeeper for this goal.`

package/CONTRIBUTING.md

@@ -18,7 +18,7 @@ The project has one strong bias: keep the core small enough that agents will act
 - Background processes.
 - Runtime hooks into private host-agent internals.
 - Global databases or cross-project indexing.
-- Large abstractions around the five core helper scripts.
+- Large abstractions around the six core helper scripts.
 
 These may be useful later, but they should not enter the project without a clear real-world failure case.
 

package/README.ja.md

@@ -119,10 +119,14 @@ Goalkeeper は長いエージェント作業を単純なループにします。
   -> resume、handoff、compaction が疑われる後、agent は checkpoint.md を最初に読む
   -> checkpoint が薄ければ context-pack.md を読む
   -> 正確な証拠が必要なら events.jsonl または source file を確認する
+  -> goal が完了したら、agent が Goalkeeper セッションを閉じる
+  -> その後の無関係な質問には Goalkeeper recovery を適用しない
 ```
 
 これは会話 transcript の保存ではありません。作業状態の保存です。
 
+Goalkeeper は永遠に張り付くべきではありません。管理していた goal が完了したら、agent は最終結果を記録し、checkpoint を closed 状態にし、active session pointer を削除してから完了報告をします。
+
 ## あえて小さくしています
 
 このプロジェクトを大きくするのは簡単です。

package/README.ko.md

@@ -119,10 +119,14 @@ Goalkeeper는 긴 에이전트 작업을 단순한 루프로 바꿉니다.
   -> resume, handoff, compact 의심 이후 agent는 checkpoint.md를 먼저 읽는다
   -> checkpoint가 얇으면 context-pack.md를 읽는다
   -> 정확한 증거가 필요하면 events.jsonl이나 source file을 확인한다
+  -> goal이 끝나면 agent가 Goalkeeper 세션을 닫는다
+  -> 이후 관련 없는 일반 질문에는 Goalkeeper recovery가 붙지 않는다
 ```
 
 이것은 대화 transcript 저장이 아닙니다. 작업 상태 보존입니다.
 
+Goalkeeper가 영원히 붙어 있으면 안 됩니다. 관리하던 goal이 끝나면 agent가 최종 결과를 기록하고, checkpoint를 closed 상태로 표시하고, active session pointer를 제거한 뒤 완료 보고를 합니다.
+
 ## 일부러 작게 만들었습니다
 
 이 프로젝트를 크게 만드는 방법은 쉽습니다.

package/README.md

@@ -119,10 +119,14 @@ Long /goal begins
   -> after resume, handoff, or suspected compaction, the agent reads checkpoint.md first
   -> if the checkpoint is too thin, the agent reads context-pack.md
   -> if exact proof is needed, the agent checks events.jsonl or source files
+  -> when the goal is done, the agent closes the Goalkeeper session
+  -> later unrelated questions do not trigger Goalkeeper recovery
 ```
 
 This is not transcript storage. It is working-state preservation.
 
+Goalkeeper should not stay attached forever. A managed goal has a shutdown step: the agent records the final outcome, marks the checkpoint closed, and removes the active session pointer before giving the completion response.
+
 ## Why It Is Small On Purpose
 
 The obvious version of this project is too big:

package/README.zh-CN.md

@@ -119,10 +119,14 @@ Goalkeeper 把长时间 agent 工作变成一个简单循环：
   -> resume、handoff 或怀疑 compaction 后，agent 先读 checkpoint.md
   -> 如果 checkpoint 太薄，agent 再读 context-pack.md
   -> 如果需要精确证据，agent 检查 events.jsonl 或 source files
+  -> goal 完成后，agent 关闭 Goalkeeper session
+  -> 之后无关的一般问题不会触发 Goalkeeper recovery
 ```
 
 这不是保存对话 transcript。它保存的是工作状态。
 
+Goalkeeper 不应该一直附着在会话上。被管理的 goal 完成后，agent 会记录最终结果，把 checkpoint 标记为 closed，移除 active session pointer，然后再汇报完成。
+
 ## 为什么故意做得很小
 
 把这个项目做大很容易：

package/docs/ROADMAP.md

@@ -4,7 +4,7 @@
 
 Long-running agent goals need a small continuity layer outside the model context.
 
-Goalkeeper should stay boring: a short checkpoint, a medium-density context pack, an append-only event log, a turn-start helper, and a doctor check. It should not become a substitute context engine or a promise of perfect post-compact recovery.
+Goalkeeper should stay boring: a short checkpoint, a medium-density context pack, an append-only event log, a turn-start helper, a close helper, and a doctor check. It should not become a substitute context engine or a promise of perfect post-compact recovery.
 
 ## MVP
 
@@ -27,6 +27,7 @@ Core behavior:
 - read the context pack when the checkpoint is too thin to recover pre-compaction reasoning
 - append meaningful decisions, failures, verification, and handoff events
 - refresh the checkpoint when recoverable working state changes
+- close the active session when the managed goal completes so unrelated questions do not trigger recovery
 - run a read-only doctor before trusting a workspace for long work
 
 ## User-Facing Scope
@@ -37,6 +38,7 @@ Keep these scripts central:
 - `goalkeeper-turn-start.mjs`
 - `goalkeeper-append-event.mjs`
 - `goalkeeper-update-checkpoint.mjs`
+- `goalkeeper-close.mjs`
 - `goalkeeper-doctor.mjs`
 
 Keep this optional and maintainer-oriented:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deltafleet/goalkeeper",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A small Agent Skill for keeping long-running goals oriented across compaction, resumes, and handoffs.",
   "license": "MIT",
   "type": "module",
@@ -29,11 +29,13 @@
     "goalkeeper-append-event": "src/goalkeeper/scripts/goalkeeper-append-event.mjs",
     "goalkeeper-update-checkpoint": "src/goalkeeper/scripts/goalkeeper-update-checkpoint.mjs",
     "goalkeeper-doctor": "src/goalkeeper/scripts/goalkeeper-doctor.mjs",
+    "goalkeeper-close": "src/goalkeeper/scripts/goalkeeper-close.mjs",
     "codex-goalkeeper-init": "src/goalkeeper/scripts/goalkeeper-init.mjs",
     "codex-goalkeeper-turn-start": "src/goalkeeper/scripts/goalkeeper-turn-start.mjs",
     "codex-goalkeeper-append-event": "src/goalkeeper/scripts/goalkeeper-append-event.mjs",
     "codex-goalkeeper-update-checkpoint": "src/goalkeeper/scripts/goalkeeper-update-checkpoint.mjs",
-    "codex-goalkeeper-doctor": "src/goalkeeper/scripts/goalkeeper-doctor.mjs"
+    "codex-goalkeeper-doctor": "src/goalkeeper/scripts/goalkeeper-doctor.mjs",
+    "codex-goalkeeper-close": "src/goalkeeper/scripts/goalkeeper-close.mjs"
   },
   "files": [
     "src/goalkeeper",

package/src/goalkeeper/SKILL.md

@@ -17,6 +17,8 @@ When a user starts or continues a `/goal` in Claude Code, Codex, or another skil
 
 When a Goalkeeper-managed goal is already active, the first project-state action in a new assistant turn should be reading the active checkpoint, unless you have already read it in the same turn.
 
+Only treat Goalkeeper as active when `<workspace>/.goalkeeper/active-session` points to a live session or the user explicitly asks to resume a specific Goalkeeper session. If no active session pointer exists and the user asks an unrelated question, do not apply checkpoint-first recovery.
+
 This is stricter than waiting until you notice compaction. A compacted turn may not reliably expose the compaction marker to the model, so checkpoint-first is the practical recovery rule for long-running goals.
 
 Allowed before the checkpoint read:
@@ -113,6 +115,31 @@ Update Goalkeeper state when any of these change:
 Append the event first, then update the session's `checkpoint.md` when the event changes the current working state.
 Use `scripts/goalkeeper-update-checkpoint.mjs` when you want a bounded canonical checkpoint instead of manual Markdown edits.
 
+## Shutdown Rule
+
+When a Goalkeeper-managed goal is complete, shut down the active Goalkeeper session before sending the final completion response.
+
+Do this when:
+
+- the done criteria are satisfied
+- the user explicitly ends the goal
+- the work is abandoned, superseded, or intentionally paused without needing checkpoint-first recovery on unrelated questions
+
+Shutdown steps:
+
+1. Append a final `close` event.
+2. Mark `checkpoint.md` as closed with the final outcome and residual risks.
+3. Remove `.goalkeeper/active-session` when it points to the closed session.
+4. Do not apply checkpoint-first recovery to later unrelated user questions.
+
+Use the close helper:
+
+```bash
+node <skill-path>/scripts/goalkeeper-close.mjs --workspace <workspace> --outcome "<final outcome>"
+```
+
+After shutdown, read the closed session again only if the user explicitly resumes that goal or asks about its history.
+
 ## Keep It Short
 
 The checkpoint is a recovery artifact, not a transcript.
@@ -157,6 +184,7 @@ Read it when checkpoint recovery is not enough. Keep raw transcripts and long co
 - Run `scripts/goalkeeper-turn-start.mjs --context` when checkpoint recovery needs the larger context pack too.
 - Run `scripts/goalkeeper-append-event.mjs` instead of hand-writing JSONL when recording decisions, verification, failures, risks, or handoffs; it can use `.goalkeeper/active-session` when `--session` is omitted.
 - Run `scripts/goalkeeper-update-checkpoint.mjs` after appending a meaningful event when checkpoint state should be refreshed in a short canonical shape.
+- Run `scripts/goalkeeper-close.mjs` before the final completion response when the managed goal is done, abandoned, or superseded.
 - Run `scripts/goalkeeper-doctor.mjs` after creating or changing Goalkeeper state to verify the target workspace is ready.
 
 ## Safety Boundary

package/src/goalkeeper/references/event-schema.md

@@ -33,7 +33,7 @@ When `<workspace>/.goalkeeper/active-session` points to the current session, `--
 - `evidence`: short supporting detail.
 - `files`: array of file paths.
 - `commands`: array of commands.
-- `status`: `open`, `done`, `failed`, `blocked`, or `superseded`.
+- `status`: `open`, `done`, `failed`, `blocked`, `superseded`, or `closed`.
 - `supersedes`: event id or short reference.
 
 ## Initial Types
@@ -51,6 +51,7 @@ When `<workspace>/.goalkeeper/active-session` points to the current session, `--
 - `next_action`: explicit next step.
 - `compact_observed`: a real agent compaction boundary was observed.
 - `recovery_violation`: the agent continued after compaction or resume before reading the Goalkeeper checkpoint.
+- `close`: the managed goal was completed, abandoned, or superseded and the active session should stop applying to unrelated questions.
 
 ## Writing Rules
 

package/src/goalkeeper/references/guardrail.md

@@ -30,6 +30,9 @@ For an active Goalkeeper-managed goal:
 2. Use `context-pack.md` when the checkpoint is too thin to recover the reasoning chain.
 3. Use `events.jsonl` only when exact evidence is needed.
 4. Append `recovery_violation` if the agent continued after compaction or resume before reading the checkpoint.
+5. When the goal is complete, run `goalkeeper-close.mjs` before the final completion response.
+
+If `.goalkeeper/active-session` is absent and the user asks an unrelated question, do not read closed Goalkeeper sessions first.
 
 If `scripts/goalkeeper-turn-start.mjs` is present, it can be used as the first recovery action:
 
@@ -61,4 +64,10 @@ Before starting a high-stakes long run, use the read-only doctor to verify the t
 node <skill-path>/scripts/goalkeeper-doctor.mjs --workspace <workspace> --session <goal-session-id> --strict
 ```
 
+When the managed goal is done, close the session:
+
+```bash
+node <skill-path>/scripts/goalkeeper-close.mjs --workspace <workspace> --outcome "<final outcome>"
+```
+
 Parallel calls are still subject to checkpoint-first ordering. It is acceptable to batch `pwd`, `.goalkeeper/sessions` discovery, and `goalkeeper-turn-start.mjs`; it is not acceptable to include normal project files or verification in that same first post-compact parallel call.

package/src/goalkeeper/references/workflow.md

@@ -73,6 +73,8 @@ Use `context-pack.md` for medium-density reasoning that should survive compactio
 
 For an already active Goalkeeper-managed task, begin each new assistant turn with a checkpoint-first recovery read before touching normal project files.
 
+Only apply this rule when `.goalkeeper/active-session` exists or the user explicitly resumes a known Goalkeeper session. If the active pointer is absent and the user asks an unrelated question, do not read closed sessions first.
+
 Recommended sequence:
 
 ```bash
@@ -166,6 +168,23 @@ Before ending a long working segment:
 2. Update `checkpoint.md` with the current state and exact next action.
 3. Include unresolved risks and verification gaps.
 
+## Shutdown
+
+Before sending the final completion response for a Goalkeeper-managed goal:
+
+1. Confirm the done criteria are satisfied, or that the goal was explicitly abandoned or superseded.
+2. Run the close helper:
+
+   ```bash
+   node <skill-path>/scripts/goalkeeper-close.mjs --workspace <workspace> --outcome "<final outcome>"
+   ```
+
+3. Include repeated `--risk "<text>"` and `--evidence "<text>"` fields when residual risks or final proof should remain recoverable.
+4. Verify `.goalkeeper/active-session` was removed when it pointed to the closed session.
+5. Send the final completion response.
+
+After shutdown, do not apply checkpoint-first recovery to unrelated user questions. Read the closed session only if the user explicitly resumes that goal or asks about its history.
+
 ## Checkpoint Update Guidance
 
 Update the checkpoint after a meaningful state transition, not after every minor tool call.

package/src/goalkeeper/scripts/goalkeeper-append-event.mjs

@@ -17,9 +17,10 @@ const EVENT_TYPES = new Set([
   "next_action",
   "compact_observed",
   "recovery_violation",
+  "close",
 ]);
 
-const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded"]);
+const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded", "closed"]);
 
 const USAGE = `Usage:
   node scripts/goalkeeper-append-event.mjs --type <event-type> --text <summary> [--session <goal-session-id>] [--workspace <path>] [--goal <text>] [--reason <text>] [--evidence <text>] [--status <status>] [--file <path> ...] [--command <cmd> ...] [--ts <iso>] [--json]

package/src/goalkeeper/scripts/goalkeeper-close.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+
+const EVENT_TYPES = new Set([
+  "goal",
+  "user_constraint",
+  "decision",
+  "attempt",
+  "failure",
+  "edit",
+  "command",
+  "verification",
+  "risk",
+  "handoff",
+  "next_action",
+  "compact_observed",
+  "recovery_violation",
+  "close",
+]);
+
+const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded", "closed"]);
+
+const USAGE = `Usage:
+  node scripts/goalkeeper-close.mjs --outcome <text> [--session <goal-session-id>] [--workspace <path>] [--risk <text> ...] [--evidence <text> ...] [--json]
+
+Closes the active Goalkeeper session after a goal is complete, abandoned, or superseded.
+This appends a close event, marks checkpoint.md closed, and removes <workspace>/.goalkeeper/active-session when it points to the closed session.
+`;
+
+function parseArgs(argv) {
+  const options = {
+    sessionId: null,
+    workspace: ".",
+    outcome: null,
+    risks: [],
+    evidence: [],
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--session") {
+      options.sessionId = argv[i + 1];
+      i += 1;
+    } else if (arg === "--workspace") {
+      options.workspace = argv[i + 1];
+      i += 1;
+    } else if (arg === "--outcome") {
+      options.outcome = argv[i + 1];
+      i += 1;
+    } else if (arg === "--risk") {
+      options.risks.push(argv[i + 1]);
+      i += 1;
+    } else if (arg === "--evidence") {
+      options.evidence.push(argv[i + 1]);
+      i += 1;
+    } else if (arg === "--json") {
+      options.json = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!options.workspace || !options.outcome) {
+    throw new Error("Missing required argument.");
+  }
+
+  options.outcome = normalizeText(options.outcome, "outcome");
+  options.risks = options.risks.map((item) => normalizeText(item, "risk"));
+  options.evidence = options.evidence.map((item) => normalizeText(item, "evidence"));
+
+  if (options.sessionId && !isValidSessionId(options.sessionId)) {
+    throw new Error("Session id must be a single path segment.");
+  }
+
+  return options;
+}
+
+function normalizeText(value, field) {
+  if (typeof value !== "string") {
+    throw new Error(`${field} must be a string.`);
+  }
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    throw new Error(`${field} must not be empty.`);
+  }
+  return normalized;
+}
+
+function isValidSessionId(sessionId) {
+  return typeof sessionId === "string" && sessionId.trim().length > 0 && !sessionId.includes("/") && !sessionId.includes("..");
+}
+
+function resolveSessionId(workspace, explicitSessionId) {
+  const activeSessionPath = path.join(workspace, ".goalkeeper", "active-session");
+  if (explicitSessionId) {
+    return { sessionId: explicitSessionId, activeSessionPath, resolvedFromActive: false };
+  }
+
+  if (!fs.existsSync(activeSessionPath)) {
+    throw new Error(`Missing --session and active session pointer: ${activeSessionPath}`);
+  }
+
+  const sessionId = fs.readFileSync(activeSessionPath, "utf8").trim();
+  if (!isValidSessionId(sessionId)) {
+    throw new Error(`Invalid active session id in ${activeSessionPath}`);
+  }
+
+  return { sessionId, activeSessionPath, resolvedFromActive: true };
+}
+
+function validateExistingJsonl(eventsPath) {
+  if (!fs.existsSync(eventsPath)) return 0;
+  const lines = fs.readFileSync(eventsPath, "utf8").split(/\r?\n/);
+  let records = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.trim()) continue;
+    records += 1;
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch (error) {
+      throw new Error(`Refusing to append to invalid JSONL at ${eventsPath}:${i + 1}: ${error.message}`);
+    }
+    validateEventRecord(parsed, eventsPath, i + 1);
+  }
+  return records;
+}
+
+function validateEventRecord(parsed, eventsPath, lineNumber) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event must be a JSON object`);
+  }
+  if (typeof parsed.ts !== "string" || Number.isNaN(Date.parse(parsed.ts))) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event ts must be a valid ISO timestamp string`);
+  }
+  if (typeof parsed.type !== "string" || !EVENT_TYPES.has(parsed.type)) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event type is missing or unknown: ${parsed.type}`);
+  }
+  if (typeof parsed.text !== "string" || parsed.text.trim().length === 0) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event text must be a non-empty string`);
+  }
+  if (parsed.status !== undefined && (typeof parsed.status !== "string" || !STATUSES.has(parsed.status))) {
+    throw new Error(`Invalid event at ${eventsPath}:${lineNumber}: event status is unknown: ${parsed.status}`);
+  }
+}
+
+function bulletList(items, fallback = "None recorded.") {
+  const values = items.length > 0 ? items : [fallback];
+  return values.map((item) => `- ${item}`).join("\n");
+}
+
+function renderClosedCheckpoint(existingCheckpoint, options, closedAt) {
+  const withoutOldClosedSection = existingCheckpoint.replace(/\n## Closed\n[\s\S]*?(?=\n## |\s*$)/g, "").trimEnd();
+  const withClosedStatus = withoutOldClosedSection.includes("- Current status:")
+    ? withoutOldClosedSection.replace(/^- Current status: .*$/m, "- Current status: Closed.")
+    : `${withoutOldClosedSection}\n\n## Status\n\n- Current status: Closed.`;
+
+  return `${withClosedStatus}
+
+## Closed
+
+- Outcome: ${options.outcome}
+- Closed at: ${closedAt}
+
+## Residual Risks
+
+${bulletList(options.risks)}
+
+## Final Evidence
+
+${bulletList(options.evidence)}
+`;
+}
+
+function maybeRemoveActiveSession(activeSessionPath, sessionId) {
+  if (!fs.existsSync(activeSessionPath)) {
+    return { removed: false, reason: "active-session was already missing." };
+  }
+
+  const activeSessionId = fs.readFileSync(activeSessionPath, "utf8").trim();
+  if (activeSessionId !== sessionId) {
+    return {
+      removed: false,
+      reason: `active-session points to ${activeSessionId || "(empty)"}, not ${sessionId}.`,
+    };
+  }
+
+  fs.rmSync(activeSessionPath);
+  return { removed: true, reason: "active-session pointed to the closed session." };
+}
+
+function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message);
+    console.error(USAGE);
+    process.exit(2);
+  }
+
+  const workspace = path.resolve(options.workspace);
+  if (!fs.existsSync(workspace) || !fs.statSync(workspace).isDirectory()) {
+    console.error(`Workspace does not exist or is not a directory: ${workspace}`);
+    process.exit(1);
+  }
+
+  let resolvedSession;
+  try {
+    resolvedSession = resolveSessionId(workspace, options.sessionId);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  const sessionDir = path.join(workspace, ".goalkeeper", "sessions", resolvedSession.sessionId);
+  const checkpointPath = path.join(sessionDir, "checkpoint.md");
+  const eventsPath = path.join(sessionDir, "events.jsonl");
+
+  if (!fs.existsSync(sessionDir) || !fs.statSync(sessionDir).isDirectory()) {
+    console.error(`Goalkeeper session directory is missing: ${sessionDir}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(checkpointPath)) {
+    console.error(`Checkpoint is missing: ${checkpointPath}`);
+    process.exit(1);
+  }
+
+  let existingRecords;
+  try {
+    existingRecords = validateExistingJsonl(eventsPath);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  const closedAt = new Date().toISOString();
+  const event = {
+    ts: closedAt,
+    type: "close",
+    text: options.outcome,
+    status: "closed",
+  };
+  if (options.risks.length > 0) event.reason = `Residual risks: ${options.risks.join("; ")}`;
+  if (options.evidence.length > 0) event.evidence = options.evidence.join("; ");
+
+  fs.appendFileSync(eventsPath, `${JSON.stringify(event)}\n`);
+
+  const existingCheckpoint = fs.readFileSync(checkpointPath, "utf8");
+  const checkpoint = renderClosedCheckpoint(existingCheckpoint, options, closedAt);
+  fs.writeFileSync(checkpointPath, checkpoint);
+
+  const activeSession = maybeRemoveActiveSession(resolvedSession.activeSessionPath, resolvedSession.sessionId);
+
+  const result = {
+    ok: true,
+    workspace,
+    sessionId: resolvedSession.sessionId,
+    sessionDir,
+    checkpointPath,
+    eventsPath,
+    lineNumber: existingRecords + 1,
+    activeSessionPath: resolvedSession.activeSessionPath,
+    activeSession,
+    event,
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log("Goalkeeper close: PASS");
+  console.log(`Session: ${resolvedSession.sessionId}`);
+  console.log(`Checkpoint: ${checkpointPath}`);
+  console.log(`Events: ${eventsPath}`);
+  console.log(`Active session removed: ${activeSession.removed ? "yes" : "no"}`);
+}
+
+main();

package/src/goalkeeper/scripts/goalkeeper-doctor.mjs

@@ -19,9 +19,10 @@ const EVENT_TYPES = new Set([
   "next_action",
   "compact_observed",
   "recovery_violation",
+  "close",
 ]);
 
-const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded"]);
+const STATUSES = new Set(["open", "done", "failed", "blocked", "superseded", "closed"]);
 const CHECKPOINT_TARGET_BYTES = 8_000;
 const CHECKPOINT_MAX_BYTES = 16_000;
 const CONTEXT_PACK_TARGET_BYTES = 30_000;

package/src/goalkeeper/templates/AGENTS.goalkeeper.md

@@ -1,6 +1,8 @@
 # Goalkeeper Guardrail
 
-When this repository has an active `.goalkeeper/sessions/<goal-session-id>/` directory, treat it as the continuity source for long-running agent work.
+When this repository has an active `.goalkeeper/active-session` pointer, treat the referenced `.goalkeeper/sessions/<goal-session-id>/` directory as the continuity source for long-running agent work.
+
+If `.goalkeeper/active-session` is absent and the user asks an unrelated question, do not read closed Goalkeeper sessions first.
 
 At the start of each new assistant turn, before reading normal project files or making edits:
 
@@ -45,4 +47,6 @@ Do not read project docs, source files, examples, tests, or make edits before th
 
 If you notice that you continued after compaction or resume without reading the checkpoint, stop, read it immediately, append a `recovery_violation` event, then continue from the recovered state.
 
+When the managed goal is complete, run `goalkeeper-close.mjs` before sending the final completion response. This records the final outcome and removes `.goalkeeper/active-session` so later unrelated questions are not treated as goal recovery.
+
 Do not claim Goalkeeper reduces compaction frequency. Its purpose is direction recovery after compaction, resume, or handoff.

package/src/goalkeeper/templates/CLAUDE.goalkeeper.md

@@ -1,6 +1,8 @@
 # Goalkeeper Guardrail
 
-When this repository has an active `.goalkeeper/sessions/<goal-session-id>/` directory, treat it as the continuity source for long-running Claude Code or agent work.
+When this repository has an active `.goalkeeper/active-session` pointer, treat the referenced `.goalkeeper/sessions/<goal-session-id>/` directory as the continuity source for long-running Claude Code or agent work.
+
+If `.goalkeeper/active-session` is absent and the user asks an unrelated question, do not read closed Goalkeeper sessions first.
 
 At the start of each new assistant turn, before reading normal project files or making edits:
 
@@ -45,4 +47,6 @@ Do not read project docs, source files, examples, tests, or make edits before th
 
 If you notice that you continued after compaction or resume without reading the checkpoint, stop, read it immediately, append a `recovery_violation` event, then continue from the recovered state.
 
+When the managed goal is complete, run `goalkeeper-close.mjs` before sending the final completion response. This records the final outcome and removes `.goalkeeper/active-session` so later unrelated questions are not treated as goal recovery.
+
 Do not claim Goalkeeper reduces compaction frequency. Its purpose is direction recovery after compaction, resume, or handoff.