harnery 0.37.0 → 0.38.0

package/dist/lib/durable-job.js

@@ -0,0 +1,296 @@
+// Durable job records: a small on-disk representation of "a job that outlives
+// the client that launched it". A supervisor process owns the record; a client
+// only reads it. A bridge drop, a closed terminal, or a killed client
+// therefore interrupts the *view* of the job, never the job itself.
+//
+// Layout, under a caller-supplied base directory:
+//
+//   <base>/jobs/<job_id>/job.json      immutable description (argv, cwd, resource)
+//   <base>/jobs/<job_id>/status.json   mutable state, rewritten atomically
+//   <base>/jobs/<job_id>/job.log       merged child stdout + stderr
+//
+// Classification is fail-closed, mirroring qa-status: liveness is proven by the
+// PID, never assumed from the status document. A non-terminal state whose PID
+// is dead classifies as "dead", never as "running".
+//
+// Toolkit tier: this module must not import src/core (layering check).
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+export const DURABLE_JOB_SCHEMA_VERSION = 1;
+/** How often the supervisor rewrites status.json while a job runs. */
+export const DURABLE_JOB_HEARTBEAT_MS = 15_000;
+/** A running job whose heartbeat is older than this earns a staleness warning,
+ * but stays "running" while its PID is alive. */
+export const DURABLE_JOB_HEARTBEAT_STALE_MS = 120_000;
+export const DURABLE_JOB_DOCUMENT_FILENAME = "job.json";
+export const DURABLE_JOB_STATUS_FILENAME = "status.json";
+export const DURABLE_JOB_LOG_FILENAME = "job.log";
+const JOBS_DIRNAME = "jobs";
+const WRITTEN_STATES = new Set(["launching", "queued", "running", "completed"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Default PID liveness probe. EPERM counts as alive; only ESRCH is dead. */
+function defaultPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== "ESRCH";
+    }
+}
+/** Directory holding every job record under a base directory. */
+export function jobsRoot(base) {
+    return join(resolve(base), JOBS_DIRNAME);
+}
+/** Directory of one job record. Does not create it. */
+export function jobDirFor(base, jobId) {
+    return join(jobsRoot(base), jobId);
+}
+/** Create (idempotently) the directory for one job and return its path. */
+export function createJobDir(base, jobId) {
+    const dir = jobDirFor(base, jobId);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function jobLogPath(jobDir) {
+    return join(resolve(jobDir), DURABLE_JOB_LOG_FILENAME);
+}
+function writeAtomic(path, body) {
+    const tmp = `${path}.${randomUUID().slice(0, 8)}.tmp`;
+    writeFileSync(tmp, body);
+    renameSync(tmp, path);
+}
+/** Write the immutable job description. */
+export function writeJobDocument(jobDir, document) {
+    writeAtomic(join(resolve(jobDir), DURABLE_JOB_DOCUMENT_FILENAME), `${JSON.stringify(document, null, 2)}\n`);
+}
+/** Replace the status document atomically, so a reader never sees a torn file. */
+export function writeJobStatus(jobDir, status) {
+    writeAtomic(join(resolve(jobDir), DURABLE_JOB_STATUS_FILENAME), `${JSON.stringify(status, null, 2)}\n`);
+}
+function readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+/** Read the job description, or null when it is missing or unusable. */
+export function readJobDocument(jobDir) {
+    const path = join(resolve(jobDir), DURABLE_JOB_DOCUMENT_FILENAME);
+    let parsed;
+    try {
+        parsed = readJson(path);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    if (typeof parsed.job_id !== "string")
+        return null;
+    return {
+        schema_version: typeof parsed.schema_version === "number"
+            ? parsed.schema_version
+            : DURABLE_JOB_SCHEMA_VERSION,
+        job_id: parsed.job_id,
+        resource: typeof parsed.resource === "string" ? parsed.resource : "",
+        capacity: typeof parsed.capacity === "number" ? parsed.capacity : 1,
+        label: typeof parsed.label === "string" ? parsed.label : "",
+        argv: Array.isArray(parsed.argv)
+            ? parsed.argv.filter((a) => typeof a === "string")
+            : [],
+        cwd: typeof parsed.cwd === "string" ? parsed.cwd : "",
+        created_at: typeof parsed.created_at === "string" ? parsed.created_at : "",
+    };
+}
+/** Read the status document, or null when it is missing or unusable. */
+export function readJobStatus(jobDir) {
+    const path = join(resolve(jobDir), DURABLE_JOB_STATUS_FILENAME);
+    let parsed;
+    try {
+        parsed = readJson(path);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    if (typeof parsed.job_id !== "string")
+        return null;
+    if (typeof parsed.state !== "string" || !WRITTEN_STATES.has(parsed.state))
+        return null;
+    const queue = parsed.queue;
+    return {
+        schema_version: typeof parsed.schema_version === "number"
+            ? parsed.schema_version
+            : DURABLE_JOB_SCHEMA_VERSION,
+        job_id: parsed.job_id,
+        pid: typeof parsed.pid === "number" ? parsed.pid : 0,
+        state: parsed.state,
+        started_at: typeof parsed.started_at === "string" ? parsed.started_at : "",
+        updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : "",
+        ...(isRecord(queue) &&
+            typeof queue.resource === "string" &&
+            typeof queue.waiting_since === "string"
+            ? { queue: { resource: queue.resource, waiting_since: queue.waiting_since } }
+            : {}),
+        ...(typeof parsed.exit_code === "number" || parsed.exit_code === null
+            ? { exit_code: parsed.exit_code }
+            : {}),
+        ...(typeof parsed.signal === "string" || parsed.signal === null
+            ? { signal: parsed.signal }
+            : {}),
+    };
+}
+/**
+ * Classify one job directory, fail-closed. "completed" is terminal and carries
+ * the wrapped command's exit code. Any other written state is trusted only
+ * while the supervisor PID is alive; otherwise the job is "dead" — the record
+ * outlived the process that owned it.
+ */
+export function classifyJob(jobDir, deps = {}) {
+    const isAlive = deps.pidAlive ?? defaultPidAlive;
+    const nowMs = deps.now ? deps.now() : Date.now();
+    const abs = resolve(jobDir);
+    if (!existsSync(abs))
+        return { ok: false, error: `no such job directory: ${abs}` };
+    const statusPath = join(abs, DURABLE_JOB_STATUS_FILENAME);
+    if (!existsSync(statusPath)) {
+        return {
+            ok: false,
+            error: `${abs} carries no ${DURABLE_JOB_STATUS_FILENAME}: not a job directory`,
+        };
+    }
+    const status = readJobStatus(abs);
+    if (!status) {
+        return { ok: false, error: `${statusPath} is not a readable job status document` };
+    }
+    const document = readJobDocument(abs);
+    let heartbeatAgeMs = null;
+    const updatedMs = Date.parse(status.updated_at);
+    if (!Number.isNaN(updatedMs))
+        heartbeatAgeMs = Math.max(0, nowMs - updatedMs);
+    const base = {
+        job_id: status.job_id,
+        pid: status.pid > 0 ? status.pid : null,
+        resource: document?.resource ?? null,
+        label: document?.label ?? null,
+        argv: document?.argv ?? null,
+        created_at: document?.created_at ?? null,
+        started_at: status.started_at || null,
+        updated_at: status.updated_at || null,
+        heartbeat_age_ms: heartbeatAgeMs,
+        job_dir: abs,
+        log_path: jobLogPath(abs),
+    };
+    if (status.state === "completed") {
+        return {
+            ok: true,
+            report: {
+                ...base,
+                state: "completed",
+                terminal: true,
+                exit_code: status.exit_code ?? null,
+                signal: status.signal ?? null,
+                warnings: [],
+            },
+        };
+    }
+    if (!(status.pid > 0 && isAlive(status.pid))) {
+        return {
+            ok: true,
+            report: {
+                ...base,
+                state: "dead",
+                terminal: false,
+                exit_code: null,
+                signal: null,
+                ...(status.queue ? { queue: status.queue } : {}),
+                warnings: [],
+            },
+        };
+    }
+    const warnings = [];
+    if (status.state === "running" &&
+        heartbeatAgeMs !== null &&
+        heartbeatAgeMs > DURABLE_JOB_HEARTBEAT_STALE_MS) {
+        warnings.push(`heartbeat stale: last update ${Math.round(heartbeatAgeMs / 1000)}s ago ` +
+            `(threshold ${DURABLE_JOB_HEARTBEAT_STALE_MS / 1000}s), but pid ${status.pid} is alive`);
+    }
+    return {
+        ok: true,
+        report: {
+            ...base,
+            state: status.state,
+            terminal: false,
+            exit_code: null,
+            signal: null,
+            ...(status.queue ? { queue: status.queue } : {}),
+            warnings,
+        },
+    };
+}
+/**
+ * Every job record under a base directory, newest first. Ordering keys on the
+ * description's created_at, falling back to the status document's started_at,
+ * then to the directory name, so a record missing its description still lists.
+ */
+export function listJobs(base, deps = {}) {
+    const root = jobsRoot(base);
+    let names;
+    try {
+        names = readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        const dir = join(root, name);
+        const document = readJobDocument(dir);
+        const classified = classifyJob(dir, deps);
+        const createdAt = document?.created_at || (classified.ok ? classified.report.started_at : null) || null;
+        const parsed = createdAt !== null ? Date.parse(createdAt) : Number.NaN;
+        entries.push({
+            entry: {
+                job_id: document?.job_id ?? name,
+                job_dir: dir,
+                created_at: createdAt,
+                document,
+                report: classified.ok ? classified.report : null,
+                ...(classified.ok ? {} : { error: classified.error }),
+            },
+            sortKey: Number.isNaN(parsed) ? 0 : parsed,
+        });
+    }
+    entries.sort((a, b) => {
+        if (b.sortKey !== a.sortKey)
+            return b.sortKey - a.sortKey;
+        return b.entry.job_id.localeCompare(a.entry.job_id);
+    });
+    return entries.map((item) => item.entry);
+}
+/** Describe a job's outcome as a process exit code: the wrapped command's own
+ * code, 1 when it died on a signal, 4 when the record is dead. */
+export function jobExitCode(report) {
+    if (report.state === "dead")
+        return 4;
+    if (!report.terminal)
+        return 5;
+    if (report.signal !== null)
+        return 1;
+    return report.exit_code ?? 1;
+}
+/** Format a duration the way the status commands do. */
+export function formatJobAge(ms) {
+    const totalSeconds = Math.max(0, Math.round(ms / 1000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ${totalSeconds % 60}s`;
+    const hours = Math.floor(minutes / 60);
+    return `${hours}h ${minutes % 60}m`;
+}

package/dist/lib/http/client.d.ts

@@ -1,4 +1,4 @@
-import type { CookieJar } from "../cookies/index.js";
+import { type CookieJar, type ExtraCookies } from "../cookies/index.js";
 /**
  * Simple cookie-aware HTTP client.
  *
@@ -36,6 +36,12 @@ export interface FetchOptions<TResponseType extends FetchResponseType = "text">
      * only land when the key isn't already set.
      */
     extraHeaders?: (url: string) => Record<string, string>;
+    /**
+     * Optional callback that returns extra cookies to persist into `jar`
+     * before the Cookie header is built. Ignored when no jar is passed
+     * (`--no-cookies`). Must stay synchronous.
+     */
+    extraCookies?: ExtraCookies;
     /** Response body representation. Default `text`; use `bytes` for lossless file output. */
     responseType?: TResponseType;
 }

package/dist/lib/http/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;;;;;;;;GASG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM;IAC5E,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,0FAA0F;IAC1F,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,KAAK,SAAS,CAAC,aAAa,SAAS,iBAAiB,IAAI,aAAa,SAAS,OAAO,GACnF,UAAU,GACV,MAAM,CAAC;AAEX,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,MAAM;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM,EACjF,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,YAAY,CAAC,aAAa,CAAM,GACrC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CA8EhD"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,YAAY,EAClB,MAAM,qBAAqB,CAAC;AAE7B;;;;;;;;;GASG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM;IAC5E,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,8CAA8C;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD;;;;OAIG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,0FAA0F;IAC1F,YAAY,CAAC,EAAE,aAAa,CAAC;CAC9B;AAED,KAAK,SAAS,CAAC,aAAa,SAAS,iBAAiB,IAAI,aAAa,SAAS,OAAO,GACnF,UAAU,GACV,MAAM,CAAC;AAEX,MAAM,WAAW,WAAW,CAAC,KAAK,GAAG,MAAM;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,aAAa,SAAS,iBAAiB,GAAG,MAAM,EACjF,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,YAAY,CAAC,aAAa,CAAM,GACrC,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,CA+EhD"}

package/dist/lib/http/client.js

@@ -1,3 +1,4 @@
+import { applyExtraCookies, } from "../cookies/index.js";
 /**
  * Fetch a URL with optional cookie-jar attach + persist.
  *
@@ -9,6 +10,7 @@
 export async function fetchWithJar(url, opts = {}) {
     const headers = { ...(opts.headers ?? {}) };
     if (opts.jar) {
+        applyExtraCookies(url, opts.jar, opts.extraCookies);
         const cookieHeader = opts.jar.header(url);
         if (cookieHeader && !headers.Cookie && !headers.cookie) {
             headers.Cookie = cookieHeader;

package/dist/lib/instructions/templates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CAgHR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAmVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../../src/lib/instructions/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAClD,sEAAsE;AACtE,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,MAAM,EAAE,OAAO,CAAC;IAChB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,GAAG,EAAE,OAAO,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,WAAoE,GAC3E,MAAM,CAgHR;AAID,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAsVD,eAAO,MAAM,MAAM,EAAE,aAAa,EAiDjC,CAAC"}

package/dist/lib/instructions/templates.js

@@ -248,10 +248,13 @@ auto-route into contribute.
 ## Create (\`create <objective>\`)
 
 The web UI is the member + steward picker; don't create from the CLI (that skips
-the steward choice). Emit the link with the objective URL-encoded:
+the steward choice). Read the dashboard base URL from the active Harnery web
+status or start output, which resolves the project's configured \`web.port\`.
+Append the URL-encoded objective to this path; never assume a port or reuse a
+dashboard URL from another project:
 
 \`\`\`
-http://localhost:4276/councils/new?objective=<encoded>
+<configured-dashboard-base-url>/councils/new?objective=<encoded>
 \`\`\`
 
 If the dev server isn't up, start it with \`${b} web up\`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harnery",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Multi-agent coordination for AI coding agents - Claude Code, Cursor, and Codex.",
   "license": "MIT",
   "author": "Ryan Kelly",
@@ -152,6 +152,11 @@
       "types": "./dist/core/policy/index.d.ts",
       "import": "./dist/core/policy/index.js"
     },
+    "./lib/admission": {
+      "bun": "./src/lib/admission.ts",
+      "types": "./dist/lib/admission.d.ts",
+      "import": "./dist/lib/admission.js"
+    },
     "./lib/agent-browser": {
       "bun": "./src/lib/agent-browser/index.ts",
       "types": "./dist/lib/agent-browser/index.d.ts",
@@ -230,7 +235,7 @@
     "access": "public",
     "provenance": true
   },
-  "packageManager": "bun@1.3.3",
+  "packageManager": "bun@1.4.0",
   "scripts": {
     "build": "npm run clean && tsc -p tsconfig.build.json && node scripts/rewrite-dts-extensions.mjs",
     "clean": "rm -rf dist",
@@ -244,6 +249,7 @@
     "lint:fix": "bun x @biomejs/biome check --write src",
     "format": "bun x @biomejs/biome format --write src",
     "test": "bun run scripts/test.mjs",
+    "test:list": "bun run scripts/test.mjs --list",
     "test:web": "cd web && bun install && bun test",
     "test:integration": "bash tests/integration/run.sh",
     "smoke": "node scripts/smoke-test.mjs",

package/src/commander.ts

@@ -121,6 +121,15 @@ export interface HarneryProgramContext {
    * zones behind a WAF). harn standalone skips the callback entirely.
    */
   extraHeaders?: (url: string) => Record<string, string>;
+  /**
+   * Optional callback that returns extra cookies to persist into the shared
+   * jar before `fetch` / `browse` attach it. Runs only when a jar is in
+   * play (`--no-cookies` skips it). Use this for host-minted session
+   * cookies; `extraHeaders` cannot merge a `Cookie` header once the jar
+   * has already set one. Must stay synchronous, same as `extraHeaders`.
+   * harn standalone skips the callback entirely.
+   */
+  extraCookies?: import("./lib/cookies/index.ts").ExtraCookies;
   /**
    * Host-injected vision-model call for `browse --check-critique`. harnery
    * ships no model client or API key; a consumer wires this to its own
@@ -443,9 +452,48 @@ function harneryCommandBundles({
     lazy(
       "qa-run <target>",
       `Run the whole page-QA matrix in one command (planner, deterministic gates per context, interactions, critique, snapshot) via child \`${binName} browse\` processes; writes page-qa-result.json with a fail-closed verdict.`,
-      async (program) => (await import("./commands/qa-run.ts")).registerQaRunCommand(program, emit),
+      async (program) =>
+        (await import("./commands/qa-run.ts")).registerQaRunCommand(program, emit, context),
+      { hasOptions: true },
+    ),
+    lazy(
+      "review-pack",
+      "Page review packs: capture a page's rendering contexts (tiles, DOM, signature) into a directory an agent can review without a browser, and judge a pack from disk through one bounded pool of vision calls.",
+      async (program) =>
+        (await import("./commands/review-pack.ts")).registerReviewPackCommand(
+          program,
+          emit,
+          context,
+        ),
+      { hasOptions: true },
+    ),
+    lazy(
+      "qa-verify <path>",
+      "Verify a qa-run result is fresh evidence for a specific invocation: match its run identity (run_id, job digest, tested revision, age, recorded output directory) against expectations. Fail-closed on missing identity.",
+      async (program) =>
+        (await import("./commands/qa-verify.ts")).registerQaVerifyCommand(program, emit),
       { hasOptions: true },
     ),
+    lazy(
+      "qa-record <target>",
+      "Record hand-performed page QA as a standard result document: same schema, run identity, stage timings, and freshness guarantees as qa-run, marked evidence_source manual so it can report a defect but never a pass.",
+      async (program) =>
+        (await import("./commands/qa-record.ts")).registerQaRecordCommand(program, emit, context),
+      { hasOptions: true },
+    ),
+    lazy(
+      "qa-status [path]",
+      "Report a qa-run's live state (queued/launching/running/completed/dead) from its run-status.json, PID liveness, and result document; --wait reconnects to a detached run and exits with its verdict; --queue shows the machine-wide browser-qa admission queue.",
+      async (program) =>
+        (await import("./commands/qa-status.ts")).registerQaStatusCommand(program, emit, context),
+      { hasOptions: true },
+    ),
+    lazy(
+      "admission",
+      "Machine-wide admission control for heavy jobs: `admission run --resource <name> -- <command…>` waits for a FIFO slot then runs the command; `admission status` lists holders and waiters per resource.",
+      async (program) =>
+        (await import("./commands/admission.ts")).registerAdmissionCommand(program, emit),
+    ),
     lazy(
       "browse-session",
       "Control an opted-in headed browse session through an owner-only descriptor",
@@ -456,7 +504,7 @@ function harneryCommandBundles({
       "browse-ai <url>",
       `agent-browser (Vercel Labs) wrapper: accessibility-tree snapshots with element refs (@e1, @e2) for LLM consumption. Daemon-mode: successive calls reuse the same browser instance. Sister to ${binName} browse (Playwright).`,
       async (program) =>
-        (await import("./commands/browse-ai.ts")).registerBrowseAiCommand(program, emit),
+        (await import("./commands/browse-ai.ts")).registerBrowseAiCommand(program, emit, context),
       { hasOptions: true },
     ),
     {