@opengsd/gsd-pi 1.6.0 → 1.7.0-dev.30c4ec2f

package/packages/gsd-agent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/agent-core",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "description": "GSD session orchestration layer on top of @gsd/pi-coding-agent",
   "type": "module",
   "gsd": {
@@ -25,9 +25,9 @@
     "test": "node --import ../../src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test src/*.test.ts src/**/*.test.ts"
   },
   "dependencies": {
-    "@gsd/native": "^1.6.0",
-    "@gsd/pi-agent-core": "^1.6.0",
-    "@gsd/pi-ai": "^1.6.0",
-    "@gsd/pi-coding-agent": "^1.6.0"
+    "@gsd/native": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-agent-core": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-ai": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-coding-agent": "^1.7.0-dev.30c4ec2f"
   }
 }

package/packages/gsd-agent-modes/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/agent-modes",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "description": "GSD run modes and CLI layer",
   "type": "module",
   "gsd": {
@@ -25,12 +25,12 @@
     "test": "node --import ../../src/resources/extensions/gsd/tests/resolve-ts.mjs --experimental-strip-types --test src/**/*.test.ts"
   },
   "dependencies": {
-    "@gsd/agent-core": "^1.6.0",
-    "@gsd/pi-agent-core": "^1.6.0",
-    "@gsd/pi-ai": "^1.6.0",
-    "@gsd/pi-coding-agent": "^1.6.0",
-    "@gsd/pi-tui": "^1.6.0",
-    "@opengsd/contracts": "^1.6.0",
+    "@gsd/agent-core": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-agent-core": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-ai": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-coding-agent": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-tui": "^1.7.0-dev.30c4ec2f",
+    "@opengsd/contracts": "^1.7.0-dev.30c4ec2f",
     "chalk": "^5.5.0"
   }
 }

package/packages/gsd-cloud/README.md

@@ -0,0 +1,48 @@
+# @opengsd/gsd-cloud
+
+Connect a local GSD runtime to [GSD Cloud](https://cloud.opengsd.net) so you can
+monitor and control your GSD projects from any browser.
+
+This is a **self-contained** agent. It depends only on `ws` and `yaml` — no
+`@opengsd/daemon`, no `@opengsd/mcp-server`, no `@opengsd/gsd-pi`. It runs the
+RFC 8628 device-flow login, opens a persistent WebSocket to the cloud gateway,
+and forwards each requested GSD workflow tool to your locally-installed `gsd`
+CLI (via `gsd --mode mcp`). The gateway default of `https://cloud.opengsd.net`
+is injected for `login`/`pair` so you never have to type `--gateway`.
+
+Requires the `gsd` CLI (from `@opengsd/gsd-pi`) to be installed and on your
+`PATH` (or set `GSD_CLI_PATH`).
+
+## Usage
+
+```bash
+# Browser-based pairing against GSD Cloud (recommended). Opens an approval URL,
+# polls for authorization, then auto-connects. No --gateway needed.
+npx @opengsd/gsd-cloud login
+
+# Show current cloud runtime configuration and connection status.
+npx @opengsd/gsd-cloud status
+
+# Start the daemon using a previously paired device token.
+npx @opengsd/gsd-cloud connect
+
+# Remove cloud runtime configuration from the local config file.
+npx @opengsd/gsd-cloud disconnect
+```
+
+`login` (and `pair`) default to `https://cloud.opengsd.net`. To target a
+different gateway, pass `--gateway <url>` explicitly — the explicit flag always
+wins. The `status`, `connect`, and `disconnect` commands do not use a gateway.
+
+## Environment
+
+- `GSD_CLOUD_PROJECTS` — path-delimiter separated list of project directories to
+  advertise to the cloud (default: the current working directory).
+- `GSD_CLI_PATH` — path to the `gsd` binary (default: `gsd` on `PATH`).
+- `GSD_CLOUD_EXECUTOR` — backend adapter: `gsd-pi` (default). `codex` and
+  `claude` adapters are stubbed for future use.
+
+## Requirements
+
+- Node.js >= 22
+- The `gsd` CLI (`@opengsd/gsd-pi`) installed locally

package/packages/gsd-cloud/bin/gsd-cloud.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// Project/App: Open GSD
+// File Purpose: gsd-cloud CLI entry — inject the default gateway, then run the
+//               standalone cloud command handler. No @opengsd/daemon dependency.
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const binDir = dirname(fileURLToPath(import.meta.url));
+const distDir = join(binDir, '..', 'dist');
+
+if (!existsSync(join(distDir, 'cli.js'))) {
+  process.stderr.write('gsd-cloud: build output missing. Run `pnpm --filter @opengsd/gsd-cloud run build`.\n');
+  process.exit(1);
+}
+
+const { injectDefaultGateway } = await import('../dist/inject-gateway.js');
+const { handleCloudCommand } = await import('../dist/cli.js');
+
+const argv = injectDefaultGateway(process.argv.slice(2));
+
+try {
+  await handleCloudCommand(argv, { binaryName: 'gsd-cloud' });
+} catch (err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`gsd-cloud: fatal: ${msg}\n`);
+  process.exit(1);
+}

