@remnic/core 9.3.692 → 9.3.693

package/src/access-http.ts

@@ -317,6 +317,7 @@ export class EngramAccessHttpServer {
       emitLegacyTools: options.emitLegacyTools,
       codingDecisionVisible: this.service.decisionRecordSurfaceVisible,
       architectureCardVisible: this.service.architectureCardSurfaceVisible,
+      sessionDeltaVisible: this.service.sessionDeltaSurfaceVisible,
     });
   }
 
@@ -1386,6 +1387,25 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (req.method === "POST" && pathname === "/engram/v1/coding/delta") {
+      // Migrated through the access boundary (issue #1525/#1548 PR4):
+      // get is read-only with respect to user memory content. It DOES write
+      // the operator-side state file (last-seen-head marker), but that is
+      // bookkeeping — the same way calibration.ts writes are uncounted. No
+      // write-quota enforcement.
+      const body = await this.readJsonBody(req);
+      const op = getOperation("coding_delta");
+      if (!op) {
+        throw new EngramAccessInputError("access-boundary: operation not registered: coding_delta");
+      }
+      const output = (await op.run(body, {
+        service: this.service,
+        authenticatedPrincipal: this.resolveRequestPrincipal(req),
+      })) as { result: unknown };
+      this.respondJson(res, 200, output.result);
+      return;
+    }
+
     if (req.method === "POST" && pathname === "/engram/v1/suggestions") {
       const body = await this.readValidatedBody(req, "suggestionSubmit");
       const request = {

package/src/access-mcp.ts

@@ -111,6 +111,7 @@ const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> = {
   "engram.memory_store": "memory_store",
   "engram.coding_decision": "coding_decision",
   "engram.coding_architecture": "coding_architecture",
+  "engram.coding_delta": "coding_delta",
 };
 
 function resolveChatGptInspectorRecallSessionKey(
@@ -331,6 +332,7 @@ export class EngramMcpServer {
    * (issue #1548 Track A PR 3, rule 39).
    */
   private readonly architectureCardVisible: boolean;
+  private readonly sessionDeltaVisible: boolean;
 
   constructor(
     private readonly service: EngramAccessService,
@@ -341,6 +343,7 @@ export class EngramMcpServer {
       emitLegacyTools?: boolean;
       codingDecisionVisible?: boolean;
       architectureCardVisible?: boolean;
+      sessionDeltaVisible?: boolean;
     } = {},
   ) {
     this.citationsEnabled = options.citationsEnabled === true;
@@ -348,6 +351,7 @@ export class EngramMcpServer {
     this.emitLegacyTools = options.emitLegacyTools !== false;
     this.codingDecisionVisible = options.codingDecisionVisible === true;
     this.architectureCardVisible = options.architectureCardVisible === true;
+    this.sessionDeltaVisible = options.sessionDeltaVisible === true;
     this.authenticatedPrincipal =
       options.principal?.trim() ||
       readEnvVar("OPENCLAW_ENGRAM_ACCESS_PRINCIPAL")?.trim() ||
@@ -2033,6 +2037,31 @@ export class EngramMcpServer {
       );
       this.tools = [...this.tools, ...architectureTools];
     }
+    if (this.sessionDeltaVisible) {
+      const deltaTools = withToolAliases(
+        {
+          name: "engram.coding_delta",
+          description:
+            "Get the session delta (commits + touched files since last seen) for the session's coding namespace (issue #1548 Track A PR 4). Subcommand: get.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              subcommand: {
+                type: "string",
+                enum: ["get"],
+                description: "Which delta operation to run.",
+              },
+              sessionKey: { type: "string", description: "Session identifier whose coding context scopes the operation." },
+              namespace: { type: "string", description: "Optional explicit namespace (overrides coding-context overlay)." },
+            },
+            required: ["subcommand"],
+            additionalProperties: false,
+          },
+        },
+        this.emitLegacyTools,
+      );
+      this.tools = [...this.tools, ...deltaTools];
+    }
   }
 
   /** Get clientInfo for a specific MCP session. Returns undefined for non-MCP requests. */

package/src/access-operations.ts

@@ -29,6 +29,11 @@ import {
   type ArchitectureSurfaceRequest,
   type ArchitectureSurfaceResponse,
 } from "./coding/architecture-surfaces.js";
+import {
+  DELTA_SUBCOMMANDS,
+  type DeltaSurfaceRequest,
+  type DeltaSurfaceResponse,
+} from "./coding/session-delta-surfaces.js";
 
 // ---------------------------------------------------------------------------
 // memory_get — fetch one memory by id
@@ -250,6 +255,46 @@ export const codingArchitectureOperation = defineOperation<
   },
 });
 
