@mikenguyen69/harness 0.1.0-beta.1

package/dist/internal/orchestration/runstate/publish.js

@@ -0,0 +1,115 @@
+/**
+ * publish (D1) — serialise a `RunState` to a `run-status` document and push it
+ * to the hub spool via `harness runstatus publish`, so the system-harness board
+ * can overlay this live run on portfolio truth.
+ *
+ * The document shape is system-harness's (`run-status.schema.json`, P7.1) — one
+ * schema, N emitters. This product never writes spool files directly, exactly
+ * as it appends the ledger only through `harness ledger append`.
+ *
+ * Publishing is best-effort: a failure degrades to a warning on the RunLog and
+ * NEVER stops the loop (staleness rules on the board cover a silent machine).
+ */
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { callProcess } from "../harness/cli.js";
+const iso = (ms, fallback = Date.now()) => new Date(ms > 0 ? ms : fallback).toISOString();
+export function runStateToDocument(state) {
+    const doc = {
+        machine_id: state.machineId || "local",
+        run_id: state.runId || "unknown",
+        system_id: state.systemId || "unknown",
+        spec_ref: state.specRef || "unknown",
+        started_at: iso(state.startedAt),
+        heartbeat_at: iso(state.heartbeatAt, Date.now()),
+        lanes: state.lanes.map((l) => ({
+            unit_id: l.unitId,
+            step: l.step,
+            runner: l.runner,
+            model: l.model,
+            attempt: l.attempt,
+            retry_budget: l.retryBudget,
+            cost: l.cost,
+            emitter: l.emitter,
+            settled: l.settled,
+            ...(l.envelopeHash ? { envelope_hash: l.envelopeHash } : {}),
+            ...(l.doorId ? { door_id: l.doorId } : {}),
+            ...(l.activity ? { activity: l.activity } : {}),
+            ...(l.activityAt ? { activity_at: iso(l.activityAt) } : {}),
+            ...(l.turn !== undefined ? { turn: l.turn } : {}),
+            ...(l.tokens ? { tokens: l.tokens } : {}),
+            ...(l.recent?.length ? { recent: l.recent } : {}),
+        })),
+        needs_you: state.needsYou.map((n) => ({
+            kind: n.kind,
+            ...(n.unitId ? { unit_id: n.unitId } : {}),
+            message: n.message,
+            unblock: n.unblock,
+        })),
+        counts: {
+            merged: state.counts.merged,
+            escalated: state.counts.escalated,
+            parked: state.counts.parked,
+            in_flight: state.counts.inFlight,
+            needs_you: state.counts.needsYou,
+            dag_size: state.dagSize,
+        },
+    };
+    if (state.outcome)
+        doc.outcome = state.outcome;
+    return doc;
+}
+/** A no-op publisher — the default when nothing is wired (dry loop, tests). */
+export const NULL_PUBLISHER = { async publish() { } };
+/** Publishes by shelling `harness runstatus publish` with the doc on a temp file. */
+export class CliRunPublisher {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async publish(state) {
+        const doc = runStateToDocument(state);
+        let tmp;
+        try {
+            const dir = mkdtempSync(join(tmpdir(), "orch-runstatus-"));
+            tmp = join(dir, "doc.json");
+            writeFileSync(tmp, JSON.stringify(doc));
+            const args = [
+                "runstatus",
+                "publish",
+                "--file",
+                tmp,
+                "--spool",
+                this.opts.spoolDir,
+                ...(this.opts.machineId ? ["--machine", this.opts.machineId] : []),
+            ];
+            const result = await callProcess({
+                command: this.opts.harnessBin,
+                args: [...(this.opts.harnessBinArgs ?? []), ...args],
+                cwd: this.opts.cwd,
+            });
+            if (result.code !== 0)
+                throw new Error((result.stderr || result.stdout).trim() || `exit ${result.code}`);
+        }
+        catch (e) {
+            // degrade to a warning — never stop the loop.
+            this.opts.log.append({
+                t: "lane.note",
+                unitId: state.runId || "run",
+                note: `run-status publish failed (${e.message.trim()}) — the board may show this run as stale`,
+            });
+        }
+        finally {
+            if (tmp) {
+                try {
+                    rmSync(join(tmp, ".."), { recursive: true, force: true });
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=publish.js.map

package/dist/internal/orchestration/worktree/index.js

@@ -0,0 +1,89 @@
+/** Per-unit Git worktrees: the control checkout owns orchestration state while
+ * every implementation lane gets an isolated branch checkout. */
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+export class GitWorktreeManager {
+    controlRepo;
+    root;
+    gitBin;
+    constructor(opts) {
+        this.controlRepo = resolve(opts.controlRepo);
+        this.root = resolve(opts.root);
+        this.gitBin = opts.gitBin ?? "git";
+    }
+    async acquire(request) {
+        await mkdir(this.root, { recursive: true });
+        const path = join(this.root, laneName(request.unitId));
+        const existing = await this.registeredPath(request.branch);
+        if (existing) {
+            if (resolve(existing) !== resolve(path)) {
+                throw new Error(`branch ${request.branch} is already checked out at ${existing}`);
+            }
+            return { unitId: request.unitId, branch: request.branch, path, controlRepo: this.controlRepo };
+        }
+        const branchExists = (await this.git(["show-ref", "--verify", "--quiet", `refs/heads/${request.branch}`], true)).code === 0;
+        const args = branchExists
+            ? ["worktree", "add", path, request.branch]
+            : ["worktree", "add", "-b", request.branch, path, request.baseBranch];
+        await this.git(args);
+        return { unitId: request.unitId, branch: request.branch, path, controlRepo: this.controlRepo };
+    }
+    async release(workspace) {
+        const status = await this.git(["-C", workspace.path, "status", "--porcelain"]);
+        if (status.stdout.trim()) {
+            throw new Error(`refusing to remove dirty worktree for ${workspace.unitId}: ${workspace.path}`);
+        }
+        await this.git(["worktree", "remove", workspace.path]);
+    }
+    async registeredPath(branch) {
+        const result = await this.git(["worktree", "list", "--porcelain"]);
+        let path;
+        for (const line of result.stdout.split(/\r?\n/)) {
+            if (line.startsWith("worktree "))
+                path = line.slice("worktree ".length);
+            if (line === `branch refs/heads/${branch}`)
+                return path;
+            if (!line)
+                path = undefined;
+        }
+        return undefined;
+    }
+    async git(args, allowFailure = false) {
+        try {
+            const { stdout, stderr } = await run(this.gitBin, args, { cwd: this.controlRepo });
+            return { code: 0, stdout, stderr };
+        }
+        catch (error) {
+            const detail = error;
+            const result = {
+                code: typeof detail.code === "number" ? detail.code : 1,
+                stdout: detail.stdout ?? "",
+                stderr: detail.stderr ?? "",
+            };
+            if (allowFailure)
+                return result;
+            throw new Error(`git ${args.join(" ")} failed: ${(result.stderr || result.stdout).trim()}`, { cause: error });
+        }
+    }
+}
+/** Test/backward-compatibility seam for pure loops that do not touch a checkout. */
+export class InPlaceWorkspaceManager {
+    path;
+    constructor(path = process.cwd()) {
+        this.path = path;
+    }
+    async acquire(request) {
+        return { unitId: request.unitId, branch: request.branch, path: this.path, controlRepo: this.path };
+    }
+    async release(_workspace) { }
+}
+function laneName(unitId) {
+    const readable = basename(unitId.replaceAll("\\", "/")).replace(/[^a-zA-Z0-9._-]+/g, "-");
+    const hash = createHash("sha256").update(unitId).digest("hex").slice(0, 10);
+    return `${readable || "unit"}-${hash}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/adapters/index.js

@@ -0,0 +1,19 @@
+/**
+ * adapters — generates the per-agent surface from ONE protocol template:
+ * AGENTS.md (vendor-neutral, Linux Foundation-stewarded), a CLAUDE.md that
+ * imports it, Claude Code hooks calling `harness gate --pre`, Cursor
+ * allowlists, Codex sandbox config, git hooks, CI workflow.
+ *
+ * Rules:
+ *   - generated files carry a content hash; the `gen:fresh` gate fails on
+ *     hand-edits or staleness — adapters may never fork from policy
+ *   - adapters are UX (prompt) and fast feedback (hooks); the substrate is
+ *     the guarantee and must be sufficient alone
+ */
+export function generate(_target, _projectRoot) {
+    throw new Error("not implemented (skeleton)");
+}
+export function checkFresh(_projectRoot) {
+    throw new Error("not implemented (skeleton)");
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/agentops/index.js

@@ -0,0 +1,16 @@
+/**
+ * agentops — the layer most harnesses forget: who is this session, what may
+ * it touch, what may it spend, and what happens when it dies.
+ *
+ *   - identity: session id + model id, threaded into every envelope
+ *   - scope enforcement: out-of-scope file touches halt (fail closed)
+ *   - budgets: token/cost/time caps per unit (exceeded = halt, not warn)
+ *   - lifecycle: a dead session holding a unit `executing` is reclaimable
+ *
+ * Threat model source: OWASP Top 10 for Agentic Applications 2026 —
+ * goal hijack (ASI01), tool misuse (ASI02), privilege abuse (ASI03).
+ */
+export function checkScope(_changedFiles, _scopeGlobs) {
+    throw new Error("not implemented (skeleton)");
+}
+//# sourceMappingURL=index.js.map

package/dist/internal/system/agentops/scope.js

@@ -0,0 +1,67 @@
+/** Authoritative verify-time scope attestation (independent of agent hooks). */
+import { execFileSync } from "node:child_process";
+import picomatch from "picomatch";
+import { canonicalUnitId, loadSpecs } from "../spec/index.js";
+const norm = (path) => path.replaceAll("\\", "/").replace(/^\.\//, "");
+/** Return every changed path outside the effective scope. Empty scope fails closed. */
+export function checkScope(changedFiles, effectiveScope) {
+    if (effectiveScope.length === 0)
+        return changedFiles.map(norm);
+    const matches = picomatch(effectiveScope.map(norm), { dot: true });
+    return changedFiles.map(norm).filter((path) => !matches(path));
+}
+/** Derive both sides of the scope assertion from git + the accepted spec. */
+export function attestScope(opts) {
+    if (!opts.baseRef || !opts.specsDir) {
+        return {
+            attested: false,
+            attempted: false,
+            changedFiles: [],
+            effectiveScope: [],
+            violations: [],
+            reason: "no unit context: verify was called without --base and --specs, so scope was not attested",
+        };
+    }
+    try {
+        const unitId = canonicalUnitId(opts.unitId);
+        const loaded = loadSpecs(opts.specsDir).find(({ spec }) => canonicalUnitId(spec.id) === unitId);
+        if (!loaded) {
+            return {
+                attested: false,
+                attempted: true,
+                changedFiles: [],
+                effectiveScope: [],
+                violations: [],
+                reason: `no accepted spec found for unit "${unitId}" under ${opts.specsDir}`,
+            };
+        }
+        const stdout = execFileSync("git", ["diff", "--name-only", `${opts.baseRef}...HEAD`, "--"], { cwd: opts.componentDir, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+        const changedFiles = stdout
+            .split(/\r?\n/)
+            .map((path) => norm(path.trim()))
+            .filter(Boolean);
+        const effectiveScope = loaded.spec.scope.map(norm);
+        const violations = checkScope(changedFiles, effectiveScope);
+        return {
+            attested: violations.length === 0,
+            attempted: true,
+            changedFiles,
+            effectiveScope,
+            violations,
+            ...(violations.length > 0
+                ? { reason: `changed paths outside declared scope: ${violations.join(", ")}` }
+                : {}),
+        };
+    }
+    catch (error) {
+        return {
+            attested: false,
+            attempted: true,
+            changedFiles: [],
+            effectiveScope: [],
+            violations: [],
+            reason: `scope attestation failed: ${error.message}`,
+        };
+    }
+}
+//# sourceMappingURL=scope.js.map

package/dist/internal/system/assets.js

@@ -0,0 +1,45 @@
+/**
+ * Package-owned asset resolution from `import.meta.url` (workspace or staged).
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export function resolvePackageAsset(fromUrl, ...markers) {
+    let dir = dirname(fileURLToPath(fromUrl));
+    while (true) {
+        for (const marker of markers) {
+            const candidate = join(dir, marker);
+            if (existsSync(candidate))
+                return resolve(candidate);
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error(`package asset not found (looked for ${markers.join(" | ")} from ${fileURLToPath(fromUrl)})`);
+        }
+        dir = parent;
+    }
+}
+export function packageSchemaDir(fromUrl = import.meta.url) {
+    return resolvePackageAsset(fromUrl, "schema");
+}
+export function packageProfilesDir(fromUrl = import.meta.url) {
+    return resolvePackageAsset(fromUrl, "profiles");
+}
+/** Workspace: `ci-templates/`; staged package: `templates/`. */
+export function packageTemplatesDir(fromUrl = import.meta.url) {
+    return resolvePackageAsset(fromUrl, "templates", "ci-templates");
+}
+export function targetPath(repoRoot, ...segments) {
+    return resolve(repoRoot, ...segments);
+}
+export function targetOwnedPaths(repoRoot) {
+    const root = resolve(repoRoot);
+    return {
+        specs: targetPath(root, "specs"),
+        systemToml: targetPath(root, "system.toml"),
+        harnessDir: targetPath(root, ".harness"),
+        componentToml: targetPath(root, "component.toml"),
+        ledgerDir: targetPath(root, ".harness", "ledger"),
+    };
+}
+//# sourceMappingURL=assets.js.map

package/dist/internal/system/board/cli.js

@@ -0,0 +1,56 @@
+/**
+ * `harness board build` — render the operations board from the ledger.
+ *
+ *   harness board build [--ledger <dir>] [--spool <dir>] [--out board.html] [--json]
+ *
+ * Every panel is a filter over the in-memory projection (sub-millisecond);
+ * empty panels render "insufficient data", never a fake zero. `--spool` adds
+ * the live "runs" overlay from the run-status spool (P7.3).
+ */
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { projectLedger } from "../hub/index.js";
+import { projectRuns } from "../runstatus/index.js";
+import { buildBoard, renderBoardHtml } from "./index.js";
+import { startBoardServer } from "./live.js";
+function flag(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+export function boardCommand(args) {
+    if (args[0] !== "build") {
+        process.stderr.write("harness board build [--ledger <dir>] [--spool <dir>] [--out board.html] [--json]\n");
+        return 2;
+    }
+    const spool = flag(args, "spool");
+    const board = buildBoard(projectLedger(flag(args, "ledger") ?? ".harness/ledger"), new Date().toISOString(), spool ? projectRuns(spool) : undefined);
+    if (args.includes("--json")) {
+        process.stdout.write(JSON.stringify(board, null, 2) + "\n");
+        return 0;
+    }
+    const out = flag(args, "out") ?? "board.html";
+    writeFileSync(out, renderBoardHtml(board));
+    const insufficient = Object.values(board.panels).filter((p) => p.status === "insufficient-data").length;
+    process.stdout.write(`wrote ${out} — ${Object.keys(board.panels).length} panels (${insufficient} insufficient-data)\n`);
+    return 0;
+}
+export function parseBoardServeOptions(args, cwd = process.cwd()) {
+    const roots = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--root" && args[i + 1])
+            roots.push(resolve(cwd, args[++i]));
+    }
+    const portText = flag(args, "port");
+    const refreshText = flag(args, "refresh");
+    const port = portText === undefined ? 4317 : Number(portText);
+    const refreshMs = refreshText === undefined ? 2_000 : Number(refreshText);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535)
+        throw new Error(`invalid --port: ${portText}`);
+    if (!Number.isFinite(refreshMs) || refreshMs < 250)
+        throw new Error(`invalid --refresh: ${refreshText}`);
+    return { roots: roots.length ? roots : [resolve(cwd)], host: "127.0.0.1", port, refreshMs };
+}
+export function boardServeCommand(args, cwd = process.cwd()) {
+    return startBoardServer(parseBoardServeOptions(args, cwd));
+}
+//# sourceMappingURL=cli.js.map