@mikenguyen69/harness 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Nguyen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @mikenguyen69/harness
+
+The publishable npm distribution facade for the portfolio. One `harness` binary
+routes operator and integration commands to `@harness/system`, `@harness/agent`,
+and `@harness/orchestration` as child processes — no verification, door, run,
+routing, or hook-install policy is reimplemented here.
+
+In the development workspace, invoke the facade by path:
+
+```bash
+node repos/npm-harness/dist/cli.js --help
+```
+
+The workspace `node_modules/.bin/harness` shim continues to point at
+`@harness/system` until the staged publish manifest adds `bin.harness` (see
+`ipkg-deterministic-tarball`).
+
+## Cancellation (process-group-break)
+
+A console interrupt (Ctrl+C / CTRL_BREAK) while `harness run` (or any dispatched
+child) is in flight is handled as one documented path across platforms. The
+facade never sends SIGINT through ChildProcess#kill — on Windows that is
+TerminateProcess and does not emulate a console break.
+
+| Platform | Spawn | Interrupt |
+|----------|-------|-----------|
+| POSIX | `detached: true` (new process group) | `process.kill(-pid, "SIGTERM")` |
+| Windows | `CREATE_NEW_PROCESS_GROUP` (shared console; not Node `detached` / `DETACHED_PROCESS`) | `GenerateConsoleCtrlEvent(CTRL_BREAK_EVENT, groupPid)` |
+
+The facade converts a console Ctrl+C (`SIGINT`) into that interrupt — Windows
+process groups ignore CTRL_C by default, so the handler is not a no-op. In-flight
+agent/orchestration grandchildren must stay in that process group (runners spawn
+without `detached`). If the tree has not exited after a short grace period, the
+facade reaps it (`taskkill /T /F` last resort on Windows; a Win32 job with
+`KILL_ON_JOB_CLOSE` also covers grandchildren). The grace reap is not cancelled
+just because the direct child closed.
+
+Manual evidence (process tree before/after + exit code):
+
+```bash
+node repos/npm-harness/scripts/interrupt-evidence.mjs          # interactive Ctrl+C
+node repos/npm-harness/scripts/interrupt-evidence.mjs --auto  # POSIX / CI
+```

package/dist/build-identity.json

@@ -0,0 +1 @@
+{"system":"0.0.1","agent":"0.0.1","orchestration":"0.0.1"}

package/dist/cancellation.js