+// ---------------------------------------------------------------------------
+// coding_delta — session-delta surface (issue #1548 Track A PR 4)
+// ---------------------------------------------------------------------------
+
+const codingDeltaSchema = z.preprocess(
+  (data) => {
+    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+      const obj = data as Record<string, unknown>;
+      const cleaned: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(obj)) {
+        if (value !== null) cleaned[key] = value;
+      }
+      return cleaned;
+    }
+    return data;
+  },
+  z.object({
+    subcommand: z.enum(DELTA_SUBCOMMANDS),
+    sessionKey: z.string().trim().max(512).optional(),
+    namespace: z.string().trim().max(256).optional(),
+  }),
+);
+
+export type CodingDeltaInput = DeltaSurfaceRequest;
+export type CodingDeltaOutput = { result: DeltaSurfaceResponse };
+
+export const codingDeltaOperation = defineOperation<
+  CodingDeltaInput,
+  CodingDeltaOutput
+>({
+  name: "coding_delta",
+  description:
+    "Get the session delta (commits + touched files since last seen) for the session's coding namespace (issue #1548 Track A PR 4).",
+  schema: codingDeltaSchema as z.ZodType<CodingDeltaInput>,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codingDelta(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
 // ---------------------------------------------------------------------------
 // Surface registration map — what each transport calls the pilot ops
 // ---------------------------------------------------------------------------
@@ -265,4 +310,5 @@ export const REGISTERED_OPERATIONS = [
   memoryStoreOperation.spec.name,
   codingDecisionOperation.spec.name,
   codingArchitectureOperation.spec.name,
+  codingDeltaOperation.spec.name,
 ] as const;

package/src/access-service.ts

@@ -28,6 +28,13 @@ import {
   ARCHITECTURE_CARD_TAG,
 } from "./coding/architecture-surfaces.js";
 import { buildArchitectureCard, createArchitectureCardSummariser } from "./coding/architecture-card.js";
+import {
+  handleCodingDelta,
+  type DeltaSurfaceRequest,
+  type DeltaSurfaceResponse,
+  type DeltaSurfaceStorage,
+} from "./coding/session-delta-surfaces.js";
+import { defaultGitInvoker } from "./coding/git-context.js";
 import { createVersion } from "./page-versioning.js";
 import { WorkStorage } from "./work/storage.js";
 import {
@@ -4545,6 +4552,54 @@ export class EngramAccessService {
     });
   }
 
+  /** Whether the coding_delta tool should appear in tools/list (rule 39). */
+  get sessionDeltaSurfaceVisible(): boolean {
+    return this.orchestrator.config.codingKnowledge?.enabled === true
+      && this.orchestrator.config.codingKnowledge?.sessionDelta === true;
+  }
+  /**
+   * Thin delegate — handler logic in coding/session-delta-surfaces.ts (#1548 PR4).
+   * All three surfaces (MCP/HTTP/CLI) arrive here via the boundary operation.
+   * Namespace resolution uses the SAME coding-scoped read path as the other
+   * coding surfaces; the delta state file lives under
+   * `<memoryDir>/state/coding-knowledge/<namespace>.json`.
+   */
+  async codingDelta(
+    request: DeltaSurfaceRequest,
+    authenticatedPrincipal?: string,
+  ): Promise<DeltaSurfaceResponse> {
+    return handleCodingDelta(request, {
+      codingKnowledge: this.orchestrator.config.codingKnowledge,
+      getCodingContext: (sk) => this.orchestrator.getCodingContextForSession(sk),
+      resolveStorage: async (req) => {
+        const ns = await this.resolveCodingScopedReadableNamespace({
+          namespace: req.namespace,
+          sessionKey: req.sessionKey,
+          authenticatedPrincipal,
+        });
+        const storage = await this.orchestrator.getStorage(ns);
+        // Delta only needs memoryDir + namespace (no readAllMemories). Use the
+        // namespace-ROUTED root (storage.dir), not the global config.memoryDir:
+        // non-default namespaces route to memoryDir/namespaces/<token>, so
+        // session-delta markers must read/write from the routed tree, mirroring
+        // the decision/architecture siblings (cursor review).
+        return {
+          memoryDir: storage.dir,
+          namespace: ns,
+        } satisfies DeltaSurfaceStorage;
+      },
+      gitInvoker: (cwd, args) => {
+        // Reuse the existing defaultGitInvoker (2s timeout, never throws —
+        // the discipline git-context.ts already established). It returns
+        // { stdout, exitCode } so the handler can recover from non-zero
+        // exits without a try/catch.
+        const invoker = defaultGitInvoker();
+        return invoker(cwd, args);
+      },
+      throwInputError: (msg) => { throw new EngramAccessInputError(msg); },
+    });
+  }
+
   async memoryBrowse(
     request: EngramAccessMemoryBrowseRequest = {},
   ): Promise<EngramAccessMemoryBrowseResponse> {

package/src/access-surface-catalog.test.ts

@@ -67,7 +67,7 @@ function shortToolName(advertised: string): string {
 /** Spin up a server with emitLegacyTools=true and read the deduped short names. */
 async function liveMcpToolShortNames(): Promise<ReadonlySet<string>> {
   const stub = { briefingEnabled: true } as unknown as EngramAccessService;
-  const server = new EngramMcpServer(stub, { emitLegacyTools: true, codingDecisionVisible: true, architectureCardVisible: true });
+  const server = new EngramMcpServer(stub, { emitLegacyTools: true, codingDecisionVisible: true, architectureCardVisible: true, sessionDeltaVisible: true });
   const response = await server.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
   const result = (response as { result?: { tools?: Array<{ name: string }> } }).result;
   const names = new Set<string>();

package/src/access-surface-catalog.ts

@@ -74,6 +74,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "memory_store", operation: "memory_store" },
   { tool: "coding_decision", operation: "coding_decision" },
   { tool: "coding_architecture", operation: "coding_architecture" },
+  { tool: "coding_delta", operation: "coding_delta" },
   { tool: "suggestion_submit", operation: null },
   { tool: "entity_get", operation: null },
   { tool: "review_queue_list", operation: null },
@@ -172,6 +173,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "POST", pathname: "/engram/v1/memories", operation: "memory_store" },
   { method: "POST", pathname: "/engram/v1/coding/decisions", operation: "coding_decision" },
   { method: "POST", pathname: "/engram/v1/coding/architecture", operation: "coding_architecture" },
+  { method: "POST", pathname: "/engram/v1/coding/delta", operation: "coding_delta" },
   { method: "POST", pathname: "/engram/v1/suggestions", operation: null },
   { method: "GET", pathname: "/engram/v1/memories", operation: null },
   { method: "GET", pathname: "/engram/v1/memories/:id", operation: "memory_get" },

package/src/cli.ts

@@ -2803,6 +2803,7 @@ export async function runAccessMcpServeCliCommand(
       emitLegacyTools: options.emitLegacyTools,
       codingDecisionVisible: service.decisionRecordSurfaceVisible,
       architectureCardVisible: service.architectureCardSurfaceVisible,
+      sessionDeltaVisible: service.sessionDeltaSurfaceVisible,
     });
   await server.runStdio(options.stdin ?? process.stdin, options.stdout ?? process.stdout);
   return { ok: true };

package/src/coding/coding-namespace.ts

@@ -66,7 +66,7 @@ export interface CodingNamespaceOverlay {
  * greedy quantifiers) closes the polynomial-backtracking surface that
  * CodeQL flagged on patterns like `-+` and `^-+|-+$`.
  */
-function sanitizeFragment(input: string): string {
+export function sanitizeFragment(input: string): string {
   if (typeof input !== "string") return "";
   const trimmed = input.trim().toLowerCase();
   let out = "";

package/src/coding/session-delta-surfaces.test.ts

@@ -0,0 +1,383 @@
+/**
+ * Surface contract tests for the session-delta handler
+ * (issue #1548 Track A PR 4).
+ *
+ * Contract under test:
+ *  - Gate predicate: enabled + sessionDelta + coding context (rule 39).
+ *  - get with no prior state → first_run, state initialized.
+ *  - get with prior head == current → unchanged.
+ *  - get with prior head ancestor → changed with capped delta.
+ *  - get with unreachable prior head → tagged failure (rule 34).
+ *  - State write happens AFTER compute (rule 25); failures are logged not fatal.
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  DELTA_SUBCOMMANDS,
+  formatDeltaSubcommands,
+  handleCodingDelta,
+  isDeltaSubcommand,
+  isSessionDeltaSurfaceEnabled,
+  isSessionDeltaSurfaceVisible,
+  type DeltaSurfaceContext,
+  type DeltaSurfaceStorage,
+} from "./session-delta-surfaces.js";
+import type {
+  CodingKnowledgeConfig,
+  CodingContext,
+} from "../types.js";
+import type { SessionDeltaGitInvoker } from "./session-delta.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Fixtures
+// ──────────────────────────────────────────────────────────────────────────
+
+const DEFAULT_CONFIG: CodingKnowledgeConfig = {
+  enabled: true,
+  decisionRecords: true,
+  architectureCard: true,
+  sessionDelta: true,
+  architectureCardLlmSummary: false,
+  structuralProvider: "none",
+  structuralProviderCommand: "",
+};
+
+const CODING_CONTEXT: CodingContext = {
+  projectId: "origin:deadbeef",
+  branch: "main",
+  rootPath: "/fake/repo",
+  defaultBranch: "main",
+};
+
+function makeStorage(): DeltaSurfaceStorage {
+  return { memoryDir: "/fake/mem", namespace: "project-test" };
+}
+
+function makeInvoker(responses: Array<{ args: string[]; stdout: string; exitCode?: number }>): SessionDeltaGitInvoker {
+  return (_cwd: string, args: string[]) => {
+    const match = responses.find((r) => r.args.join(" ") === args.join(" "));
+    if (!match) return { stdout: "", exitCode: 1 };
+    return { stdout: match.stdout, exitCode: match.exitCode ?? 0 };
+  };
+}
+
+function makeContext(overrides: Partial<DeltaSurfaceContext> = {}): DeltaSurfaceContext {
+  return {
+    codingKnowledge: DEFAULT_CONFIG,
+    getCodingContext: () => CODING_CONTEXT,
+    resolveStorage: async () => makeStorage(),
+    gitInvoker: makeInvoker([]),
+    throwInputError: (msg) => {
+      throw new Error(msg);
+    },
+    ...overrides,
+  };
+}
+
+// Stub the pure module's state read/write by importing the real module and
+// shimming its filesystem. The handler imports readLastSeenState / writeLastSeenState
+// from ./session-delta.js, which hit the real fs. We point memoryDir at a
+// temp dir per-test.
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+async function makeTempStorage(): Promise<{ storage: DeltaSurfaceStorage; cleanup: () => Promise<void> }> {
+  const dir = await mkdtemp(path.join(tmpdir(), "delta-surface-"));
+  return {
+    storage: { memoryDir: dir, namespace: "project-test" },
+    cleanup: async () => { await rm(dir, { recursive: true, force: true }); },
+  };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Subcommand + gate helpers
+// ──────────────────────────────────────────────────────────────────────────
+
+test("subcommands: the surface exposes only `get`", () => {
+  assert.deepEqual([...DELTA_SUBCOMMANDS], ["get"]);
+  assert.equal(formatDeltaSubcommands(), "get");
+});
+
+test("isDeltaSubcommand: narrows valid + rejects unknown", () => {
+  assert.equal(isDeltaSubcommand("get"), true);
+  assert.equal(isDeltaSubcommand("refresh"), false);
+  assert.equal(isDeltaSubcommand(undefined), false);
+  assert.equal(isDeltaSubcommand(123), false);
+});
+
+test("gate: surface enabled when config + sessionDelta + coding context all true", () => {
+  assert.equal(isSessionDeltaSurfaceEnabled(DEFAULT_CONFIG, CODING_CONTEXT), true);
+});
+
+test("gate: surface disabled when master gate off", () => {
+  const config: CodingKnowledgeConfig = { ...DEFAULT_CONFIG, enabled: false };
+  assert.equal(isSessionDeltaSurfaceEnabled(config, CODING_CONTEXT), false);
+});
+
+test("gate: surface disabled when sessionDelta off", () => {
+  const config: CodingKnowledgeConfig = { ...DEFAULT_CONFIG, sessionDelta: false };
+  assert.equal(isSessionDeltaSurfaceEnabled(config, CODING_CONTEXT), false);
+});
+
+test("gate: surface disabled when no coding context", () => {
+  assert.equal(isSessionDeltaSurfaceEnabled(DEFAULT_CONFIG, null), false);
+  assert.equal(isSessionDeltaSurfaceEnabled(DEFAULT_CONFIG, undefined), false);
+});
+
+test("visibility gate: config-only check mirrors full gate minus context", () => {
+  assert.equal(isSessionDeltaSurfaceVisible(DEFAULT_CONFIG), true);
+  assert.equal(isSessionDeltaSurfaceVisible({ ...DEFAULT_CONFIG, enabled: false }), false);
+  assert.equal(isSessionDeltaSurfaceVisible({ ...DEFAULT_CONFIG, sessionDelta: false }), false);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Handler — gate enforcement
+// ──────────────────────────────────────────────────────────────────────────
+
+test("handler: throws when gate fails (no coding context)", async () => {
+  const ctx = makeContext({ getCodingContext: () => null });
+  await assert.rejects(
+    () => handleCodingDelta({ subcommand: "get", sessionKey: "s1" }, ctx),
+    /coding_delta requires/,
+  );
+});
+
+test("handler: throws when gate fails (master gate off)", async () => {
+  const ctx = makeContext({
+    codingKnowledge: { ...DEFAULT_CONFIG, enabled: false },
+  });
+  await assert.rejects(
+    () => handleCodingDelta({ subcommand: "get", sessionKey: "s1" }, ctx),
+    /coding_delta requires/,
+  );
+});
+
+test("handler: throws when gate fails (sessionDelta off)", async () => {
+  const ctx = makeContext({
+    codingKnowledge: { ...DEFAULT_CONFIG, sessionDelta: false },
+  });
+  await assert.rejects(
+    () => handleCodingDelta({ subcommand: "get", sessionKey: "s1" }, ctx),
+    /coding_delta requires/,
+  );
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Handler — three-state matrix via the surface
+// ──────────────────────────────────────────────────────────────────────────
+
+test("handler/get: first run → first_run, nextState initialized", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    const invoker = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "newhead\n" },
+    ]);
+    const ctx = makeContext({
+      resolveStorage: async () => storage,
+      gitInvoker: invoker,
+    });
+    const result = await handleCodingDelta({ subcommand: "get", sessionKey: "s1" }, ctx);
+    assert.equal(result.subcommand, "get");
+    if (!("ok" in result) || !result.ok || result.kind !== "first_run") {
+      assert.fail(`expected first_run, got ${JSON.stringify(result)}`);
+      return;
+    }
+    assert.equal(result.nextState.head, "newhead");
+    assert.ok(result.nextState.at);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("handler/get: unchanged head → suppressed", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    // Pre-seed the state file by running once.
+    const invoker1 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "stable\n" },
+    ]);
+    const ctx1 = makeContext({ resolveStorage: async () => storage, gitInvoker: invoker1 });
+    await handleCodingDelta({ subcommand: "get", sessionKey: "s1" }, ctx1);
+
+    // Second call with the same head.
+    const invoker2 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "stable\n" },
+    ]);
+    const ctx2 = makeContext({ resolveStorage: async () => storage, gitInvoker: invoker2 });
+    const result = await handleCodingDelta({ subcommand: "get", sessionKey: "s1" }, ctx2);
+    if (!("ok" in result) || !result.ok || result.kind !== "unchanged") {
+      assert.fail(`expected unchanged, got ${JSON.stringify(result)}`);
+      return;
+    }
+  } finally {
+    await cleanup();
+  }
+});
+
+test("handler/get: changed head → real delta", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    // Seed: first run on headA.
+    const invoker1 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headA\n" },
+    ]);
+    await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker1 }),
+    );
+
+    // Now head moved to headB with two commits.
+    const sep = "\x1f";
+    const log = [
+      `sha1${sep}feat: a`,
+      "",
+      "src/a.ts",
+      "",
+      `sha2${sep}fix: b`,
+      "",
+      "src/b.ts",
+      "",
+    ].join("\n");
+    const invoker2 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headB\n" },
+      { args: ["log", "--reverse", "--pretty=format:%H\x1f%s", "--name-only", "headA..headB"], stdout: log },
+    ]);
+    const result = await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker2 }),
+    );
+    if (!("ok" in result) || !result.ok || result.kind !== "changed") {
+      assert.fail(`expected changed, got ${JSON.stringify(result)}`);
+      return;
+    }
+    assert.equal(result.delta.commits.length, 2);
+    assert.equal(result.delta.touchedFiles.length, 2);
+    assert.match(result.delta.summaryLine, /2 commits, 2 files touched/);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("handler/get: unreachable prior head → tagged failure, state advances", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    // Seed headA.
+    const invoker1 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headA\n" },
+    ]);
+    await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker1 }),
+    );
+
+    // Now head is headB but `git log headA..headB` fails (force-push).
+    const invoker2 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headB\n" },
+      { args: ["log", "--reverse", "--pretty=format:%H\x1f%s", "--name-only", "headA..headB"], stdout: "", exitCode: 128 },
+    ]);
+    const result = await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker2 }),
+    );
+    if (!("ok" in result) || result.ok || result.code !== "unreachable_head") {
+      assert.fail(`expected unreachable_head, got ${JSON.stringify(result)}`);
+      return;
+    }
+    // nextState advanced so the NEXT call sees headB as the baseline.
+    assert.equal(result.nextState?.head, "headB");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("handler/get: git rev-parse failure → git_failed, no state advance", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    const invoker = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "", exitCode: 128 },
+    ]);
+    const result = await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker }),
+    );
+    if (!("ok" in result) || result.ok || result.code !== "git_failed") {
+      assert.fail(`expected git_failed, got ${JSON.stringify(result)}`);
+      return;
+    }
+    // No nextState when the head itself was unreadable.
+    assert.equal(result.nextState, undefined);
+  } finally {
+    await cleanup();
+  }
+});
+
+test("handler/get: transient git log failure (exit 127) → git_failed, state NOT advanced", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    // Seed headA.
+    const invoker1 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headA\n" },
+    ]);
+    await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker1 }),
+    );
+
+    // Head is headB but git log times out (exit 127 = spawn/timeout).
+    const invoker2 = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "headB\n" },
+      { args: ["log", "--reverse", "--pretty=format:%H\x1f%s", "--name-only", "headA..headB"], stdout: "", exitCode: 127 },
+    ]);
+    const result = await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker2 }),
+    );
+    if (!("ok" in result) || result.ok || result.code !== "git_failed") {
+      assert.fail(`expected git_failed, got ${JSON.stringify(result)}`);
+      return;
+    }
+    // State marker must NOT advance — headA preserved for retry on next call.
+    // Read the state file back to verify.
+    const { readFile } = await import("node:fs/promises");
+    const { sessionDeltaStatePath } = await import("./session-delta.js");
+    const raw = await readFile(
+      sessionDeltaStatePath(storage.memoryDir, storage.namespace),
+      "utf8",
+    );
+    const persisted = JSON.parse(raw);
+    assert.equal(persisted.head, "headA", "transient failure must not advance the state marker");
+  } finally {
+    await cleanup();
+  }
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Rule 25 — state write happens AFTER compute
+// ──────────────────────────────────────────────────────────────────────────
+
+test("handler/get: state file is created after a successful first_run", async () => {
+  const { storage, cleanup } = await makeTempStorage();
+  try {
+    const invoker = makeInvoker([
+      { args: ["rev-parse", "HEAD"], stdout: "head1\n" },
+    ]);
+    await handleCodingDelta(
+      { subcommand: "get", sessionKey: "s1" },
+      makeContext({ resolveStorage: async () => storage, gitInvoker: invoker }),
+    );
+    const { readFile } = await import("node:fs/promises");
+    const raw = await readFile(
+      // The handler uses sessionDeltaStatePath(memoryDir, namespace).
+      // We import and call the same helper for parity.
+      (await import("./session-delta.js")).sessionDeltaStatePath(storage.memoryDir, storage.namespace),
+      "utf8",
+    );
+    const parsed = JSON.parse(raw);
+    assert.equal(parsed.head, "head1");
+    assert.ok(parsed.at);
+  } finally {
+    await cleanup();
+  }
+});