@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/cli/export.js

@@ -2,26 +2,17 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { stringify as stringifyYaml } from "yaml";
 import { atomicWriteFile } from "../io/atomic-write.js";
-import { withoutDerivedPolicies } from "../runtime/workflow-policies.js";
+import { formatPostureWarning } from "../schema/removed-keys.js";
 import { loadManifest } from "./loader.js";
 const SECRET_KEY_PATTERN = /(?:_|^)(KEY|TOKEN|SECRET|PASSWORD|API_KEY)$/i;
 const REDACTED = "<REDACTED>";
 export const SANITIZE_FOOTER = "# sanitised: /home/<user>/ paths replaced with ~/; env values whose key " +
     "matches /(_|^)(KEY|TOKEN|SECRET|PASSWORD|API_KEY)$/i are redacted. The " +
-    "sanitiser does NOT touch secrets in command:[] arrays or in policy " +
-    "`requires.ledger_tag` values; review before sharing.";
+    "sanitiser does NOT touch secrets in command:[] arrays; review before sharing.";
 export function exportManifest(opts = {}) {
-    const { manifest: loaded } = loadManifest(opts);
-    // F7 (review round 2, 99f47307 Slice 1): `loadManifest` folds
-    // `workflows[]`-derived policies into `manifest.policies` (F2), but
-    // `harness export` is meant to emit what the OPERATOR declared, not a
-    // computed view — a derived policy re-imported via `harness init
-    // --config <exported file>`-style workflows would then be a
-    // hand-authored duplicate of something the next `harness apply` would
-    // derive again anyway. `withoutDerivedPolicies` (identity-based; see
-    // workflow-policies.ts) restores the hand-authored view before
-    // projecting; `harness list policies` / `doctor` show the derived pair.
-    const manifest = withoutDerivedPolicies(loaded);
+    const { manifest, warnings } = loadManifest(opts);
+    // `harness export` emits the manifest exactly as `loadManifest` parsed
+    // it, nothing computed on top of it.
     const projection = manifest;
     const projected = opts.sanitize ? sanitize(projection, os.homedir()) : projection;
     let output;
@@ -44,13 +35,13 @@ export function exportManifest(opts = {}) {
         atomicWriteFile(target, output);
         wroteTo = target;
     }
-    return { output, manifest, sanitized: !!opts.sanitize, wroteTo };
+    return { output, manifest, sanitized: !!opts.sanitize, wroteTo, warnings: warnings.map(formatPostureWarning) };
 }
 /**
  * Best-effort sanitiser. Walks the manifest, replaces `/home/<user>/...` paths
  * with `~/...` and redacts env values whose key looks credential-shaped. Does
  * NOT touch command:[] entries (they often contain absolute paths that are
- * intentional and not secret) and does NOT inspect policy ledger_tag values.
+ * intentional and not secret).
  */
 export function sanitize(value, homeDir) {
     return walk(value, homeDir, []);

package/dist/cli/export.js.map

@@ -1 +1 @@
-{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/cli/export.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/cli/export.ts"],"names":[],"mappings":"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"}

package/dist/cli/gate/codex-disable.d.ts

@@ -0,0 +1,29 @@
+import { type GateDisableCandidate } from "./disable.js";
+import { type CodexDisabledUnit, type CodexRetiredSnapshot } from "./codex-snapshot.js";
+export interface CodexGateDisableOptions {
+    /** `~/.codex/config.toml` override. */
+    configPath?: string;
+    /** Test-injectable home dir for the default config path. */
+    homeDir?: string;
+    /** Literal substring of a unit's `matcher`; absent means list only. */
+    matcher?: string;
+    now?: Date;
+}
+export interface CodexGateCandidate extends GateDisableCandidate {
+    /** True for a unit an earlier `gate disable` already neutralised. */
+    disabled: boolean;
+}
+export type CodexGateDisableResult = {
+    mode: "list";
+    configPath: string;
+    candidates: CodexGateCandidate[];
+} | {
+    mode: "remove";
+    configPath: string;
+    backupPath: string;
+    snapshotPath: string;
+    neutralised: CodexDisabledUnit[];
+    /** A spent live snapshot this disable retired before starting a fresh one. */
+    retired: CodexRetiredSnapshot | null;
+};
+export declare function codexGateDisable(opts?: CodexGateDisableOptions): CodexGateDisableResult;

package/dist/cli/gate/codex-disable.js

@@ -0,0 +1,195 @@
+// `harness gate disable --runtime codex`: neutralises the harness-managed
+// hook units whose `matcher` contains `--matcher` by emptying their
+// `hooks = [...]` line in place, after writing a backup and a snapshot of the
+// original lines. With no `--matcher` it only lists the units. At most one
+// snapshot per config is live: a disable merges into it, retires it first
+// when it is spent, or refuses when the config no longer matches it. The
+// block is read by the installer's own scanner, so a malformed block refuses.
+// A later `harness apply --runtime codex --install` re-renders the whole block
+// and so brings the units back.
+// Why and how: docs/okf/gate-kill-switch.md (Codex section).
+import * as fs from "node:fs";
+import { assertCodexHookEditInvariant, existingFileMode, readCodexManagedHookUnits, } from "../apply/install-codex-config.js";
+import { atomicWriteFile } from "../../io/atomic-write.js";
+import { GateDisableError } from "./disable.js";
+import { CODEX_NEUTRALISED_HOOKS, CODEX_SNAPSHOT_TARGET, CODEX_SNAPSHOT_VERSION, codexConfigFlag, codexSnapshotPath, latestInstall, planCodexRestore, readLiveCodexSnapshots, resolveCodexConfig, retireCodexSnapshot, spentCodexSnapshot, toGateError, } from "./codex-snapshot.js";
+import { backupPath, sha256Hex } from "./snapshot.js";
+export function codexGateDisable(opts = {}) {
+    const { requestedPath, configPath, namedPath } = resolveCodexConfig(opts, (m) => new GateDisableError(m));
+    let text;
+    try {
+        text = fs.readFileSync(configPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new GateDisableError(`Codex config not found: ${requestedPath}; nothing to disable`);
+        }
+        throw new GateDisableError(`cannot read ${requestedPath}: ${err.message}`);
+    }
+    let block;
+    try {
+        block = readCodexManagedHookUnits(text, configPath);
+    }
+    catch (err) {
+        throw toGateError(err, (m) => new GateDisableError(m), namedPath);
+    }
+    if (block === null) {
+        throw new GateDisableError(`${requestedPath} has no harness-managed Codex hook block (no '# BEGIN harness-managed codex hooks' ` +
+            `fence); nothing to disable. \`harness apply --runtime codex --install${codexConfigFlag(namedPath, "--codex-config")}\` ` +
+            "writes that block.");
+    }
+    const seen = new Map();
+    const units = block.units.map((unit, ordinal) => {
+        const eventIndex = seen.get(unit.event) ?? 0;
+        seen.set(unit.event, eventIndex + 1);
+        return { unit, ordinal, eventIndex };
+    });
+    if (typeof opts.matcher !== "string" || opts.matcher.length === 0) {
+        return {
+            mode: "list",
+            configPath: requestedPath,
+            candidates: units.map(({ unit, eventIndex }) => ({
+                event: unit.event,
+                index: eventIndex,
+                matcher: unit.matcher,
+                description: unit.commands.join("; ") || unit.id,
+                disabled: unit.disabled,
+            })),
+        };
+    }
+    const pattern = opts.matcher;
+    const matched = units.filter(({ unit }) => unit.matcher !== null && unit.matcher.includes(pattern));
+    if (matched.length === 0) {
+        throw new GateDisableError(`no hook units matched matcher substring ${JSON.stringify(pattern)} in the harness-managed block of ` +
+            `${requestedPath}. Run \`harness gate disable --runtime codex${codexConfigFlag(namedPath)}\` (no --matcher) to list the available candidates.`);
+    }
+    const active = matched.filter(({ unit }) => !unit.disabled);
+    if (active.length === 0) {
+        throw new GateDisableError(`every hook unit matching ${JSON.stringify(pattern)} in ${requestedPath} is already disabled ` +
+            `(${matched.map(({ unit }) => unit.id).join(", ")}); nothing to do. ` +
+            `\`harness gate enable --runtime codex${codexConfigFlag(namedPath)}\` restores them.`);
+    }
+    // The snapshot finds a unit again by its id, so two units must not share one.
+    const ids = new Set(block.units.map((u) => u.id));
+    if (ids.size !== block.units.length) {
+        throw new GateDisableError(`two hook units of the harness-managed block in ${requestedPath} carry the same id; ` +
+            "refusing to guess which one a restore would mean. Re-run " +
+            `\`harness apply --runtime codex --install${codexConfigFlag(namedPath, "--codex-config")}\` ` +
+            "to rewrite the block. The file is untouched.");
+    }
+    let next = "";
+    let cursor = 0;
+    for (const { unit } of active) {
+        next += text.slice(cursor, unit.hooksStart) + CODEX_NEUTRALISED_HOOKS;
+        cursor = unit.hooksEnd;
+    }
+    next += text.slice(cursor);
+    const counts = {};
+    for (const { unit } of active)
+        counts[unit.event] = (counts[unit.event] ?? 0) + 1;
+    try {
+        assertCodexHookEditInvariant(text, next, configPath, { direction: "neutralise", counts });
+    }
+    catch (err) {
+        throw toGateError(err, (m) => new GateDisableError(m), namedPath);
+    }
+    // At most one live snapshot per config. A spent one (enable would only
+    // retire it: an install re-rendered the block, the config is back at the
+    // pre-disable state, or every unit it names is enabled again) is retired
+    // here and this disable starts a fresh snapshot. Otherwise this disable
+    // joins it, which is only possible when the config is exactly what the
+    // snapshot left behind, since its pre-disable sha must stay the one state a
+    // restore rebuilds.
+    let live = readLiveCodexSnapshots(requestedPath, (m) => new GateDisableError(m), namedPath).own[0];
+    let retired = null;
+    if (live !== undefined) {
+        const spent = spentCodexSnapshot(live.snapshot, sha256Hex(text), block.units, latestInstall(requestedPath, configPath), block.generation).retire;
+        if (spent !== null) {
+            const done = "nothing was written: the live gate snapshot is spent (enable would only retire it), but ";
+            const to = retireCodexSnapshot(live.path, spent.why, (m) => new GateDisableError(m), done);
+            retired = { from: live.path, to, ...spent };
+            live = undefined;
+        }
+        else if (sha256Hex(text) !== live.snapshot.configAfterSha256) {
+            // Names --force only when it would restore; otherwise the ways out of a snapshot no gate command can apply.
+            const plan = planCodexRestore(text, block.units, configPath, live, namedPath);
+            throw new GateDisableError(`the live gate snapshot ${live.path} no longer matches ${requestedPath} (edited since the last disable) ` +
+                "and names a unit that is still off or missing, so this disable cannot join it. " +
+                (plan.ok
+                    ? `Run \`harness gate enable --runtime codex${codexConfigFlag(namedPath)} --force\`: it puts back every unit ` +
+                        "the snapshot names that is still off, keeps your other edits and retires the snapshot. Then disable " +
+                        "again. The file is untouched."
+                    : plan.reason));
+        }
+    }
+    const now = opts.now ?? new Date();
+    const backup = backupPath(requestedPath, now);
+    const mode = existingFileMode(configPath);
+    const neutralised = active.map(({ unit, ordinal, eventIndex }) => ({
+        event: unit.event,
+        eventIndex,
+        ordinal,
+        id: unit.id,
+        matcher: unit.matcher,
+        hooksText: text.slice(unit.hooksStart, unit.hooksEnd),
+    }));
+    const snapPath = live?.path ?? codexSnapshotPath(requestedPath, now);
+    const snapshot = live
+        ? {
+            ...live.snapshot,
+            configAfterSha256: sha256Hex(next),
+            neutralised: [...live.snapshot.neutralised, ...neutralised].sort((a, b) => a.ordinal - b.ordinal),
+            merges: [
+                ...(live.snapshot.merges ?? []),
+                { createdAt: now.toISOString(), matcher: pattern, configBackupPath: backup },
+            ],
+        }
+        : {
+            version: CODEX_SNAPSHOT_VERSION,
+            target: CODEX_SNAPSHOT_TARGET,
+            createdAt: now.toISOString(),
+            configPath: requestedPath,
+            configBackupPath: backup,
+            configBeforeSha256: sha256Hex(text),
+            configAfterSha256: sha256Hex(next),
+            filter: { matcher: pattern },
+            neutralised,
+            // Dates the snapshot against a later install of another block. A merge
+            // keeps the joined snapshot's marker: it joins only an unchanged config.
+            ...(block.generation !== null ? { blockGeneration: block.generation } : {}),
+        };
+    // Backup and snapshot land BEFORE the live rewrite, with the config's own
+    // mode (it holds secrets and hook trust hashes): a crash between the writes
+    // leaves the config untouched and the way back on disk.
+    // A merge changes the live snapshot before the config, so a failed config
+    // write puts the snapshot back as it was: a merged snapshot over an
+    // unchanged config would name units that are still enabled.
+    const priorBody = live === undefined ? undefined : fs.readFileSync(live.path, "utf8");
+    atomicWriteFile(backup, text, { mode });
+    atomicWriteFile(snapPath, `${JSON.stringify(snapshot, null, 2)}\n`, { mode });
+    try {
+        atomicWriteFile(configPath, next, { mode });
+    }
+    catch (err) {
+        if (priorBody !== undefined) {
+            try {
+                atomicWriteFile(snapPath, priorBody, { mode });
+            }
+            catch (rollbackErr) {
+                throw new GateDisableError(`cannot write ${requestedPath}: ${err.message}; and the snapshot ${snapPath}, already merged, ` +
+                    `could not be put back (${rollbackErr.message}). Once the config can be written again, ` +
+                    `\`harness gate enable --runtime codex${codexConfigFlag(namedPath)}\` restores what is off.`);
+            }
+        }
+        throw err;
+    }
+    return {
+        mode: "remove",
+        configPath: requestedPath,
+        backupPath: backup,
+        snapshotPath: snapPath,
+        neutralised,
+        retired,
+    };
+}
+//# sourceMappingURL=codex-disable.js.map

package/dist/cli/gate/codex-disable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-disable.js","sourceRoot":"","sources":["../../../src/cli/gate/codex-disable.ts"],"names":[],"mappings":"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"}

package/dist/cli/gate/codex-enable.d.ts

@@ -0,0 +1,41 @@
+import { type CodexRetiredSnapshot, type ForeignCodexSnapshot } from "./codex-snapshot.js";
+export interface CodexGateEnableOptions {
+    configPath?: string;
+    homeDir?: string;
+    /** Restore even when the config was edited since the snapshot. */
+    force?: boolean;
+    now?: Date;
+}
+interface EnableBase {
+    configPath: string;
+    /** Ids of the block's units that are still neutralised after this call. */
+    stillDisabled: string[];
+    /** Live snapshots beside the config that were taken for another config
+     * (another file, or the same file under a name harness cannot prove is its own). */
+    skippedForeign: ForeignCodexSnapshot[];
+}
+interface SnapshotBase extends EnableBase {
+    /** The snapshot this call retired, or null when it stays live. */
+    retired: CodexRetiredSnapshot | null;
+    /** Other live snapshots for this config (an earlier build wrote one per
+     * disable): enable handles one per run, so the caller runs it again. */
+    remaining: string[];
+    /** Ids of units the snapshot names that are gone from the block (deleted
+     * by hand): the snapshot stays live, and enable never reports an all-clear. */
+    missing: string[];
+    /** The snapshot considered, under its retired name once it was retired. */
+    snapshotPath: string;
+}
+export type CodexGateEnableResult = (EnableBase & {
+    mode: "no-snapshots";
+}) | (SnapshotBase & {
+    mode: "already-restored";
+}) | (SnapshotBase & {
+    mode: "restored";
+    backupPath: string;
+    restoredCount: number;
+    /** Ids the snapshot names that were enabled again already: left as they are. */
+    skippedEnabled: string[];
+});
+export declare function codexGateEnable(opts?: CodexGateEnableOptions): CodexGateEnableResult;
+export {};

package/dist/cli/gate/codex-enable.js

@@ -0,0 +1,127 @@
+// `harness gate enable --runtime codex`: puts back the hook units that
+// `gate disable --runtime codex` neutralised, from the live
+// `harness.gate-disable-codex.*.json` snapshot beside the config (another
+// config's snapshot is skipped and named; several live ones for this config
+// are handled newest first by `createdAt`, one per run, the rest in
+// `remaining`). A snapshot that can no longer be applied is retired as
+// `*.restored.json` or `*.superseded.json`; otherwise it is applied, with
+// `--force` needed when the config was edited since and the restore does not
+// rebuild the pre-disable bytes. A backup is written before every rewrite.
+// Why and how: docs/okf/gate-kill-switch.md (Codex section).
+import * as fs from "node:fs";
+import { assertCodexHookEditInvariant, existingFileMode, readCodexManagedHookUnits, } from "../apply/install-codex-config.js";
+import { atomicWriteFile } from "../../io/atomic-write.js";
+import { codexSnapshotExits, latestInstall, planCodexRestore, readLiveCodexSnapshots, resolveCodexConfig, retireCodexSnapshot, spentCodexSnapshot, toGateError, } from "./codex-snapshot.js";
+import { GateEnableError } from "./enable.js";
+import { backupPath, sha256Hex } from "./snapshot.js";
+function readBlock(text, configPath, namedPath) {
+    try {
+        return readCodexManagedHookUnits(text, configPath);
+    }
+    catch (err) {
+        throw toGateError(err, (m) => new GateEnableError(m), namedPath);
+    }
+}
+/** Ids of the block's neutralised units; none when the config has no block. */
+function disabledIds(text, configPath, namedPath) {
+    return readBlock(text, configPath, namedPath)?.units.filter((u) => u.disabled).map((u) => u.id) ?? [];
+}
+export function codexGateEnable(opts = {}) {
+    const { requestedPath, configPath, namedPath } = resolveCodexConfig(opts, (m) => new GateEnableError(m));
+    const { own, foreign: skippedForeign } = readLiveCodexSnapshots(requestedPath, (m) => new GateEnableError(m), namedPath);
+    const live = own[0];
+    let original;
+    try {
+        original = fs.readFileSync(configPath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            if (live === undefined)
+                return { mode: "no-snapshots", configPath: requestedPath, stillDisabled: [], skippedForeign };
+            throw new GateEnableError(`Codex config not found: ${requestedPath}; cannot restore into a missing target. ${codexSnapshotExits(live, namedPath)}`);
+        }
+        throw new GateEnableError(`cannot read ${requestedPath}: ${err.message}`);
+    }
+    if (live === undefined) {
+        return {
+            mode: "no-snapshots",
+            configPath: requestedPath,
+            stillDisabled: disabledIds(original, configPath, namedPath),
+            skippedForeign,
+        };
+    }
+    const { snapshot } = live;
+    const currentSha = sha256Hex(original);
+    const block = readBlock(original, configPath, namedPath);
+    const units = block?.units ?? null;
+    const { retire: spent, missing } = spentCodexSnapshot(snapshot, currentSha, units, latestInstall(requestedPath, configPath), block?.generation ?? null);
+    let retire = spent;
+    let current = original;
+    let backup;
+    let restoredCount = 0;
+    let skipped = [];
+    // Nothing is applied when the snapshot only names units that were deleted from the block: it stays live.
+    if (retire === null && missing.length === 0) {
+        // The restore skips a unit that is back already and never overwrites a
+        // live line. Every check that would also stop --force runs first, so the
+        // edited-since refusal names --force only when --force would write.
+        const plan = planCodexRestore(original, units, configPath, live, namedPath);
+        if (!plan.ok)
+            throw new GateEnableError(plan.reason);
+        const counts = {};
+        for (const unit of plan.restored)
+            counts[unit.event] = (counts[unit.event] ?? 0) + 1;
+        try {
+            assertCodexHookEditInvariant(original, plan.text, configPath, { direction: "restore", counts });
+        }
+        catch (err) {
+            throw toGateError(err, (m) => new GateEnableError(m), namedPath);
+        }
+        // An edited config is restored without --force only when the restore
+        // provably rebuilds the pre-disable bytes (a crashed merge, a unit put
+        // back by hand). An unedited one must rebuild them, --force or not.
+        const exact = currentSha === snapshot.configAfterSha256;
+        const proven = sha256Hex(plan.text) === snapshot.configBeforeSha256;
+        if (exact && !proven) {
+            throw new GateEnableError(`the snapshot ${live.path} does not rebuild the config it was taken from (the restored text does not ` +
+                `match its recorded pre-disable sha); refusing to write. The config is untouched. ${codexSnapshotExits(live, namedPath)}`);
+        }
+        if (!exact && !proven && !opts.force) {
+            throw new GateEnableError(`the Codex config has been edited since the snapshot was taken (${live.path}; current sha ` +
+                `${currentSha.slice(0, 12)}..., snapshot's post-disable sha ${snapshot.configAfterSha256.slice(0, 12)}...). ` +
+                `Inspect the diff against ${snapshot.configBackupPath}. --force restores every unit the snapshot names that is ` +
+                "still neutralised (found by id), leaves a unit that is enabled again as it is, keeps every other edit " +
+                "and retires the snapshot.");
+        }
+        current = plan.text;
+        restoredCount = plan.restored.length;
+        skipped = plan.skipped;
+        retire = { why: "restored" };
+        const mode = existingFileMode(configPath);
+        backup = backupPath(requestedPath, opts.now ?? new Date());
+        atomicWriteFile(backup, original, { mode });
+        atomicWriteFile(configPath, current, { mode });
+    }
+    // Retired only after the config write: a crash in between leaves a
+    // snapshot the file already matches (or whose units are all enabled after
+    // a forced restore), which the next enable retires.
+    let retired = null;
+    if (retire !== null) {
+        const done = backup !== undefined ? `restored ${restoredCount} hook unit(s) into ${requestedPath}, but ` : "";
+        const to = retireCodexSnapshot(live.path, retire.why, (m) => new GateEnableError(m), done);
+        retired = { from: live.path, to, ...retire };
+    }
+    const base = {
+        configPath: requestedPath,
+        stillDisabled: disabledIds(current, configPath, namedPath),
+        skippedForeign,
+        retired,
+        remaining: own.slice(1).map((l) => l.path),
+        missing,
+        snapshotPath: retired?.to ?? live.path,
+    };
+    if (backup === undefined)
+        return { ...base, mode: "already-restored" };
+    return { ...base, mode: "restored", backupPath: backup, restoredCount, skippedEnabled: skipped };
+}
+//# sourceMappingURL=codex-enable.js.map

package/dist/cli/gate/codex-enable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-enable.js","sourceRoot":"","sources":["../../../src/cli/gate/codex-enable.ts"],"names":[],"mappings":"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"}