@lannguyensi/harness 0.63.0 → 1.0.0

package/dist/cli/pause-check.d.ts

@@ -1,22 +0,0 @@
-import { type LoaderOptions } from "./loader.js";
-export interface CheckPauseOptions {
-    /** Loader options (configPath, homeDir, project). */
-    loaderOpts?: LoaderOptions;
-    /** Test-injected generatedDir; bypasses path resolution when supplied. */
-    generatedDir?: string;
-    /** Short label identifying the hook in the stderr notice. */
-    hookLabel: string;
-    /** Where to write the notice. Defaults to process.stderr. */
-    stderr?: NodeJS.WritableStream;
-    /** Override "now" for tests. */
-    now?: Date;
-}
-/**
- * Returns `{ paused: true }` when a non-expired pause sentinel exists at
- * the resolved generatedDir, after emitting a one-line stderr notice.
- * Returns `{ paused: false }` for absent, expired (auto-resumes), or
- * resolution-failure cases.
- */
-export declare function checkPauseFromLoader(opts: CheckPauseOptions): {
-    paused: boolean;
-};

package/dist/cli/pause-check.js

@@ -1,54 +0,0 @@
-// Hook-side wrapper around the pause sentinel. Every PreToolUse /
-// PostToolUse hook — the policy-intercept gate and the pack hooks alike —
-// calls `checkPauseFromLoader` immediately after parsing stdin and BEFORE
-// attempting to load the manifest: a broken install (corrupted YAML,
-// missing file) must still honour an operator pause, since the
-// lockout-recovery flow is the exact scenario where the install is in a
-// degraded state.
-//
-// Lives at the `cli/` root rather than under `cli/pack/` because it is a
-// cross-layer helper, consumed by `cli/policy/intercept.ts` as well as the
-// pack hooks. Keeping it out of `src/runtime/pause-sentinel.ts` preserves
-// the runtime tree's no-loader rule: runtime/ already imports io/, but
-// pulling in cli/loader.ts would transitively drag YAML parsing into
-// every consumer.
-import { resolveGeneratedDir } from "../io/generated-dir.js";
-import { maybeAnnouncePause } from "../runtime/pause-sentinel.js";
-import { resolvePaths } from "./loader.js";
-/**
- * Returns `{ paused: true }` when a non-expired pause sentinel exists at
- * the resolved generatedDir, after emitting a one-line stderr notice.
- * Returns `{ paused: false }` for absent, expired (auto-resumes), or
- * resolution-failure cases.
- */
-export function checkPauseFromLoader(opts) {
-    let generatedDir;
-    if (opts.generatedDir !== undefined) {
-        generatedDir = opts.generatedDir;
-    }
-    else {
-        try {
-            const loader = opts.loaderOpts ?? {};
-            generatedDir = resolveGeneratedDir({
-                ...(loader.homeDir !== undefined ? { homeDir: loader.homeDir } : {}),
-                manifestPath: resolvePaths(loader).base,
-            });
-        }
-        catch {
-            // resolvePaths only fails in pathological env states (HOME unset,
-            // unreadable cwd). Degrade silently: a broken path resolver should
-            // never escalate into a hook block.
-            return { paused: false };
-        }
-    }
-    const announceOpts = {
-        generatedDir,
-        hookLabel: opts.hookLabel,
-    };
-    if (opts.stderr !== undefined)
-        announceOpts.stderr = opts.stderr;
-    if (opts.now !== undefined)
-        announceOpts.now = opts.now;
-    return maybeAnnouncePause(announceOpts);
-}
-//# sourceMappingURL=pause-check.js.map

package/dist/cli/pause-check.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"pause-check.js","sourceRoot":"","sources":["../../src/cli/pause-check.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,0EAA0E;AAC1E,0EAA0E;AAC1E,qEAAqE;AACrE,+DAA+D;AAC/D,wEAAwE;AACxE,kBAAkB;AAClB,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,0EAA0E;AAC1E,uEAAuE;AACvE,qEAAqE;AACrE,kBAAkB;AAElB,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAsB,MAAM,aAAa,CAAC;AAe/D;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAuB;IAC1D,IAAI,YAAoB,CAAC;IACzB,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACpC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACnC,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC;YACrC,YAAY,GAAG,mBAAmB,CAAC;gBACjC,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpE,YAAY,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,IAAI;aACxC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,kEAAkE;YAClE,mEAAmE;YACnE,oCAAoC;YACpC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,MAAM,YAAY,GAA6C;QAC7D,YAAY;QACZ,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC;IACF,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,YAAY,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACjE,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;QAAE,YAAY,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACxD,OAAO,kBAAkB,CAAC,YAAY,CAAC,CAAC;AAC1C,CAAC"}