@@ -0,0 +1,138 @@
+/**
+ * Cross-platform cancellation path for in-flight `harness` children.
+ *
+ * One operator action (console interrupt: Ctrl+C / CTRL_BREAK) maps to one
+ * documented mechanism and MUST NOT call ChildProcess#kill with SIGINT — on
+ * Windows that is TerminateProcess and does not emulate a console break.
+ *
+ * | Platform | Spawn | Interrupt |
+ * |----------|-------|-----------|
+ * | POSIX | `detached: true` (new process group) | `process.kill(-pid, "SIGTERM")` |
+ * | Windows | `CREATE_NEW_PROCESS_GROUP` (shared console, not `DETACHED_PROCESS`) | `GenerateConsoleCtrlEvent(CTRL_BREAK_EVENT, groupPid)` |
+ *
+ * Runners must spawn in-flight agent children **without** `detached` so they
+ * stay in that process group. If the tree has not exited after GRACE_MS, it is
+ * reaped (POSIX SIGKILL / Windows `taskkill /T /F` last resort; a Win32 job
+ * with KILL_ON_JOB_CLOSE also covers grandchildren).
+ */
+import { spawn } from "node:child_process";
+import { sendCtrlBreak, spawnWindowsProcessGroup } from "./win32-process-group.js";
+export const CANCELLATION_PATH = {
+    name: "process-group-break",
+    posix: "detached process group + SIGTERM to -pid",
+    windows: "CREATE_NEW_PROCESS_GROUP + GenerateConsoleCtrlEvent(CTRL_BREAK_EVENT, groupPid)",
+    never: "ChildProcess kill with SIGINT",
+};
+/** Grace period after interrupt before a force-reap of the process tree. */
+export const CANCELLATION_GRACE_MS = 5_000;
+export function cancellableSpawnOptions(base = {}) {
+    const isWin = process.platform === "win32";
+    return {
+        ...base,
+        // POSIX: new process group so kill(-pid) reaches the tree.
+        // Windows: Node's `detached` sets DETACHED_PROCESS and breaks CTRL_BREAK
+        // delivery — Windows spawn goes through spawnCancellable instead.
+        detached: !isWin,
+        windowsHide: false,
+    };
+}
+/**
+ * Spawn a child in the documented cancellation group.
+ * Windows: CREATE_NEW_PROCESS_GROUP via the Win32 helper (not Node `detached`).
+ * POSIX: `detached: true`.
+ */
+export function spawnCancellable(command, args, options = {}) {
+    if (process.platform === "win32") {
+        return spawnWindowsProcessGroup(command, args, options);
+    }
+    const child = spawn(command, args, cancellableSpawnOptions(options));
+    if (child.pid === undefined) {
+        throw new Error("spawnCancellable: child pid missing");
+    }
+    child.groupPid = child.pid;
+    return child;
+}
+function groupPidOf(child) {
+    const tagged = child;
+    return tagged.groupPid || child.pid;
+}
+/**
+ * Deliver the documented interrupt to `pid`'s process group.
+ * Windows: CTRL_BREAK via GenerateConsoleCtrlEvent. Never taskkill, never
+ * ChildProcess#kill("SIGINT").
+ */
+export function interruptProcessTree(pid) {
+    if (process.platform === "win32") {
+        sendCtrlBreak(pid);
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGTERM");
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+/** Last-resort tree reap so a stuck child cannot orphan grandchildren. */
+export function reapProcessTree(pid) {
+    if (process.platform === "win32") {
+        spawn("taskkill", ["/pid", String(pid), "/t", "/f"], {
+            stdio: "ignore",
+            windowsHide: true,
+        }).on("error", () => undefined);
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            // already gone
+        }
+    }
+}
+export function attachCancellation(child, onForwarded) {
+    let forwarded = false;
+    let reaper;
+    const forward = () => {
+        const pid = groupPidOf(child);
+        if (pid === undefined || forwarded)
+            return;
+        forwarded = true;
+        onForwarded?.();
+        interruptProcessTree(pid);
+        reaper = setTimeout(() => reapProcessTree(pid), CANCELLATION_GRACE_MS);
+        reaper.unref();
+    };
+    process.on("SIGINT", forward);
+    process.on("SIGTERM", forward);
+    if (process.platform === "win32") {
+        process.on("SIGBREAK", forward);
+    }
+    else {
+        process.on("SIGHUP", forward);
+    }
+    return () => {
+        // Do not clear the grace reap: the direct child (or helper) closing is not
+        // proof that grandchildren are gone. An unref'd reaper is harmless if the
+        // tree already exited; it is the only backstop if they did not.
+        process.removeListener("SIGINT", forward);
+        process.removeListener("SIGTERM", forward);
+        if (process.platform === "win32") {
+            process.removeListener("SIGBREAK", forward);
+        }
+        else {
+            process.removeListener("SIGHUP", forward);
+        }
+        void reaper;
+    };
+}
+//# sourceMappingURL=cancellation.js.map

package/dist/cli.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * @mikenguyen69/harness — thin public dispatcher over the three portfolio CLIs.
+ *
+ * Owns command discovery, help/version output, package-relative internal CLI
+ * resolution, child-process dispatch, process-group cancellation, and
+ * exit-code propagation only. No verification, door, run, merge, routing, or
+ * hook-install policy lives here.
+ */
+import { buildDispatchRequest, dispatch } from "./dispatch.js";
+import { USAGE } from "./help.js";
+import { resolveInternalClis } from "./paths.js";
+import { buildInternalArgv, resolveRoute } from "./routes.js";
+import { formatVersion } from "./version.js";
+export async function main(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (argv.includes("--version") || argv.includes("-V")) {
+        process.stdout.write(formatVersion());
+        return 0;
+    }
+    const route = resolveRoute(argv);
+    if (route === null) {
+        process.stderr.write(argv.length === 0
+            ? USAGE
+            : `harness ${argv.join(" ")}: unknown command\nRun harness --help\n`);
+        return argv.length === 0 ? 0 : 2;
+    }
+    if (route === "status-skeleton") {
+        process.stderr.write("harness status: not implemented (skeleton)\n");
+        return 1;
+    }
+    const clis = resolveInternalClis();
+    const internalArgv = buildInternalArgv(route, argv);
+    const request = buildDispatchRequest(route.product, internalArgv, {
+        clis,
+        ...(route.injectOrchestrationBins ? { injectOrchestrationBins: true } : {}),
+    });
+    return dispatch(request);
+}
+const invoked = process.argv[1]?.endsWith("cli.js") ?? false;
+if (invoked) {
+    void main(process.argv.slice(2)).then((code) => process.exit(code));
+}
+//# sourceMappingURL=cli.js.map

package/dist/dispatch.js

@@ -0,0 +1,70 @@
+import { attachCancellation, spawnCancellable } from "./cancellation.js";
+function orchestrationEnv(clis, base) {
+    const env = { ...base };
+    env.HARNESS_BIN = clis.system;
+    env.AGENT_HARNESS_BIN = clis.agent;
+    return env;
+}
+function commandLine(request) {
+    if (request.command.endsWith(".js")) {
+        return { command: process.execPath, args: [request.command, ...request.args] };
+    }
+    return { command: request.command, args: request.args };
+}
+export function dispatch(request) {
+    return new Promise((resolve) => {
+        const { command, args } = commandLine(request);
+        const spawnOpts = {
+            cwd: request.cwd ?? process.cwd(),
+            env: request.env ?? process.env,
+            stdio: "inherit",
+        };
+        const child = spawnCancellable(command, args, spawnOpts);
+        let settled = false;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(code);
+        };
+        const detach = attachCancellation(child);
+        child.on("error", () => {
+            detach();
+            finish(1);
+        });
+        child.on("close", (code) => {
+            detach();
+            finish(code ?? 1);
+        });
+    });
+}
+export function buildDispatchRequest(product, internalArgv, opts) {
+    const clis = opts.clis;
+    const entry = product === "system"
+        ? clis.system
+        : product === "agent"
+            ? clis.agent
+            : clis.orchestration;
+    let env = process.env;
+    if (opts.injectOrchestrationBins) {
+        env = orchestrationEnv(clis, process.env);
+    }
+    return { command: entry, args: internalArgv, env };
+}
+/** Synchronous dispatch for tests — preserves stdio pipes when configured. */
+export function dispatchSync(request, spawnSync) {
+    const { command, args } = commandLine(request);
+    const child = spawnSync(command, args, {
+        cwd: request.cwd ?? process.cwd(),
+        env: request.env ?? process.env,
+        encoding: "utf8",
+        maxBuffer: 20 * 1024 * 1024,
+    });
+    return {
+        code: child.status ?? 1,
+        stdout: child.stdout ?? "",
+        stderr: child.stderr ?? "",
+    };
+}
+export { orchestrationEnv };
+//# sourceMappingURL=dispatch.js.map

