@gethmy/harness 1.1.1 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/harness",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Execution motor for Harmony playbook stages. Runs exactly one stage per invocation: worktree, role-separated subagents, held oracle, gate evidence. It never routes, never judges, never pushes.",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.178",
-    "@gethmy/mcp": "2.24.0",
+    "@gethmy/mcp": "2.25.0",
     "@supabase/supabase-js": "2.95.3"
   },
   "devDependencies": {

package/src/cli.ts

@@ -31,6 +31,7 @@ import {
 } from "./gate-collectors.js";
 import { HarmonyClient, readClientConfig } from "./harmony-client.js";
 import { log } from "./log.js";
+import { relayAgentEvent } from "./motor-stream.js";
 import { place, remove, runHeldOracle } from "./oracle.js";
 import { SdkAgentRunner } from "./sdk-agent-runner.js";
 import {
@@ -38,11 +39,13 @@ import {
   assertStageIsAgentRunnable,
   buildStagePrompt,
   buildStageRunnerConfig,
+  describeShutdown,
   findOracleTargetStage,
   parseMetricsAllowlist,
   parseStageRunArgs,
   resolvePinnedStage,
   STAGE_RUN_USAGE,
+  stageTimeoutMs,
 } from "./stage-cli.js";
 import { runStage, type StageRunRequest } from "./stage-run.js";
 
@@ -56,6 +59,65 @@ const TAG = "cli";
  */
 const GATE_VERIFICATION_TIMEOUT_MS = 600_000;
 
+/** Hard exit if the motor's own teardown does not finish after a driver signal. */
+const SHUTDOWN_HARD_EXIT_MS = 15_000;
+
+/**
+ * The subagent runner for the stage currently in flight, published so the
+ * signal handlers can tear it down (card #885).
+ *
+ * A driver signals THIS process. The `claude` subagent is a grandchild in its
+ * OWN process group (`spawnInGroup` detaches it), so a group kill aimed at the
+ * motor never reaches it — only the motor can, through `SdkAgentRunner.stop`,
+ * which aborts the query and then escalates on the subagent's own pgid. Without
+ * a handler here, Node's default SIGTERM disposition killed the motor outright
+ * and left a token-spending `claude` writing into a worktree the driver was
+ * already tearing down.
+ */
+let activeRunner: SdkAgentRunner | null = null;
+let shuttingDown = false;
+
+/**
+ * Stop the stage subagent, then exit non-zero with the motor's error protocol
+ * so the driver reads a cause rather than a bare signal death. Re-entrant: a
+ * second signal while the first teardown runs is ignored, and the unref'd hard
+ * exit is the floor under a `stop()` that never returns.
+ */
+async function shutdown(signal: NodeJS.Signals): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  const runner = activeRunner;
+  // `describeShutdown` refuses to claim a teardown that did not happen: no
+  // subagent is in flight during argument parsing, the card and playbook
+  // fetches, or the whole gate-collection window, and a driver renders this
+  // message verbatim.
+  const plan = describeShutdown(signal, runner !== null);
+  // Written BEFORE the teardown. Node writes stdout/stderr to a pipe
+  // synchronously on Windows and Linux but ASYNCHRONOUSLY on macOS, and
+  // `process.exit` does not flush a pending async write — so on the platform
+  // this daemon usually runs on, a line written immediately before exiting can
+  // be lost outright. Emitting it here gives the teardown's own duration as the
+  // flush margin.
+  //
+  // Note this line reaches a HUMAN or the interactive `hmy` driver, not the
+  // daemon: when the daemon signals, it does so through its own abort, which
+  // settles `runMotorStage` synchronously with its own `errorMessage` and never
+  // reads this one.
+  process.stderr.write(
+    `${JSON.stringify({ type: "error", message: plan.message })}\n`,
+  );
+  const hardExit = setTimeout(() => process.exit(1), SHUTDOWN_HARD_EXIT_MS);
+  hardExit.unref?.();
+  if (plan.stopSubagent) {
+    try {
+      await runner?.stop("shutdown");
+    } catch {
+      // Already gone — the exit below is the point.
+    }
+  }
+  process.exit(1);
+}
+
 /**
  * Run the stage's subagent to completion. The launch decides the role, the
  * environment and the tool denies (runner.ts); `envKeysDroppedByLaunch` turns
@@ -63,13 +125,18 @@ const GATE_VERIFICATION_TIMEOUT_MS = 600_000;
  * key would not remove it, because the child's environment is rebuilt from the
  * motor's own `process.env`.
  *
- * The subagent's own events are diagnostics, not the motor's protocol: stdout
- * carries the newline-delimited motor events a driver parses, so these go to
- * the log instead.
+ * The subagent's events are RELAYED to the driver on stdout (`agent_event`,
+ * card #885) and logged on stderr. They are diagnostics to a human reader and
+ * live telemetry to a driver: the relayed draft is the very shape the daemon's
+ * `ProgressTracker` ingests, which is what puts the run's turns, tokens, cost
+ * and tool actions on the board. The stderr line is `log.event`, not
+ * `log.debug` — a default-level run used to print exactly one line for a
+ * nine-minute stage, because `debug` is dropped unless `DEBUG` is set.
  */
 async function runRole(
   request: StageRunRequest,
   prompt: string,
+  emit: (line: unknown) => void,
 ): Promise<void> {
   // `buildStageRunnerConfig` owns the role's env strip and tool deny — see
   // stage-cli.ts for why they live behind a tested seam rather than inline here.
@@ -80,29 +147,94 @@ async function runRole(
     parentEnv: process.env,
   });
   const runner = new SdkAgentRunner(launch.config);
+  activeRunner = runner;
 
   log.info(
     TAG,
     `Running stage ${request.stageId} as role ${launch.role ?? "(none — fail-closed)"}`,
   );
-  for await (const event of runner.start({
-    // The Harmony agent-session id the runner LABELS its events with. It never
-    // enters the subagent's context: the prompt is built without it, and
-    // `RoleLaunch` has no field for it.
-    sessionId: request.sessionId,
-    cardId: request.cardId,
-    workspaceId: request.workspaceId,
-    prompt: launch.prompt,
-    cwd: launch.cwd,
-  })) {
-    if (event.kind === "error") {
-      log.warn(TAG, `subagent error: ${event.payload.message}`);
-    } else {
-      log.debug(TAG, `subagent ${event.kind}`);
+
+  // The motor's own clock. `stop("timeout")` runs the same cooperative
+  // abort + pgid escalation a driver's signal would, so the subagent dies with
+  // the motor instead of outliving it — and the `for await` below ends, which
+  // is what lets the run report the timeout instead of hanging on it.
+  const timeoutMs = stageTimeoutMs(process.env);
+  let timedOut = false;
+  const clock =
+    timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          log.warn(
+            TAG,
+            `stage ${request.stageId} exceeded ${timeoutMs}ms — stopping the subagent`,
+          );
+          void runner.stop("timeout");
+        }, timeoutMs)
+      : null;
+  clock?.unref?.();
+
+  try {
+    for await (const event of runner.start({
+      // The Harmony agent-session id the runner LABELS its events with. It never
+      // enters the subagent's context: the prompt is built without it, and
+      // `RoleLaunch` has no field for it.
+      sessionId: request.sessionId,
+      cardId: request.cardId,
+      workspaceId: request.workspaceId,
+      prompt: launch.prompt,
+      cwd: launch.cwd,
+    })) {
+      const relayed = relayAgentEvent(event);
+      if (relayed) emit(relayed);
+      if (event.kind === "error") {
+        log.warn(TAG, `subagent error: ${event.payload.message}`);
+      } else {
+        log.event(TAG, `subagent ${event.kind}`);
+      }
     }
+  } finally {
+    if (clock) clearTimeout(clock);
+    activeRunner = null;
+  }
+
+  if (timedOut) {
+    throw new Error(
+      `stage ${request.stageId} exceeded its ${timeoutMs}ms wall-clock bound and its subagent was stopped`,
+    );
   }
 }
 