package/packages/gsd-cloud/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@opengsd/gsd-cloud",
+  "version": "1.7.0-dev.30c4ec2f",
+  "description": "Standalone CLI agent that connects a local GSD runtime to GSD Cloud (cloud.opengsd.net)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-gsd/gsd-pi.git",
+    "directory": "packages/gsd-cloud"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "gsd-cloud": "./bin/gsd-cloud.js"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-package-dist.cjs && tsc",
+    "test": "pnpm run build && node --test dist/inject-gateway.test.js dist/cloud-gateway-lookup.test.js dist/cloud-runtime.test.js dist/executors/mcp-stdio-client.test.js dist/executors/gsd-pi-executor.test.js"
+  },
+  "dependencies": {
+    "ws": "^8.21.0",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "README.md",
+    "bin",
+    "dist",
+    "!dist/**/*.test.*"
+  ]
+}

package/packages/mcp-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/mcp-server",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "description": "MCP server exposing GSD orchestration tools for compatible clients",
   "license": "MIT",
   "gsd": {
@@ -50,9 +50,9 @@
     "test": "pnpm run build:test && node --test dist/mcp-server.test.js dist/remote-questions.test.js dist/moonshot-tool-schema.test.js dist/pid-registry.test.js dist/probe-mode.test.js dist/stdio-watchdog.test.js dist/cli-runner.test.js dist/readers/graph.test.js dist/readers/paths.test.js dist/readers/readers.test.js"
   },
   "dependencies": {
-    "@gsd/pi-ai": "^1.6.0",
-    "@opengsd/contracts": "^1.6.0",
-    "@opengsd/rpc-client": "^1.6.0",
+    "@gsd/pi-ai": "^1.7.0-dev.30c4ec2f",
+    "@opengsd/contracts": "^1.7.0-dev.30c4ec2f",
+    "@opengsd/rpc-client": "^1.7.0-dev.30c4ec2f",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^4.0.0"
   },