package/dist/help.js

@@ -0,0 +1,47 @@
+export const USAGE = `harness — one command over the portfolio harness products
+
+Operator journey:
+  harness init                 scaffold a target repository for harness work
+  harness doctor               read-only preflight before a run
+  harness run                  drive the spec DAG with an agent fleet
+  harness resume               continue after a signed door approval
+  harness status               project run and lane status from RunState
+  harness report run           render the end-of-run HTML report
+  harness report calibration   aggregate verification envelopes (calibration input)
+
+Advanced — verification and gates:
+  harness verify               run all bound gates and emit the signed envelope
+  harness gate --pre           ring-0 cheap gates before tool use
+
+Advanced — specs and units:
+  harness spec check           lint specs, dep DAG, consumes/produces
+  harness spec materialize     write idempotent unit.planned facts
+  harness next                 list units ready to claim
+  harness claim                atomically take a ready unit
+  harness heartbeat            keep a claim alive
+  harness merge                authorize or record a landed merge
+
+Advanced — doors and ledger:
+  harness door list|show|approve|reject   open-decision surface
+  harness ledger append|read|verify-chain record plane
+
+Advanced — board and attestations:
+  harness board build|serve    local live dashboard
+  harness attest               provenance attestations for a merge
+
+Advanced — calibration:
+  harness calibrate            calibration jobs
+  harness digest               digest surfaces
+
+Integration (machine-facing, same binary):
+  harness hook pre-tool-use    agent PreToolUse handler (payload on stdin)
+  harness session <phase>      append session.<phase> evidence (stdin JSON)
+  harness escalate             raise session.escalated for the current unit
+  harness route                print the resolved route as JSON
+
+Usage:
+  harness --help               this text
+  harness --version            facade version and internal build identity
+  harness <command> [args…]    dispatch to the owning internal CLI
+`;
+//# sourceMappingURL=help.js.map

package/dist/internal/agent/adapter/conformance.js

