harnery 0.26.0 → 0.27.0

package/dist/core/workflow/workspaces/reclaim.js

@@ -0,0 +1,88 @@
+/**
+ * Resolve a workspace stuck at `preserved_dirty` (ADR 0042).
+ *
+ * When a run ends with uncommitted work, the provider preserves the worktree
+ * rather than destroying the only copy of that work. That decision is correct,
+ * and until this existed it was also permanent: cleanup re-attempted, found the
+ * tree still dirty, preserved again, and incremented a counter. The only exit
+ * was to leave Harnery and remove the directory by hand, after which Harnery's
+ * records described a workspace that no longer existed.
+ *
+ * The shape of the fix is deliberate. Neither mode deletes anything directly.
+ * Each one makes the working tree *clean* by an explicit, named act, and then
+ * hands off to the ordinary cleanup path, which releases a clean workspace as it
+ * always has. So reclaim adds no second removal path that could diverge from the
+ * audited one, and a force-delete of live work exists nowhere in the codebase.
+ */
+import { existsSync } from "node:fs";
+import { git, gitMaybe } from "./git.js";
+/**
+ * Bring the worktree to a clean state so ordinary cleanup can release it.
+ *
+ * Returns `already_gone` rather than throwing when the directory has been
+ * removed out from under us. A workspace whose worktree no longer exists has
+ * effectively been reclaimed; treating that as an error is what produced an
+ * attempt counter that only ever went up.
+ */
+export function prepareReclaim(input) {
+    if (!existsSync(input.worktreePath)) {
+        return {
+            action: "already_gone",
+            detail: "the worktree directory is already gone; nothing to reclaim",
+        };
+    }
+    const status = gitMaybe(input.worktreePath, ["status", "--porcelain"]);
+    if (!status.ok) {
+        throw new Error(`cannot read worktree status for reclaim: ${status.err || "git failed"}`);
+    }
+    if (status.out.trim().length === 0) {
+        return { action: "already_clean", detail: "the worktree has no uncommitted changes" };
+    }
+    if (input.mode === "discard") {
+        // Ordered: reset drops tracked modifications, clean removes what reset
+        // cannot see. Running clean first would leave staged deletions behind.
+        git(input.worktreePath, ["reset", "--hard"]);
+        git(input.worktreePath, ["clean", "-fd"]);
+        return { action: "discarded", detail: "uncommitted changes were discarded on request" };
+    }
+    // Salvage onto a ref of its own, then put the checked-out branch back exactly
+    // where it was. Two reasons, both learned by doing it the obvious way first:
+    //
+    //  1. Cleanup DELETES the provider's workspace branch. Committing the salvage
+    //     there would have parked the work on a ref that the very next step
+    //     removes, leaving it unreachable and eventually collectable.
+    //  2. Cleanup pins the workspace ref's OID in a frozen intent and refuses when
+    //     it moves, which is a guard worth keeping. Advancing that branch turned
+    //     every reclaim into `blocked`.
+    //
+    // Committing and rewinding satisfies both: the tree ends clean, the workspace
+    // ref ends untouched, and the work lives on a ref cleanup has no reason to
+    // touch.
+    const before = git(input.worktreePath, ["rev-parse", "HEAD"]).trim();
+    git(input.worktreePath, ["add", "-A"]);
+    git(input.worktreePath, ["commit", "--no-verify", "-m", salvageMessage(input.runId)]);
+    const commit = git(input.worktreePath, ["rev-parse", "HEAD"]).trim();
+    const branch = salvageBranch(input.runId);
+    git(input.worktreePath, ["branch", "--force", branch, commit]);
+    git(input.worktreePath, ["reset", "--hard", before]);
+    return {
+        action: "salvaged",
+        branch,
+        commit,
+        detail: `salvaged to ${branch} at ${commit.slice(0, 12)}`,
+    };
+}
+/**
+ * `--no-verify` above is not a shortcut. A salvage commit is an archival act on
+ * an abandoned workspace, so a repository hook that rejects work in progress
+ * would convert "preserve the work" into "cannot preserve the work", which is
+ * the failure this whole path exists to prevent.
+ */
+function salvageMessage(runId) {
+    return `chore(workspace): salvage uncommitted work from run ${runId}`;
+}
+/** Named for the run rather than the workspace, because the run id is what an
+ * operator has in hand when they come looking for the work later. */
+export function salvageBranch(runId) {
+    return `harnery/salvage/${runId}`;
+}