package/dist/cli/policy/intercept.d.ts

@@ -1,233 +0,0 @@
-import { type LedgerEntry } from "../../policies/index.js";
-import { type LedgerClient, type PolicyDecision } from "../../runtime/index.js";
-import type { Manifest, McpServer } from "../../schema/index.js";
-import { type LoaderOptions } from "../loader.js";
-export interface InterceptCliOptions extends LoaderOptions {
-    /** Defaults to process.stdin. */
-    stdin?: NodeJS.ReadableStream;
-    /** Defaults to process.stdout. */
-    stdout?: NodeJS.WritableStream;
-    /** Defaults to process.stderr. */
-    stderr?: NodeJS.WritableStream;
-    /** Override timeout per ledger call. */
-    ledgerTimeoutMs?: number;
-    /** Override "now" for deterministic tests. */
-    now?: Date;
-    /** Idle bound, in ms, for the stdin read (default STDIN_IDLE_TIMEOUT_MS). Tests inject a short value. */
-    stdinIdleTimeoutMs?: number;
-    /** Inject a fake ledger client (tests). */
-    ledger?: LedgerClient;
-    /** Inject the resolved manifest (tests). */
-    manifest?: Manifest;
-    /**
-     * Test-injected generatedDir for the pause-sentinel lookup; bypasses
-     * path resolution when supplied. Mirrors the pack hooks' option.
-     */
-    generatedDir?: string;
-    /**
-     * When true (or `HARNESS_POLICY_VERBOSE` env is truthy), emit a
-     * human-readable diagnostic block to stderr for each non-allow
-     * decision. stdout is unaffected, so Claude Code's deny JSON contract
-     * is preserved. Phase 5 #3 — opt-in only.
-     */
-    verbose?: boolean;
-    /**
-     * Risk Gate seams (Phase 7 #5). Override the ambient inputs the
-     * Context Resolver matches `environments.resolvers[]` signals
-     * against, so a test exercising a `when:` policy stays hermetic.
-     * `env` defaults to `process.env`; the kube seams bypass the
-     * `~/.kube/config` read when either is supplied.
-     */
-    env?: Record<string, string | undefined>;
-    kubeContext?: string;
-    kubeNamespace?: string;
-    /**
-     * Test seam for Codex's sandbox `--command-cwd` process argument.
-     * Production resolves it from `/proc/1/cmdline` when Codex does not
-     * include a cwd/workdir in the hook event payload.
-     */
-    codexCommandCwd?: string;
-    /**
-     * Name of the manifest hook that fired this intercept invocation. Set
-     * by the Codex generator (`generate-codex-config.ts`) as the argv flag
-     * `--hook <name>` so every spawned process self-identifies. Used as a
-     * stderr-line prefix and a tag in the no-match hint; when absent the
-     * existing back-compat behaviour (un-tagged stderr) holds. Codex emits
-     * one `[[hooks.*]]` block per manifest hook so the per-hook tag is
-     * unambiguous; the Claude Code generator dedupes by `(command, timeout)`
-     * within a matcher group, so this flag is NOT injected there (it would
-     * defeat the dedupe and N-multiply audit-writes per tool event).
-     */
-    hookName?: string;
-}
-export interface InterceptCliResult {
-    exitCode: number;
-    decisions: PolicyDecision[];
-    blocked: boolean;
-}
-/**
- * Real grounding-mcp-backed ledger client. Exported for testing: the
- * `record` adapter's failure-surfacing path is exercised against a
- * bogus mcpCommand in tests/runtime/intercept-cli.test.ts.
- *
- * Connection discipline (2026-07-01 review, enforcement-subprocess-latency):
- * ONE lazily-opened grounding-mcp session serves every query and audit
- * record of the intercept invocation this client was constructed for,
- * instead of 2 fresh subprocess spawns per matching policy. On top,
- * `ledger_summary` returns the WHOLE session's entries (per-tag filtering
- * happens client-side in `intercept()`), so the K per-policy queries are
- * textually identical — they collapse into one cached round-trip per
- * sessionId. `runInterceptCli` calls `dispose()` when the intercept
- * completes; a caller constructing this client directly owns that call.
- */
-export declare function realLedgerClient(server: McpServer, opts: InterceptCliOptions): LedgerClient;
-/**
- * Per-call budget of the audit-retry session (task f1aea826, review
- * round 2): a quarter of the ledger timeout with a 250ms floor (a fresh
- * node subprocess must cold-start + initialize within it). Exported as a
- * pure function so the FORMULA itself is pinned by a unit test — the
- * round-1 finding this bounds was precisely that an unbounded retry
- * reused the full budget, and nothing would go red if that regressed.
- */
-export declare function auditRetryTimeoutMs(timeoutMs: number): number;
-/**
- * Recognise a hook `command` string as an invocation of `harness policy
- * intercept`'s subcommand, regardless of how the leading interpreter /
- * binary token is spelled: a bare `harness policy intercept`, a node-path
- * form (`node /abs/path/dist/cli/index.js policy intercept`, e.g. a local
- * dev build), an `npx` form (`npx harness policy intercept`), a leading
- * inline env-var assignment (`FOO=bar harness policy intercept` — the
- * same shape `understanding-before-execution.ts`'s `wrap()` helper
- * prefixes pack-contributed commands with), or a trailing flag
- * (`harness policy intercept --hook <name>`, the tag
- * `generate-codex-config.ts#commandWithHookTag` appends).
- *
- * Every OTHER call site that needs to recognise this subcommand in this
- * codebase today (`generate-settings.ts#hookTimeoutSeconds`,
- * `generate-codex-config.ts#commandWithHookTag`) still compares
- * `command.trim() === "harness policy intercept"` VERBATIM — deliberately
- * left unchanged (task d20a7e0c scope: the hook-timeout projection
- * contract those two own is out of scope). For THEM a missed match only
- * changes a floor/flag on a command harness itself emits byte-for-byte,
- * so the single canonical spelling is enough. This matcher exists for a
- * caller (the validate/doctor hook-budget-vs-ledger-timeout guard, task
- * d20a7e0c) where under-recognition is a false NEGATIVE on a security
- * check against an OPERATOR-authored `manifest.hooks[]` entry, which is
- * under no obligation to spell the command exactly the way harness's own
- * generators do.
- *
- * Deliberately narrow, not a shell parser: matches the two literal words
- * `policy` and `intercept` as adjacent, whitespace-separated tokens,
- * preceded by start-of-string / whitespace / a path separator (so
- * `mypolicy intercept` inside one longer token cannot match) and followed
- * by whitespace, end-of-string, or a semicolon/quote character (`;`, `"`,
- * `'`) immediately abutting the word — the shape a chained shell command
- * (`harness policy intercept; echo done`) or an embedded `sh -c
- * "harness policy intercept"` wrapper produces, where nothing whitespace
- * separates `intercept` from the next token (review 2026-08-09, fix round
- * 1, finding 3). The quote arm accepts more than it strictly should: a
- * quote glued directly onto the word (`intercept'or'`) also matches, even
- * though a shell concatenates that into a different, longer identifier
- * (`interceptor`). This is a deliberate, harmless OVER-flag — at worst a
- * spurious validate/doctor diagnostic on an exotic command, never a missed
- * real hook — accepted because the same quote boundary is load-bearing for
- * the legitimate `sh -c "...intercept"` wrapper above. Still not
- * exhaustive: a trailing `)`, `|`, `&`, or
- * backtick immediately abutting the word (e.g. `$(harness policy
- * intercept)`) is a KNOWN, deliberately-unclosed gap — widening further
- * risks matching inside an unrelated longer token with no whitespace
- * boundary at all, and the shapes above already cover the realistic
- * manifest-authoring patterns this matcher exists for. A false negative
- * here degrades to the pre-existing verbatim behaviour (the hook is
- * simply not classified as ledger-consulting, so the margin check has
- * nothing to say about it) — not a runtime bypass; the dispatch this
- * check advises about is unaffected either way.
- */
-export declare function isPolicyInterceptCommand(command: string): boolean;
-/**
- * Minimum `budget_ms` a blocking, ledger-consulting hook needs to clear
- * the worst-case wall time `realLedgerClient` (below) can spend before it
- * writes its own fail-closed decision — derived from that function's OWN
- * two round-trip shapes, not a measured-then-eyeballed constant. Both
- * halves are pinned against the real client in
- * tests/e2e/policy-intercept.test.ts ("hook-budget-ledger-margin
- * derivation (task d20a7e0c)").
- *
- * SCOPE, stated precisely (review 2026-08-09, fix round 1): this is the
- * worst case on the PURE-TIMEOUT HANG SHAPE — the shape where the
- * `query()` call that degrades does so by tripping `LedgerSession`'s own
- * session-wide `timedOut` latch (src/policies/ledger-client.ts), which is
- * what lets the retry sequence below start from an INSTANT first
- * `record()` attempt. A query() that instead degrades via a NON-timeout
- * path — `ledger_summary` coming back a genuine JSON-RPC error, an
- * unparseable payload, or a payload missing the `entries` shape
- * (`querySummary`'s non-timeout `degraded` branches in
- * src/policies/ledger-client.ts) — never sets that latch, so it falls
- * OUTSIDE this bound. See the KNOWN RESIDUAL paragraph at the end of this
- * comment; do not read this function, or the `checkHookBudgetLedgerMargin`
- * diagnostic it backs, as a blanket worst-case guarantee.
- *
- * `T` = the ledger's own per-call budget (`health.timeout_ms`, defaulted
- * to 5000 exactly like `realLedgerClient` itself). `R` =
- * `auditRetryTimeoutMs(T)`, the audit-retry session's own per-call budget.
- *
- *   1. query() — up to 2×T. `LedgerSession.querySummary`
- *      (src/policies/ledger-client.ts) performs `ensureInitialized()`
- *      (the `initialize` handshake, its own T-bounded wait) and, only
- *      once THAT resolves, the actual `ledger_summary` `tools/call` (a
- *      SEPARATE T-bounded wait). A ledger that is merely SLOW rather than
- *      hard-down (the threat class docs/risk-gate.md and this file's own
- *      `deny-degraded` diagnostics already name, distinct from an
- *      instantly-refusing one) can answer `initialize` just under T and
- *      still time out on the following `ledger_summary` — the case a
- *      naive "1×T" assumption undercounts.
- *
- *   2. the deny-degraded audit retry — up to 3×R. On the pure-timeout
- *      hang shape, the pooled session's `timedOut` latch (tripped by the
- *      query()-side timeout itself) makes the FIRST `record()` attempt on
- *      it instant (see `realLedgerClient`'s own doc comment above). The
- *      ONE reserved retry then opens a FRESH session budgeted at R and
- *      calls `recordPolicyDecisionOnSession` (src/runtime/ledger-
- *      record.ts), which can spend up to three independent R-bounded
- *      round-trips before it can report success or give up: the fresh
- *      session's own `initialize` handshake, the first `ledger_add`
- *      attempt at `type: "policy_decision"`, and — only reached when that
- *      attempt comes back a genuine JSON-RPC error rather than a
- *      transport timeout (an older/incompatible grounding-mcp rejecting
- *      the newer type) — the legacy `type: "fact"` fallback `ledger_add`.
- *
- * query() must complete (or degrade) before any policy decision — and so
- * any record() — is computed (`intercept()`'s per-policy loop in
- * src/runtime/intercept.ts awaits `evaluateOnePolicy`, which calls
- * `ledger.query`, before it calls `ledger.record`), and the retry only
- * starts after the first record() attempt on the pooled session already
- * failed, so the two stages are SEQUENTIAL within one hook invocation:
- * worst case ON THE PURE-TIMEOUT HANG SHAPE = 2T + 3R.
- *
- * KNOWN RESIDUAL (review 2026-08-09, fix round 1): when `query()` instead
- * degrades via one of the NON-timeout branches named in the SCOPE
- * paragraph above, the pooled session's `timedOut` latch is never set, so
- * `record()`'s own first attempt is a REAL round-trip too — up to T for
- * the `type: "policy_decision"` `ledger_add` attempt, plus another up to
- * T for the legacy `type: "fact"` fallback if that attempt is itself
- * rejected non-timeout — BEFORE the 3R retry sequence even starts. Worst
- * case on this "error-then-hang" shape is therefore up to 4T + 3R, not
- * 2T + 3R: 23750ms at the shipped T=5000 default, against this
- * function's 13750ms. This formula is DELIBERATELY NOT raised to
- * 4T + 3R: doing so would fail `checkHookBudgetLedgerMargin` against the
- * shipped, reviewer-confirmed-clean fresh-init budget of 15000ms
- * (src/cli/init/templates.ts, task 7bf47554/#414 — out of scope here) at
- * the same T=5000 default, since 15000 < 23750. The guard this function
- * backs GUARANTEES delivery of the fail-closed verdict on the
- * pure-timeout hang shape, but NOT on this error-then-hang shape.
- * Unlike an earlier draft of this note, this residual is NOT confined to
- * one runtime projection: Claude Code and Codex both convert `budget_ms`
- * into the outer hook-kill seconds via the identical `hookTimeoutSeconds`
- * helper (src/cli/apply/generate-settings.ts, shared by
- * generate-codex-config.ts) since task 7bf47554/#414, so a manifest at
- * the shipped defaults is equally exposed on both — this was checked
- * against both generators' current source, not assumed.
- */
-export declare function requiredHookBudgetMs(ledgerTimeoutMs: number): number;
-export declare function runInterceptCli(opts?: InterceptCliOptions): Promise<InterceptCliResult>;
-export type { LedgerEntry };