@@ -0,0 +1,53 @@
+/**
+ * conformance — replays a recorded scenario through the adapter and returns the
+ * observable stream (hook exit codes + session event {type, body}). A scenario
+ * passes iff its replay equals its recorded expectation, field for field.
+ *
+ * The session events are compared as the adapter emits them (before the ledger
+ * stamps seq/ts/hash), so the comparison is deterministic.
+ */
+import { buildSessionEvent, } from "./session.js";
+import { handlePreToolUse, } from "./hook.js";
+export function runScenario(s) {
+    const saved = {};
+    for (const [k, v] of Object.entries(s.env ?? {})) {
+        saved[k] = process.env[k];
+        process.env[k] = v;
+    }
+    const events = [];
+    const capture = (phase, body) => {
+        const built = buildSessionEvent(phase, body);
+        events.push({ type: built.type, body: built.body });
+        return { ok: true };
+    };
+    const exitCodes = [];
+    try {
+        for (const step of s.steps) {
+            if ("hook" in step) {
+                exitCodes.push(handlePreToolUse(step.hook, s.unit, capture).exitCode);
+            }
+            else {
+                capture(step.session, step.body);
+            }
+        }
+    }
+    finally {
+        for (const [k, v] of Object.entries(saved)) {
+            if (v === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = v;
+        }
+    }
+    return { exitCodes, events };
+}
+export function checkScenario(s) {
+    const got = runScenario(s);
+    const want = { exitCodes: s.expect.exitCodes, events: s.expect.events };
+    const a = JSON.stringify(want, null, 2);
+    const b = JSON.stringify(got, null, 2);
+    return a === b
+        ? { name: s.name, ok: true }
+        : { name: s.name, ok: false, diff: `--- expected\n${a}\n--- actual\n${b}` };
+}
+//# sourceMappingURL=conformance.js.map

package/dist/internal/agent/adapter/hook.js

@@ -0,0 +1,113 @@
+/**
+ * hook — the Claude Code PreToolUse handler.
+ *
+ * Reads the hook payload on stdin, resolves the current unit's scope, and:
+ *   - blocks a Write/Edit outside scope (exit 2, reason on stderr) and emits
+ *     session.gate_fired
+ *   - otherwise, optionally runs ring-0 (`harness gate --pre`) when
+ *     HARNESS_RING0=1; a real ring-0 failure blocks
+ *   - on ANY internal failure (bad payload, no unit context, unreachable
+ *     harness) it DEGRADES: warn on stderr, exit 0. The hook is the fast copy
+ *     of the rule; verify and the substrate are the guarantee (principle 1).
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkToolCall } from "./scope.js";
+import { emitSessionEvent, } from "./session.js";
+export function loadUnitContext(cwd) {
+    const file = join(cwd, ".harness", "current-unit.json");
+    if (existsSync(file)) {
+        try {
+            return JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            /* fall through to env */
+        }
+    }
+    const id = process.env.HARNESS_UNIT_ID;
+    const component = process.env.HARNESS_UNIT_COMPONENT;
+    const scope = process.env.HARNESS_UNIT_SCOPE;
+    if (id && component && scope) {
+        return {
+            unit_id: id,
+            component_id: component,
+            scope: scope
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean),
+        };
+    }
+    return undefined;
+}
+function ring0(path, bin) {
+    const r = spawnSync(bin, ["gate", "--pre", "--file", path], {
+        encoding: "utf8",
+        windowsHide: true,
+    });
+    return { ok: r.status === 0, output: (r.stdout ?? "") + (r.stderr ?? "") };
+}
+/** Pure decision — no process.exit, for testability. */
+export function handlePreToolUse(payload, ctx, emit = emitSessionEvent) {
+    // degrade: no unit context → let it through, warn
+    if (!ctx) {
+        return {
+            exitCode: 0,
+            message: "adapter: no current-unit context; scope not enforced at the hook (verify still will)",
+        };
+    }
+    const decision = checkToolCall(payload, ctx.scope, payload.cwd);
+    const session = payload.session_id ?? "unknown";
+    if (!decision.allow) {
+        emit("gate_fired", {
+            session_id: session,
+            unit_id: ctx.unit_id,
+            component_id: ctx.component_id,
+            ...(ctx.model ? { model: ctx.model } : {}),
+            gate: { name: "scope", outcome: "fail", ring: 0 },
+        }, { soft: true });
+        return decision.reason !== undefined
+            ? { exitCode: 2, message: decision.reason }
+            : { exitCode: 2 };
+    }
+    if (process.env.HARNESS_RING0 === "1" && decision.path) {
+        const bin = process.env.HARNESS_BIN ?? "harness";
+        const r = ring0(decision.path, bin);
+        if (!r.ok) {
+            emit("gate_fired", {
+                session_id: session,
+                unit_id: ctx.unit_id,
+                component_id: ctx.component_id,
+                gate: { name: "pre", outcome: "fail", ring: 0 },
+            }, { soft: true });
+            return {
+                exitCode: 2,
+                message: `ring-0 gate failed:\n${r.output.trim()}`,
+            };
+        }
+    }
+    return { exitCode: 0 };
+}
+/** stdin → decision → stdout/stderr + exit code. Never throws. */
+export function runHookFromStdin(stdin) {
+    let payload;
+    try {
+        payload = JSON.parse(stdin);
+    }
+    catch {
+        return {
+            exitCode: 0,
+            message: "adapter: unparseable hook payload; allowing (fast-copy degrade)",
+        };
+    }
+    try {
+        return handlePreToolUse(payload, loadUnitContext(payload.cwd ?? process.cwd()));
+    }
+    catch (e) {
+        return {
+            exitCode: 0,
+            message: `adapter: internal error, allowing (fast-copy degrade): ${e.message}`,
+        };
+    }
+}
+//# sourceMappingURL=hook.js.map