+/**
+ * Write one protocol line to stdout, now. Every line the motor prints goes
+ * through here so "when a driver sees it" has exactly one answer: at the moment
+ * it happened (card #885).
+ *
+ * Total by design. A driver that went away leaves a closed pipe, and the write
+ * then fails EPIPE — which must not abort a stage run that is otherwise fine
+ * and whose evidence row is already persisted. Nobody is left to read the line,
+ * so there is nothing to salvage by failing here.
+ *
+ * The `try` alone does not deliver that. A pipe write is synchronous on Windows
+ * and Linux, where EPIPE arrives as a throw and is caught here — but it is
+ * ASYNCHRONOUS on macOS, where it arrives as an `'error'` event instead and
+ * would go unhandled. Hence the stream handlers installed below. That path
+ * matters far more since #885: stdout now carries thousands of lines during a
+ * run rather than four at the end of it.
+ */
+function emitLine(line: unknown): void {
+  try {
+    process.stdout.write(`${JSON.stringify(line)}\n`);
+  } catch {
+    // Deliberately swallowed — see above.
+  }
+}
+
+// The async half of the same contract: an EPIPE on a macOS pipe surfaces here,
+// not as a throw, and an unhandled stream 'error' would take the motor down
+// mid-stage over an audience that already left.
+process.stdout.on("error", () => {});
+process.stderr.on("error", () => {});
+
 async function main(): Promise<void> {
   const parsed = parseStageRunArgs(process.argv.slice(2));
   if (!parsed.ok) {
@@ -192,10 +324,13 @@ async function main(): Promise<void> {
   };
 
   const result = await runStage(request, {
+    // Flush every protocol event when it happens (card #885). `runStage` still
+    // accumulates them for the final `result` line — this is the live copy.
+    emit: emitLine,
     // Already resolved above, because the stage's ROLE and prompt come off the
     // same pinned def and have to be known before the subagent launches.
     resolveGate: async () => pinned.gate,
-    runRole: (req) => runRole(req, prompt),
+    runRole: (req) => runRole(req, prompt, emitLine),
     collect: async (req, gate) => {
       const registry = buildGateCollectorRegistry({
         build: {
@@ -235,10 +370,9 @@ async function main(): Promise<void> {
     },
   });
 
-  for (const event of result.events) {
-    process.stdout.write(`${JSON.stringify(event)}\n`);
-  }
-
+  // `result.events` is NOT reprinted here: `emit` above already wrote each one
+  // at the moment it happened, and a second pass would duplicate every line for
+  // a driver that parses the stream.
   if (result.evidence && pinned.gate) {
     const context: GateEvidenceContext = {
       cardId,
@@ -255,12 +389,23 @@ async function main(): Promise<void> {
     await client.recordStageGateEvidence(
       toStageGateEvidenceInsert(context, result.evidence),
     );
-    process.stdout.write(
-      `${JSON.stringify({ type: "gate_verdict", passed: evaluation.passed, findings: evaluation.findings })}\n`,
-    );
+    emitLine({
+      type: "gate_verdict",
+      passed: evaluation.passed,
+      findings: evaluation.findings,
+    });
   }
 
-  process.stdout.write(`${JSON.stringify({ type: "result", ...result })}\n`);
+  emitLine({ type: "result", ...result });
+}
+
+// Installed BEFORE main runs: a driver that signals during argument parsing or
+// the first API call must still get the motor's error protocol rather than a
+// silent signal death (card #885).
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.on(signal, () => {
+    void shutdown(signal);
+  });
 }
 
 main().catch((err: unknown) => {

package/src/confine-to-repo.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import {
+  confineToRepo,
+  decideConfinedTool,
+  isInsideTree,
+} from "./confine-to-repo.js";
+
+const ROOT = "/Users/dev/repo";
+
+function decide(tool: string, input: Record<string, unknown>) {
+  return decideConfinedTool(ROOT, tool, input);
+}
+
+describe("isInsideTree", () => {
+  it("accepts the root itself and anything under it", () => {
+    expect(isInsideTree(ROOT, ROOT)).toBe(true);
+    expect(isInsideTree(ROOT, `${ROOT}/src/index.ts`)).toBe(true);
+    expect(isInsideTree(ROOT, `${ROOT}/a/b/c/d.ts`)).toBe(true);
+  });
+
+  it("rejects a sibling whose name merely starts with the root", () => {
+    // The separator check is the whole point: without it `/Users/dev/repo-secrets`
+    // reads as inside `/Users/dev/repo`.
+    expect(isInsideTree(ROOT, "/Users/dev/repo-secrets/.env")).toBe(false);
+    expect(isInsideTree(ROOT, "/Users/dev/repository/x")).toBe(false);
+  });
+
+  it("rejects a parent and an unrelated tree", () => {
+    expect(isInsideTree(ROOT, "/Users/dev")).toBe(false);
+    expect(isInsideTree(ROOT, "/etc/passwd")).toBe(false);
+  });
+
+  it("normalises traversal before comparing", () => {
+    expect(isInsideTree(ROOT, `${ROOT}/../repo/src/a.ts`)).toBe(true);
+    expect(isInsideTree(ROOT, `${ROOT}/../../etc/passwd`)).toBe(false);
+  });
+});
+
+describe("decideConfinedTool", () => {
+  it("allows a read inside the tree", () => {
+    expect(decide("Read", { file_path: `${ROOT}/src/index.ts` })).toEqual({
+      behavior: "allow",
+    });
+  });
+
+  it("resolves a relative path against the repo, not process.cwd()", () => {
+    // The daemon's own cwd may be somewhere else entirely.
+    expect(decide("Read", { file_path: "src/index.ts" })).toEqual({
+      behavior: "allow",
+    });
+    expect(decide("Read", { file_path: "../../.ssh/id_rsa" }).behavior).toBe(
+      "deny",
+    );
+  });
+
+  // --- The paths this exists to close. ---
+
+  it("denies the operator's credential directory", () => {
+    const r = decide("Read", {
+      file_path: "/Users/dev/.harmony-mcp/config.json",
+    });
+    expect(r.behavior).toBe("deny");
+  });
+
+  it("denies an ssh key", () => {
+    expect(
+      decide("Read", { file_path: "/Users/dev/.ssh/id_rsa" }).behavior,
+    ).toBe("deny");
+  });
+
+  it("denies traversal out of the tree", () => {
+    expect(
+      decide("Read", { file_path: `${ROOT}/../../.aws/credentials` }).behavior,
+    ).toBe("deny");
+  });
+
+  it("denies a sibling directory that shares the root's prefix", () => {
+    expect(
+      decide("Read", { file_path: "/Users/dev/repo-secrets/.env" }).behavior,
+    ).toBe("deny");
+  });
+
+  it("names the refused path so the denial is legible", () => {
+    const r = decide("Read", { file_path: "/etc/passwd" });
+    expect(r.behavior).toBe("deny");
+    if (r.behavior === "deny") expect(r.message).toContain("/etc/passwd");
+  });
+
+  // --- Every read-only tool, and every argument each can carry. ---
+
+  it("checks Grep and Glob paths too", () => {
+    expect(decide("Grep", { path: `${ROOT}/src` })).toEqual({
+      behavior: "allow",
+    });
+    expect(decide("Grep", { path: "/etc" }).behavior).toBe("deny");
+    expect(decide("Glob", { path: "/Users/dev" }).behavior).toBe("deny");
+  });
+
+  it("checks every path argument a Read can carry", () => {
+    expect(decide("Read", { path: "/etc/hosts" }).behavior).toBe("deny");
+    expect(decide("Read", { notebook_path: "/etc/x.ipynb" }).behavior).toBe(
+      "deny",
+    );
+  });
+
+  it("allows a pathless call, which defaults to the session cwd", () => {
+    // Grep with no `path` searches cwd — which IS the confined tree.
+    expect(decide("Grep", { pattern: "foo" })).toEqual({ behavior: "allow" });
+    expect(decide("Glob", { pattern: "**/*.ts" })).toEqual({
+      behavior: "allow",
+    });
+  });
+
+  it("ignores a non-string or empty path rather than crashing", () => {
+    expect(decide("Read", { file_path: 42 })).toEqual({ behavior: "allow" });
+    expect(decide("Read", { file_path: "" })).toEqual({ behavior: "allow" });
+    expect(decide("Read", { file_path: null })).toEqual({ behavior: "allow" });
+  });
+
+  it("denies any tool it does not recognise", () => {
+    // Fails closed: an unrecognised tool means the allow-list drifted or the
+    // model reached for something this spawn should not have.
+    expect(decide("Bash", { command: "cat /etc/passwd" }).behavior).toBe(
+      "deny",
+    );
+    expect(decide("Write", { file_path: `${ROOT}/x.ts` }).behavior).toBe(
+      "deny",
+    );
+    expect(decide("Edit", { file_path: `${ROOT}/x.ts` }).behavior).toBe("deny");
+    expect(decide("WebFetch", { url: "https://x" }).behavior).toBe("deny");
+  });
+});
+
+describe("confineToRepo", () => {
+  it("returns the async shape the SDK expects", async () => {
+    const handler = confineToRepo(ROOT);
+    await expect(
+      handler("Read", { file_path: `${ROOT}/a.ts` }),
+    ).resolves.toEqual({ behavior: "allow" });
+    await expect(
+      handler("Read", { file_path: "/etc/passwd" }),
+    ).resolves.toMatchObject({ behavior: "deny" });
+  });
+});

package/src/confine-to-repo.ts

@@ -0,0 +1,113 @@
+/**
+ * Confine a read-only spawn to one directory tree.
+ *
+ * ## Why a handler and not a permission string
+ *
+ * The obvious move is a scoped rule in `allowedTools` — `Read(/**)` and friends.
+ * The Agent SDK documents `allowedTools` as a list of tool NAMES ("To restrict
+ * which tools are available, use the `tools` option instead"), so a rule-shaped
+ * entry there most likely matches no tool at all. That failure is silent and
+ * expensive: the tool is denied, the preflight returns no verdict, `sizeRun`
+ * answers `null`, and the daemon degrades to the policy fallback forever with
+ * nothing in the logs to say the sizing step stopped working.
+ *
+ * `canUseTool` is documented to run before each tool execution and receives the
+ * tool's INPUT, so the path can be checked directly. It is an ordinary function,
+ * which means the rule is unit-testable rather than a string whose semantics we
+ * would be guessing at.
+ *
+ * ## What it is for
+ *
+ * The pickup sizing preflight reads the operator's PRIMARY checkout, not a
+ * disposable worktree — the card's worktree does not exist when the model has to
+ * be chosen. Its prompt is built from card text anyone in the workspace can
+ * write. Denying the credential directory by name closes the worst path, but it
+ * is a blocklist: a repo-root `.env`, an `~/.ssh` key, or anything else the
+ * daemon's user can read stays reachable. This inverts that into an allowlist —
+ * inside the tree, or denied.
+ *
+ * Prompt-level containment (JSON-encoded card data) makes injection harder; this
+ * is what bounds it when that fails.
+ */
+import { isAbsolute, resolve, sep } from "node:path";
+
+/** The result shape the Agent SDK's `canUseTool` must return. */
+export type ConfineDecision =
+  | { behavior: "allow" }
+  | { behavior: "deny"; message: string };
+
+/**
+ * Where each read-only tool carries the path it wants to touch.
+ *
+ * A tool absent from this map is denied outright rather than allowed: this
+ * guards a spawn whose allow-list is meant to be exactly these three, so an
+ * unrecognised tool means either the allow-list drifted or the model reached
+ * for something it should not have. Failing closed is the honest answer to
+ * "I do not know what this tool would do".
+ */
+const PATH_ARG_BY_TOOL: Record<string, readonly string[]> = {
+  Read: ["file_path", "path", "notebook_path"],
+  Grep: ["path"],
+  Glob: ["path"],
+};
+
+/** Is `target` inside `root` (or root itself)? */
+export function isInsideTree(root: string, target: string): boolean {
+  const normalizedRoot = resolve(root);
+  const normalizedTarget = resolve(target);
+  if (normalizedTarget === normalizedRoot) return true;
+  // The separator matters: without it `/repo-secrets` reads as inside `/repo`.
+  return normalizedTarget.startsWith(normalizedRoot + sep);
+}
+
+/**
+ * Decide one tool call. Pure, so the policy is testable without a spawn.
+ *
+ * A tool with no path argument is allowed: `Grep` and `Glob` default to the
+ * session's `cwd`, which IS the tree being confined to. A relative path is
+ * resolved against that same root rather than `process.cwd()`, which may be
+ * somewhere else entirely in the daemon.
+ */
+export function decideConfinedTool(
+  repoRoot: string,
+  toolName: string,
+  input: Record<string, unknown>,
+): ConfineDecision {
+  const pathArgs = PATH_ARG_BY_TOOL[toolName];
+  if (!pathArgs) {
+    return {
+      behavior: "deny",
+      message: `${toolName} is not available to this run.`,
+    };
+  }
+
+  for (const key of pathArgs) {
+    const value = input[key];
+    if (typeof value !== "string" || value.length === 0) continue;
+    const candidate = isAbsolute(value) ? value : resolve(repoRoot, value);
+    if (!isInsideTree(repoRoot, candidate)) {
+      return {
+        behavior: "deny",
+        message: `${toolName} may only read inside the repository. Refused: ${value}`,
+      };
+    }
+  }
+
+  return { behavior: "allow" };
+}
+
+/**
+ * Build the `canUseTool` handler for a spawn confined to `repoRoot`.
+ *
+ * Kept separate from {@link decideConfinedTool} so the policy stays synchronous
+ * and testable while the SDK gets the async shape it expects.
+ */
+export function confineToRepo(
+  repoRoot: string,
+): (
+  toolName: string,
+  input: Record<string, unknown>,
+) => Promise<ConfineDecision> {
+  return async (toolName, input) =>
+    decideConfinedTool(repoRoot, toolName, input);
+}

package/src/gate-config-error.ts

@@ -1,73 +1,23 @@
 /**
- * The "this gate cannot be measured as configured" marker (card #823).
+ * Re-export of the "gate cannot be measured as configured" marker (#823), which
+ * now lives in `@harmony/shared` (`gateConfigError.ts` — read its module doc for
+ * the whole rule; card #914 moved it).
  *
- * A gate that reports `blocked` says only that no measurement exists. Two very
- * different situations produce it, and the advancement engine must not treat them
- * alike:
+ * It moved because the marker is a persistence contract on
+ * `stage_gate_evidence.structured` with readers on three runtimes: the harness
+ * collector writes it, the daemon's `stage-advance.ts` holds on it, and the Deno
+ * edge's `decideAdvance` now reads it so the board can tell a misconfigured gate
+ * apart from an unmet one. The edge cannot import the harness (dependency
+ * direction is agent → harness → shared), and a second spelling of the key in the
+ * edge is the per-path drift #495 forbids.
  *
- *   - **The measurement failed.** The command exited non-zero, timed out, or
- *     printed something unparsable. A re-run can genuinely change the outcome —
- *     the tool may be flaky, the branch may be fixed by the next attempt — so this
- *     keeps the existing retry path (`handleGateUnmet`).
- *   - **The gate is misconfigured.** The metric name is undeclared, the
- *     declaration carries no `command`, or its `parse` mode is unknown. Nothing
- *     ran and nothing ever will: the inputs are static config, so attempt N+1
- *     computes exactly the same answer as attempt 1. Re-running costs a full
- *     Claude implementation run each time and cannot help.
- *
- * Before this marker existed, both routed into the generic "gate unmet → re-run
- * this stage" path, so a typo'd metric name burned the card's whole `maxAttempts`
- * budget (and a converge loop's whole iteration budget) before holding. The
- * collector now tags the config-defect blocks, and `stage-advance.ts` holds on
- * them immediately with the attempt rolled back.
- *
- * The marker is a plain own key on the evidence's `structured` doc, so it survives
- * the round-trip every other field takes: `gateEvaluate` echoes `structured` into
- * its `GateEvaluation` verbatim, and `stage_gate_evidence.structured` persists it
- * for the board/edge to read later. It is deliberately NOT part of the gate
- * predicate surface — `blockedDetail` composes the human-facing finding from
- * `structured.reason` alone, so adding this key changes no verdict text.
- *
- * Fail-safe by omission: evidence without the key reads as retryable, which is the
- * pre-#823 behavior. A collector opts a block IN to the hold-immediately path; it
- * can never opt one out by accident.
- */
-
-/** Own key on `GateEvidence.structured` marking a block as a configuration defect. */
-export const GATE_CONFIG_ERROR_KEY = "configError";
-
-/** The structured fragment a collector spreads into config-defect `blocked` evidence. */
-export const GATE_CONFIG_ERROR_MARK: Readonly<Record<string, unknown>> =
-  Object.freeze({ [GATE_CONFIG_ERROR_KEY]: true });
-
-/** The minimal evaluation shape this predicate reads — structurally a `GateEvaluation`. */
-interface EvaluationLike {
-  passed: boolean;
-  structured: Record<string, unknown>;
-}
-
-/**
- * The reason a gate cannot be measured as configured, or `null` when this is a
- * normal (retryable) verdict. PURE + TOTAL — never throws, so a malformed
- * structured doc degrades to "retryable" rather than crashing the engine.
- *
- * A *passing* evaluation is never a config error: `gateEvaluate` cannot pass
- * blocked evidence, so a marked-and-passed evaluation would mean the marker was
- * forged into a passing doc. Reading `passed` first makes that unreachable instead
- * of merely unlikely.
+ * This file stays as the harness's own surface: `@gethmy/harness` exports these
+ * three names (`packages/harmony-agent/src/stage-advance.ts` and the motor-driver
+ * tests import them from the published package), so re-exporting keeps every
+ * existing import path working with no consumer change.
  */
-export function gateConfigErrorReason(
-  evaluation: EvaluationLike | null | undefined,
-): string | null {
-  if (!evaluation || evaluation.passed) return null;
-  const structured = evaluation.structured;
-  if (!structured || typeof structured !== "object") return null;
-  if (!Object.hasOwn(structured, GATE_CONFIG_ERROR_KEY)) return null;
-  if ((structured as Record<string, unknown>)[GATE_CONFIG_ERROR_KEY] !== true) {
-    return null;
-  }
-  const reason = (structured as Record<string, unknown>).reason;
-  return typeof reason === "string" && reason.trim().length > 0
-    ? reason.trim()
-    : "the gate cannot be measured as configured";
-}
+export {
+  GATE_CONFIG_ERROR_KEY,
+  GATE_CONFIG_ERROR_MARK,
+  gateConfigErrorReason,
+} from "@harmony/shared";

package/src/harmony-client.ts

@@ -52,6 +52,8 @@ export type StageCardPin = Pick<
 
 /** The oracle payload `POST /stage-oracle/fetch` returns (camelCase, edge-side). */
 interface OracleResponse {
+  /** The row id — absent from pre-#927 deployments, so optional here. */
+  id?: string | null;
   path: string;
   content: string;
   runnerHint?: string | null;
@@ -162,6 +164,7 @@ export class HarmonyClient {
     }
     const body = (await response.json()) as OracleResponse;
     return {
+      id: body.id ?? null,
       path: body.path,
       content: body.content,
       runnerHint: body.runnerHint ?? null,