@gethmy/harness 1.0.0 → 1.1.0

package/README.md

@@ -11,10 +11,15 @@ It deliberately does **not** decide anything. Harmony routes and advances;
 `gateEvaluate` in `@harmony/shared` turns evidence into a verdict. The motor
 never routes, never judges, never pushes.
 
-A *driver* invokes it. Today the drivers are `@gethmy/agent` (unattended) and the
+A *driver* invokes it. The drivers are `@gethmy/agent` (unattended) and the
 `hmy` skill (interactive). Installing this package on its own is useful only if
 you are building a driver.
 
+The full chain — bind, drive, gate, advance — is exercised end to end by
+`e2e/planted-bug.e2e.ts` (`bun run e2e`). It spends real agent tokens against a
+real Harmony API and a real Claude Code login, so it runs on demand only,
+never in CI.
+
 ## Prerequisites
 
 - [Node.js](https://nodejs.org) >= 20 or [Bun](https://bun.sh) >= 1.0

package/dist/cli.js

@@ -2752,15 +2752,50 @@ function assertStageIsAgentRunnable(stage) {
     return;
   throw new Error(`stage "${stage.id}" ("${stage.name}") is owned by "${stage.owner}" — refusing to run a stage a human owns`);
 }
+var STAGE_SCOPE_LINE = "Do ONLY the work of this stage. Other stages of this card belong to other runs — do not start their work, and do not undo it.";
+function oracleWriteAddendum(input) {
+  return [
+    "## Oracle upload — author duty",
+    "",
+    "After writing the hidden acceptance test, upload it as the oracle for the gated downstream stage. POST it yourself; there is no MCP tool for this:",
+    "",
+    "    POST $HARMONY_API_URL/v1/stage-oracle",
+    "    Headers: x-api-key: $HARMONY_API_KEY, Content-Type: application/json",
+    "",
+    "Body (JSON):",
+    "```json",
+    JSON.stringify({
+      cardId: input.cardId,
+      sessionId: input.sessionId,
+      targetStageId: input.targetStageId,
+      path: "oracle/<name>.test.ts",
+      content: "<the full test file>",
+      runnerHint: "bun"
+    }, null, 2),
+    "```",
+    "",
+    "Constraints: `path` is repo-relative ([A-Za-z0-9._-] per segment, no `..`, no dot-prefixed segment, no absolute path); `content` <= 100 KB; `runnerHint` is `bun` or `vitest`. Do NOT commit the oracle file — the motor places and removes it at the gated stage."
+  ].join(`
+`);
+}
 function buildStagePrompt(args) {
   const stageName = args.stage?.name ?? args.stageId;
   const entryAction = args.stage?.entry_action;
-  return [
+  const lines = [
     `## Playbook stage: ${stageName}`,
     `You are running the "${stageName}" stage for Harmony card ${args.cardId}.`,
     entryAction ? `Stage skill / entry action: \`${entryAction}\`. Follow that skill's method for this stage.` : "Read the card with the Harmony MCP tools (`harmony_get_card`) and do this stage's work for it.",
-    "Do only this stage's work, then stop. Do not move the card, do not advance the stage, and do not end your agent session — the driver that invoked this stage owns all three."
-  ].join(`
+    "Do only this stage's work, then stop. Do not move the card, do not advance the stage, and do not end your agent session — the driver that invoked this stage owns all three.",
+    STAGE_SCOPE_LINE
+  ];
+  if (args.stage?.role === "author" && args.oracleTargetStageId && args.sessionId) {
+    lines.push("", oracleWriteAddendum({
+      cardId: args.cardId,
+      sessionId: args.sessionId,
+      targetStageId: args.oracleTargetStageId
+    }));
+  }
+  return lines.join(`
 `);
 }
 function resolvePinnedStage(version, stageId) {
@@ -2783,6 +2818,18 @@ function resolvePinnedStage(version, stageId) {
     gate: normalizeGateSpec(resolution.stage.gate)
   };
 }
+function findOracleTargetStage(version, fromStageId) {
+  const stages = Array.isArray(version.steps) ? version.steps : [];
+  const from = stages.findIndex((s) => s.id === fromStageId);
+  if (from < 0)
+    return null;
+  for (const stage of stages.slice(from + 1)) {
+    const gate = normalizeGateSpec(stage.gate);
+    if (gate?.kind === "oracle_passed")
+      return stage.id;
+  }
+  return null;
+}
 function buildStageRunnerConfig(args) {
   const launch = buildRoleLaunch(args);
   return {
@@ -2868,7 +2915,13 @@ ${STAGE_RUN_USAGE}
     throw new Error(`refusing to run stage "${stageId}" for card ${cardId}: ${pinned.reason}`);
   }
   assertStageIsAgentRunnable(pinned.stage);
-  const prompt = buildStagePrompt({ cardId, stageId, stage: pinned.stage });
+  const prompt = buildStagePrompt({
+    cardId,
+    stageId,
+    stage: pinned.stage,
+    sessionId,
+    oracleTargetStageId: findOracleTargetStage(version, stageId)
+  });
   const request = {
     cardId,
     stageId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/harness",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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",
@@ -9,7 +9,8 @@
     ".": {
       "types": "./src/index.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "bin": {
     "harmony-harness": "dist/cli.js"
@@ -49,11 +50,12 @@
     "build": "rm -rf dist && bun build src/index.ts src/cli.ts --outdir dist --target node --external @supabase/supabase-js --external @gethmy/mcp --external \"@gethmy/mcp/*\" --external @anthropic-ai/claude-agent-sdk",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "npm run build",
-    "test": "vitest run"
+    "test": "vitest run",
+    "e2e": "bun e2e/planted-bug.e2e.ts"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.178",
-    "@gethmy/mcp": "2.22.0",
+    "@gethmy/mcp": "2.23.0",
     "@supabase/supabase-js": "2.95.3"
   },
   "devDependencies": {

package/src/cli.ts

@@ -38,6 +38,7 @@ import {
   assertStageIsAgentRunnable,
   buildStagePrompt,
   buildStageRunnerConfig,
+  findOracleTargetStage,
   parseMetricsAllowlist,
   parseStageRunArgs,
   resolvePinnedStage,
@@ -173,7 +174,13 @@ async function main(): Promise<void> {
   // accident.
   assertStageIsAgentRunnable(pinned.stage);
 
-  const prompt = buildStagePrompt({ cardId, stageId, stage: pinned.stage });
+  const prompt = buildStagePrompt({
+    cardId,
+    stageId,
+    stage: pinned.stage,
+    sessionId,
+    oracleTargetStageId: findOracleTargetStage(version, stageId),
+  });
 
   const request: StageRunRequest = {
     cardId,

package/src/stage-cli.ts

@@ -180,32 +180,107 @@ export function assertStageIsAgentRunnable(stage: PlaybookStageDef): void {
   );
 }
 
+/**
+ * Every stage's prompt carries this line: automatic driving runs one stage per
+ * invocation, and a stage's subagent otherwise has no way to know that the
+ * rest of the card's playbook is someone else's run, not unfinished work of
+ * its own to pick up or undo.
+ */
+const STAGE_SCOPE_LINE =
+  "Do ONLY the work of this stage. Other stages of this card belong to other runs — do not start their work, and do not undo it.";
+
+/**
+ * The author's oracle-upload procedure, appended to the prompt only for a
+ * stage whose role is `author` with a resolved oracle target. There is no MCP
+ * tool for this write (the oracle route requires the acting stage's role to
+ * normalize to `author` server-side — see `playbookStage.ts`), so the author
+ * must POST it directly; this is the one place that procedure is spelled out.
+ */
+function oracleWriteAddendum(input: {
+  cardId: string;
+  sessionId: string;
+  targetStageId: string;
+}): string {
+  return [
+    "## Oracle upload — author duty",
+    "",
+    "After writing the hidden acceptance test, upload it as the oracle for the gated downstream stage. POST it yourself; there is no MCP tool for this:",
+    "",
+    "    POST $HARMONY_API_URL/v1/stage-oracle",
+    "    Headers: x-api-key: $HARMONY_API_KEY, Content-Type: application/json",
+    "",
+    "Body (JSON):",
+    "```json",
+    JSON.stringify(
+      {
+        cardId: input.cardId,
+        sessionId: input.sessionId,
+        targetStageId: input.targetStageId,
+        path: "oracle/<name>.test.ts",
+        content: "<the full test file>",
+        runnerHint: "bun",
+      },
+      null,
+      2,
+    ),
+    "```",
+    "",
+    "Constraints: `path` is repo-relative ([A-Za-z0-9._-] per segment, no `..`, no dot-prefixed segment, no absolute path); `content` <= 100 KB; `runnerHint` is `bun` or `vitest`. Do NOT commit the oracle file — the motor places and removes it at the gated stage.",
+  ].join("\n");
+}
+
 /**
  * The subagent's prompt. Built from the stage's `entry_action` when the pinned
  * stage names one, otherwise from the card — in which case the agent is told to
  * read the card itself through the Harmony MCP tools, which every role keeps
  * (see runner.ts). The motor does not read board content to build this.
  *
- * The signature is the guard on what can leak: there is no parameter for the
- * agent-session id or for the oracle's path, and neither value is reachable
- * from here. The prompt is free text and the last remaining way to hand the
- * implementer either one.
+ * Every prompt carries {@link STAGE_SCOPE_LINE}. An `author` stage additionally
+ * gets the oracle-write procedure ({@link oracleWriteAddendum}), but only when
+ * BOTH `oracleTargetStageId` and `sessionId` are given — `sessionId` is the one
+ * value the author needs verbatim in the POST body, and omitting the addendum
+ * entirely when it is absent is deliberate: a body with a hole in it is worse
+ * than no addendum.
+ *
+ * The signature is still the guard on what can leak to an implementer: neither
+ * `sessionId` nor `oracleTargetStageId` reaches an implementer stage's prompt,
+ * because the addendum is gated on `role === "author"`.
  */
 export function buildStagePrompt(args: {
   cardId: string;
   stageId: string;
   stage: PlaybookStageDef | null;
+  /** Session id — the author needs it verbatim in the oracle POST body. */
+  sessionId?: string;
+  /** Id of the downstream stage gated by oracle_passed, from findOracleTargetStage. */
+  oracleTargetStageId?: string | null;
 }): string {
   const stageName = args.stage?.name ?? args.stageId;
   const entryAction = args.stage?.entry_action;
-  return [
+  const lines = [
     `## Playbook stage: ${stageName}`,
     `You are running the "${stageName}" stage for Harmony card ${args.cardId}.`,
     entryAction
       ? `Stage skill / entry action: \`${entryAction}\`. Follow that skill's method for this stage.`
       : "Read the card with the Harmony MCP tools (`harmony_get_card`) and do this stage's work for it.",
     "Do only this stage's work, then stop. Do not move the card, do not advance the stage, and do not end your agent session — the driver that invoked this stage owns all three.",
-  ].join("\n");
+    STAGE_SCOPE_LINE,
+  ];
+  if (
+    args.stage?.role === "author" &&
+    args.oracleTargetStageId &&
+    args.sessionId
+  ) {
+    lines.push(
+      "",
+      oracleWriteAddendum({
+        cardId: args.cardId,
+        sessionId: args.sessionId,
+        targetStageId: args.oracleTargetStageId,
+      }),
+    );
+  }
+  return lines.join("\n");
 }
 
 /**
@@ -261,6 +336,33 @@ export function resolvePinnedStage(
   };
 }
 
+/**
+ * The first stage AFTER `fromStageId` whose gate is `oracle_passed` — the
+ * stage the author's held test will grade. Null when none exists; the author
+ * addendum is then omitted and the prompt carries no oracle duty.
+ *
+ * Reads `version.steps` directly rather than through `readStageDefs` /
+ * `resolveStageDef`: those refuse a legacy (`steps_version !== 2`) snapshot
+ * outright, but this lookup only needs "is there a later stage with this
+ * gate" and degrades safely to `null` on any shape it does not recognize —
+ * `fromStageId` simply will not be found, and the loop below finds nothing.
+ */
+export function findOracleTargetStage(
+  version: PlaybookVersionDef,
+  fromStageId: string,
+): string | null {
+  const stages = Array.isArray(version.steps)
+    ? (version.steps as PlaybookStageDef[])
+    : [];
+  const from = stages.findIndex((s) => s.id === fromStageId);
+  if (from < 0) return null;
+  for (const stage of stages.slice(from + 1)) {
+    const gate = normalizeGateSpec(stage.gate);
+    if (gate?.kind === "oracle_passed") return stage.id;
+  }
+  return null;
+}
+
 /** A stage's subagent launch, in the two shapes `SdkAgentRunner` consumes. */
 export interface StageRunnerLaunch {
   /** The NORMALIZED role (`buildRoleLaunch`), never the raw input. */