package/dist/internal/agent/adapter/install.js

@@ -0,0 +1,30 @@
+/**
+ * Agent-harness hook-install path.
+ *
+ * Invoked by system-harness `init` as a documented composition (spawn this
+ * module — do not import `@harness/agent` from system-harness). Writes
+ * `.claude/settings.json` with `harness hook pre-tool-use`.
+ */
+import { fileURLToPath } from "node:url";
+import { installHooks } from "./settings.js";
+export { installHooks } from "./settings.js";
+function flag(argv, name) {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 && argv[i + 1] ? argv[i + 1] : undefined;
+}
+export function runHookInstall(argv, cwd = process.cwd()) {
+    const repo = flag(argv, "cwd") ?? argv[0] ?? cwd;
+    return installHooks(repo);
+}
+function invokedAsMain() {
+    const argv1 = process.argv[1];
+    if (!argv1)
+        return false;
+    const self = fileURLToPath(import.meta.url).replaceAll("\\", "/").toLowerCase();
+    const got = argv1.replaceAll("\\", "/").toLowerCase();
+    return got === self || got.endsWith("/adapter/install.js") || got.endsWith("/adapter/install.ts");
+}
+if (invokedAsMain()) {
+    process.stdout.write(`${runHookInstall(process.argv.slice(2))}\n`);
+}
+//# sourceMappingURL=install.js.map

package/dist/internal/agent/adapter/scope.js

@@ -0,0 +1,55 @@
+/**
+ * scope — the adapter's fast copy of the fail-closed scope rule. A Write/Edit
+ * to a path outside the unit's declared `scope` globs is blocked, with the
+ * scope quoted back. This is the *fast* copy: the same check re-runs at
+ * `verify` (scope_attested) and at the merge gate, so a bypass here is caught,
+ * just later (principle 1).
+ */
+import picomatch from "picomatch";
+/** Tools whose file target is scope-checked. */
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+function targetPath(call) {
+    const i = call.tool_input ?? {};
+    const p = i.file_path ?? i.path ?? i.notebook_path;
+    return typeof p === "string" ? p : undefined;
+}
+/** normalise to forward slashes, drop a leading ./ */
+function norm(p) {
+    return p.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/**
+ * @param cwd the session working dir — used to make an absolute path relative
+ * before glob-matching against the (relative) scope globs.
+ */
+export function checkToolCall(call, scopeGlobs, cwd) {
+    if (!WRITE_TOOLS.has(call.tool_name))
+        return { allow: true };
+    const raw = targetPath(call);
+    if (!raw)
+        return { allow: true };
+    let path = norm(raw);
+    if (cwd) {
+        const base = norm(cwd).replace(/\/$/, "") + "/";
+        if (path.startsWith(base))
+            path = path.slice(base.length);
+    }
+    if (scopeGlobs.length === 0) {
+        return {
+            allow: false,
+            path,
+            reason: "no scope declared for this unit — every unit must declare `scope`",
+        };
+    }
+    const isMatch = picomatch(scopeGlobs.map(norm), { dot: true });
+    if (isMatch(path))
+        return { allow: true, path };
+    return {
+        allow: false,
+        path,
+        reason: `"${path}" is outside this unit's declared scope.\n` +
+            `  scope: ${scopeGlobs.join(", ")}\n` +
+            "  Touching files outside declared scope is drift. Ask to widen the scope or split a new unit.\n" +
+            "  (This halt also re-runs at verify and at the merge gate.)",
+    };
+}
+//# sourceMappingURL=scope.js.map