@gethmy/harness 1.5.0 → 1.7.0

package/src/run-containment.ts

@@ -78,24 +78,85 @@
  * was found by a review round rather than by reading the code, and a residual
  * nobody wrote down is indistinguishable from one nobody saw.
  *
- *  - **Everything resolved through `spawnRunArgs` runs the run's own
- *    `package.json` scripts.** Six call sites, not four: `runBuild`,
- *    `runTests`, `runFormatFix` and `runLint` (`verification.ts`), plus the two
- *    `dev` servers — `runDeepReview` (`verification.ts`) and the review
- *    worker's own (`review-worker.ts`). Each executes `bun run <script>` from
- *    the worktree, which the run may rewrite, in the DAEMON process and outside
- *    the sandbox with network. All six now carry `containedEnv()`, so the
- *    secret-shaped variables are gone; the command itself is still the run's to
- *    choose. Closing that means running the repo's build somewhere the
- *    operator's credentials are not; that is `repair-sandbox.ts`'s problem shape
- *    and its own piece of work.
- *
- *    The count is in this bullet on purpose. The first version of this list
- *    named the four verification steps and stopped, and both dev servers then
- *    shipped with the daemon's whole environment while the changelog told users
- *    these commands run "without your credentials". `spawn-run-containment.test.ts`
- *    scans for the property instead of trusting this prose, because the residual
- *    is a completeness claim over CALL SITES and a hand-list has already lost it.
+ *  - **Egress from the two `dev` servers, plus the standalone harness CLI.**
+ *    #1036 closed the four verification steps AND the `build_green` gate
+ *    collector, which re-runs the same two scripts: `runBuild`, `runTests`,
+ *    `runFormatFix` and `runLint` run inside `repair-sandbox.ts`'s container
+ *    when `verification.sandboxImage` is set — worktree the only mount, no
+ *    network, no host fallback. #1037 took the same key and moved the two dev
+ *    servers in behind it: `runDeepReview`'s and the review worker's, both
+ *    through one `devServerLaunch`, so they can no longer be fixed one at a
+ *    time the way #988 fixed one and shipped the other.
+ *
+ *    **What is left of this bullet is egress, and only egress.** A dev server
+ *    exists to be connected to, so `--network=none` is not available to it: the
+ *    container publishes `127.0.0.1:<port>` on a default bridge, which gives it
+ *    a route out. That is a strictly weaker property than the four verification
+ *    steps get, and it is named here rather than left to be inferred from a
+ *    missing flag. Two shapes that would have kept both halves were measured on
+ *    the daemon's own platform and neither works — `--internal` drops the
+ *    published port along with the egress, and a bridge with
+ *    `enable_ip_masquerade=false` keeps the egress and additionally reaches the
+ *    operator's own host services. `devServerSandboxArgs` carries the numbers.
+ *
+ *    What the container still takes is the part that made the command worth
+ *    attacking: the run's `dev` script no longer executes in the daemon
+ *    process, no longer reads `~/.ssh` or `~/.harmony-mcp/config.json`, and no
+ *    longer holds a capability. What egress can still carry out is the
+ *    worktree, which is the run's own output.
+ *
+ *    The containment is **opt-in**, so on a host with no `sandboxImage` all six
+ *    commands still run in the daemon process, with `containedEnv()` as the
+ *    only bound. That is a deliberate asymmetry with this module's own
+ *    containment, which defaults on: the SDK sandbox is inside the CLI, whereas
+ *    a container needs a reachable Docker and an image carrying the repo's
+ *    toolchain.
+ *
+ *    One correction to the severity this was first written with. The dev
+ *    servers were called the rare path because `verification.deepReview`
+ *    defaults to false. That is true of `runDeepReview` and **false of the
+ *    review worker's**, which has no such gate and no toolchain check:
+ *    `review.enabled` defaults to true, so that server starts on every card
+ *    that reaches Review. Of the two, the one on the default path was the one
+ *    described as conditional.
+ *
+ *    `packages/harmony-harness/src/cli.ts` used to build the same collector and
+ *    pass no image, because the motor held no operator config of its own. #1021
+ *    gave it `--sandbox-image`, threaded from the daemon's same
+ *    `verification.sandboxImage`, so a daemon-driven stage now contains the
+ *    `build_green` gate and the HELD TEST alike. A person running the CLI by
+ *    hand against their own checkout still passes no image and still runs on
+ *    their host — a different threat model, and named here rather than left to
+ *    be rediscovered.
+ *
+ *    The count is in this bullet on purpose, and it has now been wrong three
+ *    times. The first version named the four verification steps and stopped, and
+ *    both dev servers then shipped with the daemon's whole environment while the
+ *    changelog told users these commands run "without your credentials". The
+ *    second version — #1036's own — said "the two dev servers" while the
+ *    `build_green` gate ran the worktree's script on the host for any operator
+ *    who had set an image precisely to stop that. The third omission was not a
+ *    missing NAME but a wrong SPELLING, which is worse: `review-worker.ts`'s dev
+ *    server carried `env: containedEnv()` on a `spawnInGroup` call, and
+ *    `spawnInGroup` merges `process.env` back over whatever `env` it is handed —
+ *    so that strip removed nothing for as long as it shipped, and the source
+ *    scan reported the property as held because the scan read the spelling.
+ *    Every one of the three was caught by a reader, not by a gate.
+ *
+ *    A fourth was caught by the gate, which is the point of having one. #1037
+ *    consolidated the two dev servers behind `devServerLaunch` — the right move,
+ *    and it instantly took `review-worker.ts` OUT of the scan, because the file
+ *    stopped containing the word `spawnRunArgs` and that list was how the walk
+ *    chose which files to open. The property assertion would have gone on
+ *    passing over the very file whose inert strip had just been fixed. The scan
+ *    now names both dev-server files explicitly, so a file leaving the walk
+ *    fails instead of quietly shrinking the count.
+ *
+ *    `spawn-run-containment.test.ts` is therefore spawn-function aware, covers
+ *    the held-test spawn, and checks its own coverage; and
+ *    `verification-sandbox.test.ts` asserts that a configured image takes the
+ *    four out of this process entirely — because the residual is a completeness
+ *    claim over CALL SITES and a hand-list has already lost it twice.
  *  - **The MCP surface.** The sandbox governs commands. MCP stdio servers are
  *    hosted by the CLI and are not sandboxed, so `mcp__harmony__*` is bounded by
  *    the tool allow-list and the daemon-owned denials (#525/#576), not by this.
@@ -578,6 +639,53 @@ export function containedEnv(
   return out;
 }
 
+/**
+ * The model credentials {@link containedEnv} deliberately KEEPS, named so a
+ * spawn that is not a model call can drop them.
+ *
+ * They are in {@link KEEP_ENV_KEYS} because an implement run IS the model call
+ * — stripping them stops the run existing rather than containing it. Nothing
+ * generalizes from that: it is a statement about one spawn.
+ */
+const MODEL_CREDENTIAL_KEYS: readonly string[] = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+];
+
+/**
+ * Environment keys the HELD-TEST run must not carry (#1021): everything
+ * {@link secretEnvKeysToStrip} names, plus the model credentials.
+ *
+ * A held test is arbitrary code an untrusted `author` subagent wrote, and
+ * before this the oracle spawn passed no `env` at all — so it inherited the
+ * daemon's entire environment, `HARMONY_API_KEY` and `ANTHROPIC_API_KEY`
+ * included. The first class is `secretEnvKeysToStrip`'s. The second is kept by
+ * `containedEnv` on purpose, which is right for the spawn that one was written
+ * for and wrong here: a test file has no model call to make, so a live billing
+ * credential in its environment is spend and reach it has no use for.
+ *
+ * **KEY NAMES, not an environment, and that is the whole point.** The oracle
+ * spawns through `spawnInGroup`, which MERGES `process.env` back on top of any
+ * `env` it is handed — so passing a narrowed object there strips nothing. The
+ * removal has to be a `stripEnvKeys` DELETE. `sdk-agent-runner.ts` records the
+ * same trap for the same reason; `review-worker.ts` shipped the inert spelling.
+ *
+ * This is a REDUCTION, not the boundary — the same thing #988 said about
+ * `containedEnv()` and for the same reason: the command still runs as the
+ * operator and can read `~/.ssh` and `~/.harmony-mcp/config.json` off disk. The
+ * boundary is the container, which `oracle.ts` uses when
+ * `verification.sandboxImage` is configured. This is what the DEFAULT path gets,
+ * and the default path is the one most operators are on.
+ */
+export function heldTestEnvKeysToStrip(
+  parentEnv: Record<string, string | undefined> = process.env,
+): string[] {
+  return [
+    ...new Set([...secretEnvKeysToStrip(parentEnv), ...MODEL_CREDENTIAL_KEYS]),
+  ];
+}
+
 /**
  * Git metadata the contained run may not write — the escape the worktree grant
  * would otherwise hand it.
@@ -1028,8 +1136,36 @@ export const IMPLEMENT_ALLOWED_DOMAINS: readonly string[] = [
  * lockstep with its own release, and a contained run reaching for `@latest`
  * would fetch a version this daemon was never tested against — over a network
  * the containment then has to allow the registry for.
+ *
+ * ## `run` — how the agent inside the run learns its own session (#1035)
+ *
+ * A daemon-run agent cannot call `harmony_start_agent_session`: the daemon owns
+ * the lifecycle and denies the tool (`STAGE_DAEMON_OWNED_TOOLS`). So the MCP
+ * process it talks to used to know nothing about the run it serves, and
+ * `harmony_add_comment` had to leave the attribution to the API — which could
+ * only ask "does this ACCOUNT have a session on this card?", true of every
+ * concurrent run of the same account. That is the borrowed attribution measured
+ * on card #1029.
+ *
+ * Passing `run` closes it at the source: the run's `card_agent_context` id
+ * reaches the MCP server as its own environment, so the comment names the
+ * session instead of the server inferring one.
+ *
+ * **The `env` field, not the spawn environment, and that is the point.** The
+ * CLI hosts a stdio MCP server with `{...its own env, ...this env}` — measured
+ * 2026-09-05 against `claude 2.1.261` with a probe server that dumped its
+ * environment: both halves arrive, and `PATH`/`HOME` survive. Putting the id
+ * here rather than on the run's own spawn keeps it out of the model's shell, so
+ * the agent cannot read it, echo it, or pass a different one.
+ *
+ * An OLDER `@gethmy/mcp` — one published before #1035 — simply ignores two
+ * unknown environment keys, so this is safe to ship ahead of the pin bump. A
+ * CLI FLAG would not be: `cli.js serve` parses with commander, which exits 1 on
+ * an unknown option, and the run would lose `mcp__harmony__*` entirely.
  */