package/packages/native/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/native",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "description": "Native Rust bindings for GSD — high-performance native modules via N-API",
   "type": "commonjs",
   "gsd": {

package/packages/pi-agent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-agent-core",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "description": "General-purpose agent with transport abstraction, state management, and attachment support",
   "type": "module",
   "gsd": {

package/packages/pi-ai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-ai",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "description": "Unified LLM API with automatic model discovery and provider configuration",
   "type": "module",
   "gsd": {

package/packages/pi-coding-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-coding-agent",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "description": "Coding agent CLI (vendored from earendil-works/pi)",
   "type": "module",
   "gsd": {
@@ -33,7 +33,7 @@
     "copy-assets": "node scripts/copy-assets.cjs"
   },
   "dependencies": {
-    "@opengsd/contracts": "^1.6.0",
+    "@opengsd/contracts": "^1.7.0-dev.30c4ec2f",
     "@mariozechner/jiti": "^2.6.2",
     "@silvia-odwyer/photon-node": "0.3.4",
     "chalk": "5.6.2",
@@ -53,11 +53,11 @@
     "typebox": "1.1.38",
     "undici": "7.28.0",
     "yaml": "2.9.0",
-    "@gsd/agent-core": "^1.6.0",
-    "@gsd/native": "^1.6.0",
-    "@gsd/pi-agent-core": "^1.6.0",
-    "@gsd/pi-ai": "^1.6.0",
-    "@gsd/pi-tui": "^1.6.0",
+    "@gsd/agent-core": "^1.7.0-dev.30c4ec2f",
+    "@gsd/native": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-agent-core": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-ai": "^1.7.0-dev.30c4ec2f",
+    "@gsd/pi-tui": "^1.7.0-dev.30c4ec2f",
     "@sinclair/typebox": "^0.34.41"
   },
   "devDependencies": {

package/packages/pi-tui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-tui",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "description": "Terminal UI library (vendored from earendil-works/pi)",
   "type": "module",
   "gsd": {
@@ -21,7 +21,7 @@
     "build": "node ../../scripts/clean-package-dist.cjs && tsc -p tsconfig.json --incremental false"
   },
   "dependencies": {
-    "@gsd/native": "^1.6.0",
+    "@gsd/native": "^1.7.0-dev.30c4ec2f",
     "get-east-asian-width": "1.6.0",
     "marked": "15.0.12",
     "@sinclair/typebox": "^0.34.41"

package/packages/rpc-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/rpc-client",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "description": "Standalone RPC client SDK for GSD — zero internal dependencies",
   "license": "MIT",
   "gsd": {
@@ -34,7 +34,7 @@
     "test": "node --test dist/rpc-client.test.js"
   },
   "dependencies": {
-    "@opengsd/contracts": "^1.6.0"
+    "@opengsd/contracts": "^1.7.0-dev.30c4ec2f"
   },
   "engines": {
     "node": ">=22.0.0"

package/pkg/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glittercowboy/gsd",
-  "version": "1.6.0",
+  "version": "1.7.0-dev.30c4ec2f",
   "piConfig": {
     "name": "gsd",
     "configDir": ".gsd"

package/src/resources/extensions/browser-tools/tests/gsd-browser-launch-config.test.mjs

@@ -9,6 +9,7 @@ import { dirname, join } from "node:path";
 const {
   resolveBundledGsdBrowserCliPath,
   resolveGsdBrowserDaemonStartInvocation,
+  resolveGsdBrowserDaemonStopInvocation,
   resolveGsdBrowserMcpLaunchConfig,
 } = await import("../../shared/gsd-browser-cli.ts");
 
@@ -179,3 +180,21 @@ describe("resolveGsdBrowserDaemonStartInvocation", () => {
     );
   });
 });
+
+describe("resolveGsdBrowserDaemonStopInvocation", () => {
+  it("mirrors MCP session and identity flags with daemon stop", () => {
+    const launch = resolveGsdBrowserMcpLaunchConfig("/tmp/example-project", {});
+    const daemon = resolveGsdBrowserDaemonStopInvocation("/tmp/example-project", {});
+
+    assert.equal(daemon.command, launch.command);
+    assert.equal(daemon.cwd, launch.cwd);
+    assert.deepEqual(
+      daemon.args.slice(daemon.args.indexOf("--session")),
+      launch.args.slice(launch.args.indexOf("--session")),
+    );
+    assert.deepEqual(
+      daemon.args.slice(0, daemon.args.indexOf("--session")),
+      [...launch.args.slice(0, launch.args.indexOf("mcp")), "daemon", "stop"],
+    );
+  });
+});

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -56,7 +56,7 @@ import { normalizeWorktreePathForCompare } from "./worktree-root.js";
 import { isDbAvailable, getTask, getSlice, getMilestone, getMilestoneSlices, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
 import { getWorkflowDatabasePath, refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { renderPlanCheckboxes, renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "./markdown-renderer.js";
-import { consumeSignal } from "./session-status-io.js";
+import { awaitWorkerResume, consumeSignal } from "./session-status-io.js";
 import {
   checkPostUnitHooks,
   consumeHookFailure,
@@ -1279,8 +1279,27 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         return "dispatched";
       }
       if (signal.signal === "pause") {
-        await pauseAuto(ctx, pi);
-        return "dispatched";
+        // A worker `pause` is a *temporary* coordination request: the docs
+        // contract (docs/user-docs/parallel-orchestration.md) is "finish current
+        // unit, wait" followed by a matching `resume`. Only the interactive
+        // dashboard runtime owns a resumer — unattended `gsd headless auto` does
+        // not — so a terminal pauseAuto() here strands the worker at exit 10
+        // (BLOCKED) after its first unit, with nothing able to lift it (#1273).
+        // Wait for the coordinator to resume (or stop) us instead. If no resumer
+        // lifts the pause within the window, degrade to in-process serialization
+        // and continue the dispatch loop rather than halting the run forever.
+        const resumeOutcome = await awaitWorkerResume(s.basePath, milestoneLock);
+        if (resumeOutcome === "stop") {
+          await stopAuto(ctx, pi);
+          return "dispatched";
+        }
+        if (resumeOutcome === "timeout") {
+          logWarning(
+            "parallel",
+            `pause signal for ${milestoneLock} was not resumed (no headless resumer, #1273); continuing dispatch`,
+          );
+        }
+        // "resume" or "timeout": fall through and continue post-unit processing.
       }
     }
   }

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -2725,6 +2725,26 @@ export async function buildExecuteTaskPrompt(
   let phaseAnchorSection = planAnchor ? formatAnchorForPrompt(planAnchor) : "";
   trackPromptContext(contextTelemetry, "plan-anchor", phaseAnchorSection ? "inline" : "skipped", phaseAnchorSection, phaseAnchorSection ? undefined : "missing");
 
+  // #1272: inject a pending reopen reason into this task's prompt. When a gate
+  // (e.g. complete-slice's full-suite run) reopened the task via gsd_task_reopen
+  // with a diagnosis, surface it here so the re-dispatched executor fixes the
+  // regression instead of re-running the original (green) scoped verify. Claim
+  // is one-shot (artifact deleted on read). Not feature-gated — a reopened task
+  // must always know why. Prepended so it sits above the plan anchor.
+  try {
+    const { claimReopenReasonForInjection } = await import("./reopen-reason.js");
+    const reopenClaimed = claimReopenReasonForInjection(base, mid, sid, tid);
+    if (reopenClaimed) {
+      const block = reopenClaimed.injectionBlock + "\n\n---\n\n";
+      phaseAnchorSection = phaseAnchorSection
+        ? `${block}${phaseAnchorSection}`
+        : block;
+      trackPromptContext(contextTelemetry, "reopen-reason", "inline", reopenClaimed.injectionBlock);
+    }
+  } catch (reopenErr) {
+    logWarning("prompt", `reopen reason injection failed: ${(reopenErr as Error).message}`);
+  }
+
   // ADR-011 Phase 2: inject any resolved-but-unapplied escalation override
   // into this task's prompt. Claim is atomic via DB UPDATE WHERE IS NULL, so
   // if a parallel build already injected it, we skip. Feature-gated by

package/src/resources/extensions/gsd/auto.ts

@@ -185,6 +185,7 @@ import { enterAutoWorktree, isInAutoWorktree } from "./auto-worktree-entry.js";
 import { getAutoWorktreePath } from "./auto-worktree-path-resolution.js";
 import { checkResourcesStale, readResourceVersion } from "./auto-worktree-resource-version.js";
 import { escapeStaleWorktree } from "./auto-worktree-runtime-cleanup.js";
+import { teardownWarmedBrowserDaemons } from "./browser-daemon-auto-prep.js";
 import { getAutoWorktreeOriginalBase } from "./auto-worktree-session-registry.js";
 import { syncWorktreeStateBack } from "./auto-worktree-sync.js";
 import { teardownAutoWorktree } from "./auto-worktree-teardown.js";
@@ -1490,6 +1491,17 @@ export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void>
     logWarning("session", `lock cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
   }
 
+  // Symmetric teardown for the browser-UAT warm-up preflight (#1259): stop any
+  // gsd-browser daemon this session started so the Chrome process does not
+  // linger after the loop exits. Re-warms on the next browser-backed run-uat.
+  try {
+    for (const { projectRoot, error } of teardownWarmedBrowserDaemons()) {
+      logWarning("session", `gsd-browser daemon stop failed for ${projectRoot}: ${error}`, { file: "auto.ts" });
+    }
+  } catch (err) {
+    logWarning("session", `browser daemon teardown failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+  }
+
   // A transient provider-error pause intentionally leaves the paused badge
   // visible so the user still has a resumable auto-mode signal on screen.
   if (!s.paused) {

package/src/resources/extensions/gsd/browser-daemon-auto-prep.ts

@@ -9,10 +9,19 @@ import {
 import {
   resolveGsdBrowserCliAvailability,
   resolveGsdBrowserDaemonStartInvocation,
+  resolveGsdBrowserDaemonStopInvocation,
 } from "../shared/gsd-browser-cli.js";
 import { uatTypeIncludesBrowser, type UatType } from "./uat-policy.js";
 
 const DEFAULT_DAEMON_START_TIMEOUT_MS = 30_000;
+const DEFAULT_DAEMON_STOP_TIMEOUT_MS = 15_000;
+
+/**
+ * Project roots whose gsd-browser daemon this process warmed via
+ * {@link prepareBrowserDaemonForUat}. Teardown only stops daemons we actually
+ * started, so non-browser auto-mode sessions never spawn a stray `daemon stop`.
+ */
+const warmedDaemonProjectRoots = new Set<string>();
 
 function isEnvDisabled(value: string | undefined): boolean {
   if (!value) return false;
@@ -102,7 +111,74 @@ export function prepareBrowserDaemonForUat(ctx: BrowserDaemonWarmContext): strin
   if (!shouldWarmBrowserDaemonForUat(ctx)) return null;
 
   const result = ensureBrowserDaemonStarted(ctx.projectRoot, { env: ctx.env });
-  if (result.ok) return null;
+  if (result.ok) {
+    warmedDaemonProjectRoots.add(resolve(ctx.projectRoot));
+    return null;
+  }
 
   return `Cannot dispatch browser-backed run-uat: gsd-browser daemon failed to start (${result.error}). Ensure Chrome/Chromium is installed, run \`gsd-browser daemon health\` with the project session flags from .mcp.json, or set GSD_BROWSER_PATH to a Chromium binary.`;
 }
+
+/**
+ * Best-effort stop of a gsd-browser session daemon warmed for browser UAT.
+ * Mirrors {@link ensureBrowserDaemonStarted}; returns the failure detail rather
+ * than throwing so teardown can stay non-fatal.
+ */
+export function stopBrowserDaemon(
+  projectRoot: string,
+  options: { env?: NodeJS.ProcessEnv; timeoutMs?: number } = {},
+): { ok: true } | { ok: false; error: string } {
+  const env = options.env ?? process.env;
+  const availability = resolveGsdBrowserCliAvailability(env);
+  if (!availability.available) {
+    return { ok: false, error: availability.detail };
+  }
+
+  let invocation: ReturnType<typeof resolveGsdBrowserDaemonStopInvocation>;
+  try {
+    invocation = resolveGsdBrowserDaemonStopInvocation(projectRoot, env);
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  try {
+    execFileSync(invocation.command, invocation.args, {
+      cwd: invocation.cwd,
+      env: { ...process.env, ...env, ...(invocation.env ?? {}) },
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout: options.timeoutMs ?? DEFAULT_DAEMON_STOP_TIMEOUT_MS,
+      encoding: "utf-8",
+    });
+    return { ok: true };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/**
+ * Tear down every gsd-browser daemon this process warmed for browser UAT,
+ * clearing the tracked set. Called on auto-mode loop exit so the Chrome process
+ * does not survive session/task completion (mirrors the warm-up preflight).
+ * Best-effort: returns the project roots whose stop failed for logging.
+ */
+export function teardownWarmedBrowserDaemons(
+  options: { env?: NodeJS.ProcessEnv } = {},
+): { projectRoot: string; error: string }[] {
+  if (warmedDaemonProjectRoots.size === 0) return [];
+
+  const failures: { projectRoot: string; error: string }[] = [];
+  for (const projectRoot of warmedDaemonProjectRoots) {
+    const result = stopBrowserDaemon(projectRoot, { env: options.env });
+    if (!result.ok) {
+      failures.push({ projectRoot, error: result.error });
+    }
+  }
+  warmedDaemonProjectRoots.clear();
+  return failures;
+}

package/src/resources/extensions/gsd/doctor-history.ts

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { saveFile } from "./files.js";
+import { gsdRoot } from "./paths.js";
+
+import type { DoctorReport } from "./doctor-types.js";
+
+export interface DoctorHistoryEntry {
+  ts: string;
+  ok: boolean;
+  errors: number;
+  warnings: number;
+  fixes: number;
+  codes: string[];
+  /** Issue messages with severity and scope (added in Phase 2). */
+  issues?: Array<{ severity: string; code: string; message: string; unitId: string }>;
+  /** Fix descriptions applied during this run (added in Phase 2). */
+  fixDescriptions?: string[];
+  /** Milestone/slice scope this doctor run was scoped to (e.g. "M001/S02"). */
+  scope?: string;
+  /** Human-readable one-line summary of this doctor run. */
+  summary?: string;
+}
+
+function buildDoctorHistorySummary(report: DoctorReport, errorCount: number, warningCount: number, issueDetails: DoctorHistoryEntry["issues"]): string {
+  const summaryParts: string[] = [];
+  if (report.ok) {
+    summaryParts.push("Clean");
+  } else {
+    const counts: string[] = [];
+    if (errorCount > 0) counts.push(`${errorCount} error${errorCount > 1 ? "s" : ""}`);
+    if (warningCount > 0) counts.push(`${warningCount} warning${warningCount > 1 ? "s" : ""}`);
+    summaryParts.push(counts.join(", "));
+  }
+  if (report.fixesApplied.length > 0) {
+    summaryParts.push(`${report.fixesApplied.length} fixed`);
+  }
+  if (issueDetails && issueDetails.length > 0) {
+    const topIssue = issueDetails.find(i => i.severity === "error") ?? issueDetails[0]!;
+    summaryParts.push(topIssue.message);
+  }
+  return summaryParts.join(" · ");
+}
+
+export async function appendDoctorHistory(basePath: string, report: DoctorReport): Promise<void> {
+  try {
+    const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+    const errorCount = report.issues.filter(i => i.severity === "error").length;
+    const warningCount = report.issues.filter(i => i.severity === "warning").length;
+    const issueDetails = report.issues
+      .filter(i => i.severity === "error" || i.severity === "warning")
+      .slice(0, 10) // cap to keep JSONL lines bounded
+      .map(i => ({ severity: i.severity, code: i.code, message: i.message, unitId: i.unitId }));
+
+    const entry = JSON.stringify({
+      ts: new Date().toISOString(),
+      ok: report.ok,
+      errors: errorCount,
+      warnings: warningCount,
+      fixes: report.fixesApplied.length,
+      codes: [...new Set(report.issues.map(i => i.code))],
+      issues: issueDetails.length > 0 ? issueDetails : undefined,
+      fixDescriptions: report.fixesApplied.length > 0 ? report.fixesApplied : undefined,
+      scope: (report as { scope?: string }).scope,
+      summary: buildDoctorHistorySummary(report, errorCount, warningCount, issueDetails),
+    } satisfies DoctorHistoryEntry);
+    const existing = existsSync(historyPath) ? readFileSync(historyPath, "utf-8") : "";
+    await saveFile(historyPath, existing + entry + "\n");
+  } catch { /* non-fatal */ }
+}
+
+/** Read the last N doctor history entries. Returns most-recent-first. */
+export async function readDoctorHistory(basePath: string, lastN = 50): Promise<DoctorHistoryEntry[]> {
+  try {
+    const historyPath = join(gsdRoot(basePath), "doctor-history.jsonl");
+    if (!existsSync(historyPath)) return [];
+    const lines = readFileSync(historyPath, "utf-8").split("\n").filter(l => l.trim());
+    return lines.slice(-lastN).reverse().map(l => JSON.parse(l) as DoctorHistoryEntry);
+  } catch { return []; }
+}