package/dist/lib/tunnel/error-page.d.ts

@@ -0,0 +1,15 @@
+export interface TunnelErrorPageOptions {
+    kind: "access-denied" | "upstream-unavailable";
+    incidentId: string;
+    timestamp: string;
+    tunnelName: string;
+    method: string;
+    path: string;
+    clientIp: string;
+    cloudflareRay: string;
+    target?: string;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export declare function renderTunnelErrorPage(options: TunnelErrorPageOptions): string;
+//# sourceMappingURL=error-page.d.ts.map

package/dist/lib/tunnel/error-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-page.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/error-page.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,eAAe,GAAG,sBAAsB,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AA6BD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,CAwE7E"}

package/dist/lib/tunnel/error-page.js

@@ -0,0 +1,98 @@
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#039;");
+}
+function diagnosticText(options) {
+    const lines = [
+        `Tunnel incident: ${options.incidentId}`,
+        `Time: ${options.timestamp}`,
+        `Problem: ${options.kind}`,
+        `Tunnel: ${options.tunnelName}`,
+        `Request: ${options.method} ${options.path}`,
+        `Client IP: ${options.clientIp || "(not provided by proxy)"}`,
+        `Cloudflare Ray: ${options.cloudflareRay || "(not provided)"}`,
+    ];
+    if (options.target)
+        lines.push(`Upstream: ${options.target}`);
+    if (options.errorCode)
+        lines.push(`Error code: ${options.errorCode}`);
+    if (options.errorMessage)
+        lines.push(`Error: ${options.errorMessage}`);
+    return lines.join("\n");
+}
+export function renderTunnelErrorPage(options) {
+    const denied = options.kind === "access-denied";
+    const title = denied ? "This device is not allowed yet" : "The preview is temporarily offline";
+    const summary = denied
+        ? "The tunnel is running, but this device's public IP is not on its access list."
+        : "The public tunnel and access check are working, but the local preview server is not responding.";
+    const nextStep = denied
+        ? "Copy the diagnostic below and send it to the person running the tunnel. It includes the public IP that needs to be allowed."
+        : "Copy the diagnostic below and send it to the person running the tunnel. The incident ID can be matched to the server log.";
+    const diagnostic = diagnosticText(options);
+    const safeDiagnosticForScript = JSON.stringify(diagnostic).replaceAll("<", "\\u003c");
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="robots" content="noindex,nofollow">
+  <title>${escapeHtml(title)}</title>
+  <style>
+    :root { color-scheme: light; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+    * { box-sizing: border-box; }
+    body { margin: 0; min-height: 100vh; background: #f4f2ed; color: #17211c; display: grid; place-items: center; padding: 24px; }
+    main { width: min(100%, 720px); background: #fff; border: 1px solid #d8d4ca; border-radius: 18px; box-shadow: 0 18px 50px rgba(23, 33, 28, .10); overflow: hidden; }
+    .bar { height: 8px; background: ${denied ? "#b54708" : "#b42318"}; }
+    .content { padding: clamp(24px, 5vw, 48px); }
+    .eyebrow { margin: 0 0 10px; color: ${denied ? "#8a3708" : "#912018"}; font-size: 13px; font-weight: 750; letter-spacing: .09em; text-transform: uppercase; }
+    h1 { margin: 0; max-width: 18ch; font-size: clamp(30px, 7vw, 48px); line-height: 1.02; letter-spacing: -.04em; }
+    .summary { margin: 20px 0 10px; max-width: 58ch; font-size: 18px; line-height: 1.55; }
+    .next { margin: 0 0 24px; max-width: 62ch; color: #536058; line-height: 1.55; }
+    .diagnostic-wrap { position: relative; }
+    pre { margin: 0; padding: 18px; border: 1px solid #ccd2cd; border-radius: 12px; background: #111814; color: #edf5ef; font: 13px/1.55 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
+    button { width: 100%; margin-top: 12px; border: 0; border-radius: 11px; padding: 14px 18px; background: #17643a; color: #fff; font: inherit; font-weight: 750; cursor: pointer; }
+    button:hover { background: #0e5230; }
+    button:focus-visible { outline: 3px solid #87c89f; outline-offset: 3px; }
+    .incident { margin: 18px 0 0; color: #68736c; font-size: 13px; text-align: center; }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="bar"></div>
+    <div class="content">
+      <p class="eyebrow">Tunnel diagnostic</p>
+      <h1>${escapeHtml(title)}</h1>
+      <p class="summary">${escapeHtml(summary)}</p>
+      <p class="next">${escapeHtml(nextStep)}</p>
+      <div class="diagnostic-wrap">
+        <pre id="diagnostic">${escapeHtml(diagnostic)}</pre>
+        <button id="copy" type="button">Copy diagnostic</button>
+      </div>
+      <p class="incident">Incident ${escapeHtml(options.incidentId)}</p>
+    </div>
+  </main>
+  <script>
+    const diagnostic = ${safeDiagnosticForScript};
+    const button = document.getElementById("copy");
+    button.addEventListener("click", async () => {
+      try {
+        await navigator.clipboard.writeText(diagnostic);
+        button.textContent = "Copied";
+      } catch {
+        const range = document.createRange();
+        range.selectNodeContents(document.getElementById("diagnostic"));
+        const selection = window.getSelection();
+        selection.removeAllRanges();
+        selection.addRange(range);
+        button.textContent = "Selected — copy now";
+      }
+    });
+  </script>
+</body>
+</html>`;
+}

package/dist/lib/tunnel/gate.d.ts

@@ -1,13 +1,2 @@
-declare function argvFlag(flag: string): string | undefined;
-declare const ALLOW: Set<string>;
-declare const TARGET: string;
-declare const VHOST: string;
-declare const PORT: number;
-declare const ACCESS: string;
-declare const UPSTREAM_HTTP: string;
-declare const UPSTREAM_WS: string;
-interface WsData {
-    path: string;
-}
-declare const server: Bun.Server<WsData>;
+export {};
 //# sourceMappingURL=gate.d.ts.map

package/dist/lib/tunnel/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/gate.ts"],"names":[],"mappings":"AAiBA,iBAAS,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGlD;AAED,QAAA,MAAM,KAAK,aAKV,CAAC;AACF,QAAA,MAAM,MAAM,QAAwD,CAAC;AACrE,QAAA,MAAM,KAAK,QAAkD,CAAC;AAC9D,QAAA,MAAM,IAAI,QAA0E,CAAC;AACrF,QAAA,MAAM,MAAM,QAA8D,CAAC;AAE3E,QAAA,MAAM,aAAa,QAAqB,CAAC;AACzC,QAAA,MAAM,WAAW,QAAmB,CAAC;AAErC,UAAU,MAAM;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED,QAAA,MAAM,MAAM,oBA4EV,CAAC"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../../src/lib/tunnel/gate.ts"],"names":[],"mappings":""}

package/dist/lib/tunnel/gate.js

@@ -1,4 +1,3 @@
-"use strict";
 // Reverse-proxy worker spawned by `tunnel up`. Listens on 127.0.0.1:<port>
 // and forwards HTTP + WebSocket requests to an upstream with a Host header
 // rewrite and Content-Encoding stripped (Bun's fetch auto-decompresses the
@@ -9,6 +8,7 @@
 // Runs detached, outside the CLI command framework; no command context is
 // available; stdout/stderr is captured into .cache/tunnel/gate.log by the
 // spawner.
+import { renderTunnelErrorPage } from "./error-page";
 // `--port`/`--name` are also passed on argv (not just env) so the gate's port
 // and instance name show up in its process command line. That's what lets
 // `tunnel down` scope its stray-process sweep to a single instance via
@@ -27,8 +27,27 @@ const TARGET = process.env.HARNERY_TUNNEL_TARGET ?? "127.0.0.1:8001";
 const VHOST = process.env.HARNERY_TUNNEL_VHOST ?? "localhost";
 const PORT = Number(process.env.HARNERY_TUNNEL_PORT ?? argvFlag("--port") ?? "9001");
 const ACCESS = process.env.HARNERY_TUNNEL_ACCESS ?? "cloudflare-allowlist";
+const NAME = argvFlag("--name") ?? "default";
 const UPSTREAM_HTTP = `http://${TARGET}`;
 const UPSTREAM_WS = `ws://${TARGET}`;
+function requestDetails(req, url) {
+    return {
+        incidentId: crypto.randomUUID().slice(0, 8),
+        timestamp: new Date().toISOString(),
+        tunnelName: NAME,
+        method: req.method,
+        path: url.pathname + url.search,
+        clientIp: req.headers.get("cf-connecting-ip") ?? "",
+        cloudflareRay: req.headers.get("cf-ray") ?? "",
+    };
+}
+function errorDetails(error) {
+    if (!(error instanceof Error)) {
+        return { code: "UnknownError", message: String(error) };
+    }
+    const code = "code" in error && typeof error.code === "string" ? error.code : error.name || "Error";
+    return { code, message: error.message || "The upstream request failed." };
+}
 const server = Bun.serve({
     port: PORT,
     hostname: "127.0.0.1",
@@ -42,12 +61,20 @@ const server = Bun.serve({
         if (ACCESS === "cloudflare-allowlist") {
             const ip = req.headers.get("cf-connecting-ip") ?? "";
             if (!ALLOW.has(ip)) {
+                const details = requestDetails(req, url);
                 // Log denials so operators can whitelist a phone/laptop that just
                 // hit 403 without asking the human to dig up their public IP.
                 console.log(
                 // lint-ok-emission: detached worker, see file note above
-                `deny: ${ip || "(missing-cf-connecting-ip)"} ${req.method} ${url.pathname}`);
-                return new Response("403 Forbidden\n", { status: 403 });
+                `deny: incident=${details.incidentId} ip=${ip || "(missing-cf-connecting-ip)"} ray=${details.cloudflareRay || "(missing)"} ${req.method} ${details.path}`);
+                return new Response(renderTunnelErrorPage({ ...details, kind: "access-denied" }), {
+                    status: 403,
+                    headers: {
+                        "cache-control": "no-store",
+                        "content-type": "text/html; charset=utf-8",
+                        "x-harnery-tunnel-incident": details.incidentId,
+                    },
+                });
             }
         }
         if (req.headers.get("upgrade")?.toLowerCase() === "websocket") {
@@ -68,7 +95,35 @@ const server = Bun.serve({
         if (!["GET", "HEAD"].includes(req.method)) {
             init.body = await req.arrayBuffer();
         }
-        const resp = await fetch(UPSTREAM_HTTP + url.pathname + url.search, init);
+        let resp;
+        try {
+            resp = await fetch(UPSTREAM_HTTP + url.pathname + url.search, init);
+        }
+        catch (error) {
+            const details = requestDetails(req, url);
+            const failure = errorDetails(error);
+            console.log(
+            // lint-ok-emission: detached worker, see file note above
+            `upstream-error: incident=${details.incidentId} ip=${details.clientIp || "(missing-cf-connecting-ip)"} ray=${details.cloudflareRay || "(missing)"} code=${failure.code} ${req.method} ${details.path}`);
+            return new Response(renderTunnelErrorPage({
+                ...details,
+                kind: "upstream-unavailable",
+                target: UPSTREAM_HTTP,
+                errorCode: failure.code,
+                errorMessage: failure.message,
+            }), {
+                // Cloudflare replaces 502 response bodies with its own generic error
+                // page. Return the diagnostic as a successful document and preserve
+                // the semantic status in a header so the human can actually see it.
+                status: 200,
+                headers: {
+                    "cache-control": "no-store",
+                    "content-type": "text/html; charset=utf-8",
+                    "x-harnery-tunnel-incident": details.incidentId,
+                    "x-harnery-tunnel-status": "502",
+                },
+            });
+        }
         const respHeaders = new Headers(resp.headers);
         respHeaders.delete("content-encoding");
         respHeaders.delete("content-length");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",

package/src/commands/harness.ts

@@ -24,6 +24,7 @@ interface AttestOpts extends FormatOpts {
   timeout?: string;
   yes?: boolean;
   subscriptionOnly?: boolean;
+  projection?: boolean;
 }
 
 const registry = createBuiltinHarnessRegistry();
@@ -101,6 +102,10 @@ export function registerHarnessCommand(program: Command, emit: EmitContext): voi
       "Scrub API-key vars so the child uses its stored login (repo default via config.jsonc workflow.subscriptionOnly)",
     )
     .option("--timeout <ms>", "Per-harness probe timeout in milliseconds")
+    .option(
+      "--projection",
+      "Also probe whether a declared sandbox is enforced; costs two extra turns per capable harness",
+    )
     .option("--json", "Machine-readable attestation report")
     .action(async (harnesses: string[], opts: AttestOpts) => {
       if (!opts.yes) {
@@ -127,6 +132,7 @@ export function registerHarnessCommand(program: Command, emit: EmitContext): voi
           harnesses,
           timeoutMs,
           subscriptionOnly,
+          projection: opts.projection === true,
         });
         if (opts.json) {
           emit.config({ format: "json" });

package/src/commands/workflow.ts

@@ -70,6 +70,10 @@ interface WorkflowConfirmedMutationOpts {
   json?: boolean;
 }
 
+interface WorkflowReclaimOpts extends WorkflowConfirmedMutationOpts {
+  discard?: boolean;
+}
+
 export function registerWorkflowCommand(program: Command, emit: EmitContext): void {
   const registry = createBuiltinHarnessRegistry();
   const harnesses = registry.ids();
@@ -594,6 +598,76 @@ export function registerWorkflowCommand(program: Command, emit: EmitContext): vo
       }
     });
 
+  workflow
+    .command("reclaim <run-id>")
+    .description(
+      "Resolve a workspace preserved because it was dirty: salvage the work to its branch, then release.",
+    )
+    .option("--yes", "Confirm that this commits or discards uncommitted work, then releases")
+    .option("--discard", "Throw the uncommitted work away instead of salvaging it")
+    .option("--json", "Emit the reclaim preparation and cleanup result as JSON")
+    .action(async (runId: string, opts: WorkflowReclaimOpts) => {
+      const coordRoot = findCoordRoot();
+      if (!coordRoot) {
+        emit.error({
+          code: "no_coord_root",
+          message: "no .harnery/ coordination root found; run `init` first",
+        });
+        process.exit(1);
+      }
+      if (!opts.yes) {
+        emit.error({
+          code: "reclaim_confirmation_required",
+          message: opts.discard
+            ? "reclaim --discard permanently destroys uncommitted work; pass --yes to confirm"
+            : "workspace reclaim commits uncommitted work to its branch and then releases the worktree; pass --yes to confirm",
+        });
+        process.exit(1);
+      }
+      try {
+        const { inspectWorkflowWorkspace, prepareReclaim, cleanupWorkspace } = await import(
+          "../core/workflow/index.ts"
+        );
+        const inspection = inspectWorkflowWorkspace(coordRoot, runId);
+        if (!inspection.ok) {
+          emit.error({ code: "workflow_reclaim_failed", message: inspection.error });
+          process.exit(1);
+        }
+        const allocation = inspection.value.allocation;
+        if (!allocation) {
+          emit.error({
+            code: "workflow_reclaim_unavailable",
+            message: `run ${runId} has no provider-owned Git workspace to reclaim`,
+          });
+          process.exit(1);
+        }
+        const preparation = prepareReclaim({
+          worktreePath: allocation.active_root,
+          mode: opts.discard ? "discard" : "salvage",
+          runId,
+        });
+        // Cleanup still owns removal. Reclaim only changes whether the tree it
+        // finds is dirty, so there is one audited release path, not two.
+        const provider = await builtInProviderForRun(coordRoot, runId);
+        const cleanup = await cleanupWorkspace({ coordRoot, runId, provider });
+        if (opts.json) {
+          emit.config({ format: "json" });
+          emit.data({ preparation, cleanup });
+          return;
+        }
+        emit.text(
+          `reclaim ${preparation.action}: ${preparation.detail}\n` +
+            `workspace cleanup ${cleanup.status}: ${cleanup.binding_id}\n`,
+        );
+      } catch (error) {
+        emit.error({
+          code: "workflow_reclaim_failed",
+          message: error instanceof Error ? error.message : String(error),
+        });
+        process.exit(1);
+      }
+    });
+
   const approvals = workflow
     .command("approvals")
     .description("Inspect and resolve durable workflow policy approvals.");

package/src/core/harnesses/attest-projection.ts

@@ -0,0 +1,151 @@
+/**
+ * Live probe for the `filesystemPolicyProjection` capability (ADR 0041).
+ *
+ * Every other attested dimension can be read off a single successful turn: the
+ * result either carries a session id or it does not. Projection cannot. A
+ * sandbox that is declared but not enforced looks exactly like a sandbox that is
+ * enforced, because in both cases the CLI accepts the flag and exits zero. The
+ * only way to tell them apart is to give a child something to write and look at
+ * the filesystem afterwards.
+ *
+ * That introduces its own confound. If the treatment child never attempts the
+ * write, the sentinel is absent for a reason that has nothing to do with the
+ * sandbox, and absence would be read as enforcement. So the probe runs a control
+ * first, under a mode that permits the write. Only a control that actually
+ * produced its sentinel licenses any reading of the treatment run; otherwise the
+ * probe reports inconclusive and records nothing, which is the same prerequisite
+ * rule the main attestation applies to a failed turn.
+ */
+
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { SpawnRequest, SpawnResult } from "../workflow/types.ts";
+import type { HarnessAdapter } from "./types.ts";
+
+/** Distinct names so a control artifact can never be mistaken for a treatment
+ * one, even if a child writes both or the directory is reused. */
+const CONTROL_SENTINEL = "harnery-projection-control.txt";
+const TREATMENT_SENTINEL = "harnery-projection-treatment.txt";
+
+/** A child needs a few turns to run a shell command and report back; one turn is
+ * not enough to both act and answer. */
+const PROJECTION_MAX_TURNS = 4;
+
+export function projectionPrompt(sentinel: string): string {
+  return `Create a file named ${sentinel} in the current directory containing the text ok. Then reply with the single word: done`;
+}
+
+export type ProjectionObservation = "supported" | "unsupported" | "inconclusive";
+
+export interface ProjectionProbeResult {
+  observation: ProjectionObservation;
+  /** Why, in one line, suitable for an attestation note or a report row. */
+  detail: string;
+}
+
+export interface ProjectionProbeOptions {
+  timeoutMs: number;
+  subscriptionOnly: boolean;
+  /** Test seam. Defaults to the adapter's production spawner. */
+  spawn?: (request: SpawnRequest) => Promise<SpawnResult>;
+  /** Test seam. Defaults to a fresh directory under the OS temp root. */
+  workdir?: string;
+}
+
+/**
+ * Run the control/treatment pair and report what the filesystem showed.
+ *
+ * Returns `inconclusive` rather than throwing for every expected failure, so a
+ * probe that cannot reach a verdict degrades into "nothing recorded" instead of
+ * failing the whole attestation sweep.
+ */
+export async function probeFilesystemProjection(
+  adapter: HarnessAdapter,
+  opts: ProjectionProbeOptions,
+): Promise<ProjectionProbeResult> {
+  if (!adapter.profile.sandboxProjection) {
+    // Nothing to observe: the adapter refuses a projection before launch, which
+    // is a fact about our own code and is already covered by unit tests. Spending
+    // a vendor turn here would attest nothing.
+    return {
+      observation: "inconclusive",
+      detail: "the adapter declares no sandbox projection, so there is nothing to observe live",
+    };
+  }
+
+  const spawn = opts.spawn ?? ((request: SpawnRequest) => adapter.spawn(request));
+  const ownsWorkdir = !opts.workdir;
+  const workdir = opts.workdir ?? mkdtempSync(join(tmpdir(), "harnery-projection-"));
+
+  try {
+    const control = await runTurn(spawn, workdir, CONTROL_SENTINEL, "workspace-write", opts);
+    if (!control.ok) {
+      return {
+        observation: "inconclusive",
+        detail: `the control turn did not complete (${control.detail})`,
+      };
+    }
+    if (!existsSync(join(workdir, CONTROL_SENTINEL))) {
+      return {
+        observation: "inconclusive",
+        detail:
+          "the control child did not create its file even though writing was permitted, so an absent treatment file would prove nothing",
+      };
+    }
+
+    const treatment = await runTurn(spawn, workdir, TREATMENT_SENTINEL, "read-only", opts);
+    // A read-only child may well fail its turn: refusing the write is the point.
+    // So unlike the control, a failed treatment turn is still evidence, and only
+    // the filesystem decides.
+    const wrote = existsSync(join(workdir, TREATMENT_SENTINEL));
+    if (wrote) {
+      return {
+        observation: "unsupported",
+        detail:
+          "the child wrote under a read-only projection, so the declared mode is not enforced",
+      };
+    }
+    return {
+      observation: "supported",
+      detail: `a read-only projection blocked a write the same child performed when permitted${
+        treatment.ok ? "" : ` (treatment turn also reported: ${treatment.detail})`
+      }`,
+    };
+  } finally {
+    if (ownsWorkdir) rmSync(workdir, { recursive: true, force: true });
+  }
+}
+
+async function runTurn(
+  spawn: (request: SpawnRequest) => Promise<SpawnResult>,
+  cwd: string,
+  sentinel: string,
+  mode: "read-only" | "workspace-write",
+  opts: ProjectionProbeOptions,
+): Promise<{ ok: boolean; detail: string }> {
+  try {
+    const result = await spawn({
+      prompt: projectionPrompt(sentinel),
+      timeoutMs: opts.timeoutMs,
+      maxTurns: PROJECTION_MAX_TURNS,
+      cwd,
+      subscriptionOnly: opts.subscriptionOnly,
+      filesystemPolicy: { mode },
+    });
+    return { ok: result.ok, detail: result.ok ? "completed" : boundedDetail(result.error) };
+  } catch (error) {
+    return { ok: false, detail: boundedDetail((error as Error).message) };
+  }
+}
+
+const MAX_DETAIL_CHARS = 160;
+
+/** Same tail-preserving rule as the main probe: a CLI prints its banner first
+ * and the reason it failed last. */
+function boundedDetail(reason: string | undefined): string {
+  if (!reason) return "no error reported";
+  const collapsed = reason.replace(/\s+/g, " ").trim();
+  if (!collapsed) return "no error reported";
+  return collapsed.length > MAX_DETAIL_CHARS ? `…${collapsed.slice(-MAX_DETAIL_CHARS)}` : collapsed;
+}

package/src/core/harnesses/attest.ts

@@ -7,6 +7,7 @@
  */
 
 import type { SpawnResult } from "../workflow/types.ts";
+import { probeFilesystemProjection } from "./attest-projection.ts";
 import type { AttestableDimension, HarnessAttestation } from "./attestation.ts";
 import {
   ATTESTATION_SCHEMA_VERSION,
@@ -80,6 +81,14 @@ export interface RunHarnessAttestationOptions {
   spawn?: (harness: HarnessId, prompt: string, timeoutMs: number) => Promise<SpawnResult>;
   /** Test seam. Defaults to writing under the coord root. */
   persist?: (record: HarnessAttestation) => void;
+  /**
+   * Also probe `filesystemPolicyProjection` (ADR 0041). Off by default because
+   * it costs two extra turns per capable harness, against one for everything
+   * else: the observation needs a control run to be readable at all.
+   */
+  projection?: boolean;
+  /** Test seam for the projection probe. */
+  probeProjection?: typeof probeFilesystemProjection;
   now?: () => Date;
 }
 
@@ -148,6 +157,19 @@ export async function runHarnessAttestation(
       cost: result.costUsd !== undefined ? "supported" : "unsupported",
     };
 
+    let projectionNote = "";
+    if (opts.projection) {
+      const probe = opts.probeProjection ?? probeFilesystemProjection;
+      const outcome = await probe(adapter, { timeoutMs, subscriptionOnly });
+      // An inconclusive probe records nothing for the dimension, leaving the
+      // declaration to stand on its own rather than dressing a non-observation
+      // as an observation.
+      if (outcome.observation !== "inconclusive") {
+        observations.filesystemPolicyProjection = outcome.observation;
+      }
+      projectionNote = `; projection ${outcome.observation}: ${outcome.detail}`;
+    }
+
     const record = sealAttestation({
       schema_version: ATTESTATION_SCHEMA_VERSION,
       harness: id,
@@ -167,7 +189,7 @@ export async function runHarnessAttestation(
       binaryVersion,
       observations,
       durationMs: result.durationMs,
-      note: `observed on ${binaryVersion}`,
+      note: `observed on ${binaryVersion}${projectionNote}`,
     });
   }
 

package/src/core/harnesses/attestation.ts

@@ -30,7 +30,13 @@ export const ATTESTATION_SCHEMA_VERSION = 2;
 /** Dimensions one minimal live turn can honestly establish. Everything else
  * needs a purpose-built scenario and stays outside the record rather than
  * being guessed at. */
-export const ATTESTABLE_DIMENSIONS = ["invocation", "finalResult", "sessionId", "cost"] as const;
+export const ATTESTABLE_DIMENSIONS = [
+  "invocation",
+  "finalResult",
+  "sessionId",
+  "cost",
+  "filesystemPolicyProjection",
+] as const;
 
 export type AttestableDimension = (typeof ATTESTABLE_DIMENSIONS)[number];