-export function harmonyMcpServer(): Record<string, McpServerConfig> {
+export function harmonyMcpServer(
+  run?: HarmonyMcpRunBinding,
+): Record<string, McpServerConfig> {
   const require = createRequire(import.meta.url);
   // The package's `exports` map publishes "." → dist/index.js and no bin
   // subpath, so the CLI is named as its sibling rather than resolved directly.
@@ -1041,10 +1177,37 @@ export function harmonyMcpServer(): Record<string, McpServerConfig> {
       // and no chance of a different Node than the one that was tested.
       command: process.execPath,
       args: [cli, "serve"],
+      // Both keys or neither: the card id is what lets the MCP server tell
+      // "this comment is on the card I am running" from "this comment is on a
+      // neighbour", and without it the session id would be claimed on every
+      // card the run comments on.
+      ...(run
+        ? {
+            env: {
+              HARMONY_AGENT_CARD_ID: run.cardId,
+              HARMONY_AGENT_SESSION_ID: run.agentSessionId,
+            },
+          }
+        : {}),
     },
   };
 }
 
+/**
+ * The run whose `card_agent_context` session the MCP server may claim (#1035).
+ *
+ * Both fields are required together — see {@link harmonyMcpServer}. A caller
+ * that has no live session (a verification or review spawn that never opened
+ * one) passes nothing, and the MCP server then posts sessionless rather than
+ * borrowing.
+ */
+export interface HarmonyMcpRunBinding {
+  /** `cards.id` — the card this run holds its session on. */
+  cardId: string;
+  /** `card_agent_context.id` — the run's own session row. */
+  agentSessionId: string;
+}
+
 /** The fields {@link implementRunContainment} contributes to an `SdkRunnerConfig`. */
 export interface RunContainment {
   sandbox: SandboxSettings;
@@ -1087,6 +1250,12 @@ export function implementRunContainment(args: {
    * it says instead of being auto-approved because the run is sandboxed.
    */
   readOnly?: boolean;
+  /**
+   * The board session this spawn IS, so its agent can name it on a comment
+   * instead of the API inferring one (#1035). Omit when the spawn holds no
+   * session — the agent then comments sessionless, which is the honest answer.
+   */
+  run?: HarmonyMcpRunBinding;
 }): RunContainment {
   // Inside the builder rather than at the call sites, so a future spawn cannot
   // adopt the containment and skip the check that makes it hold. Throws — see
@@ -1209,7 +1378,7 @@ export function implementRunContainment(args: {
     // Handed back explicitly, because the line above took it away — see
     // `harmonyMcpServer`. Without this the run loses `mcp__harmony__*` and can
     // no longer report its own progress.
-    mcpServers: harmonyMcpServer(),
+    mcpServers: harmonyMcpServer(args.run),
     // Paired with the two above: the run sees only the server declared to it,
     // and no MCP config the operator happens to have registered for themselves.
     strictMcpConfig: true,
@@ -1268,6 +1437,11 @@ export function implementRunContainmentCliArgs(args: {
    * it says instead of being auto-approved because the run is sandboxed.
    */
   readOnly?: boolean;
+  /**
+   * The board session this spawn IS (#1035) — travels inside `--mcp-config`,
+   * the same way the SDK path travels it inside `mcpServers`.
+   */
+  run?: HarmonyMcpRunBinding;
 }): string[] {
   const containment = implementRunContainment(args);
   return [

package/src/stage-cli.ts

@@ -26,14 +26,19 @@ import { buildRoleLaunch, envKeysDroppedByLaunch } from "./runner.js";
 import type { SdkRunnerConfig } from "./sdk-agent-runner.js";
 
 export const STAGE_RUN_USAGE =
-  "usage: harmony-harness stage run --card <id> --stage <id> --workspace <id> --repo <path> --session <id> [--metrics <json-path>]";
+  "usage: harmony-harness stage run --card <id> --stage <id> --workspace <id> --repo <path> --session <id> [--metrics <json-path>] [--sandbox-image <image>]";
 
 /** The five identifiers one stage run needs. Every one is required.
- * `metricsPath` is the one optional input: a JSON file holding the DRIVER's
- * metric allowlist for `custom` gates (same shape as the daemon operator's
- * `agent.playbooks.metrics`). The motor itself stays config-free — without the
- * flag a `custom` gate reports "metric not declared" and blocks, exactly as
- * before. */
+ * `metricsPath` and `sandboxImage` are the optional inputs, and both carry the
+ * DRIVER's operator config into a motor that holds none of its own:
+ *  - `metricsPath` is a JSON file holding the metric allowlist for `custom`
+ *    gates (same shape as the daemon operator's `agent.playbooks.metrics`).
+ *    Without it a `custom` gate reports "metric not declared" and blocks,
+ *    exactly as before.
+ *  - `sandboxImage` is the daemon's `verification.sandboxImage` (#1021): the
+ *    container the held test and the gate's build/lint commands run in. Without
+ *    it both run in the motor's own process tree, which is what a person
+ *    running this CLI against their own checkout gets. */
 export interface StageRunArgs {
   cardId: string;
   stageId: string;
@@ -41,6 +46,7 @@ export interface StageRunArgs {
   repoPath: string;
   sessionId: string;
   metricsPath: string | null;
+  sandboxImage: string | null;
 }
 
 export type StageRunArgsResult =
@@ -78,14 +84,16 @@ export function parseStageRunArgs(argv: string[]): StageRunArgsResult {
     };
   }
 
-  const fields: Array<[Exclude<keyof StageRunArgs, "metricsPath">, string]> = [
+  const fields: Array<
+    [Exclude<keyof StageRunArgs, "metricsPath" | "sandboxImage">, string]
+  > = [
     ["cardId", "card"],
     ["stageId", "stage"],
     ["workspaceId", "workspace"],
     ["repoPath", "repo"],
     ["sessionId", "session"],
   ];
-  const args = { metricsPath: null } as StageRunArgs;
+  const args = { metricsPath: null, sandboxImage: null } as StageRunArgs;
   for (const [field, flag] of fields) {
     const value = readFlag(argv, flag);
     if (value === null) {
@@ -105,6 +113,22 @@ export function parseStageRunArgs(argv: string[]): StageRunArgsResult {
     }
     args.metricsPath = metricsPath;
   }
+
+  // Optional: --sandbox-image <image> (#1021). Same absent/valueless split as
+  // --metrics, and the refusal matters MORE here: a driver that passed the flag
+  // asked for the held test to run without its credentials in scope, and
+  // silently running it on the host would hand back exactly the exposure the
+  // flag exists to remove. There is no host fallback anywhere on this path.
+  if (argv.includes("--sandbox-image")) {
+    const sandboxImage = readFlag(argv, "sandbox-image");
+    if (sandboxImage === null) {
+      return {
+        ok: false,
+        message: "missing value for --sandbox-image <image>",
+      };
+    }
+    args.sandboxImage = sandboxImage;
+  }
   return { ok: true, args };
 }