@lannguyensi/harness 0.43.0 → 0.45.0

package/dist/policy-packs/builtin/understanding-before-execution/ledger.d.ts

@@ -0,0 +1,25 @@
+import { type LedgerEntry } from "../../../policies/index.js";
+export declare const APPROVED_LEDGER_TAG_PREFIX = "understanding-approved:";
+/** Build the per-session ledger tag the pack searches for. */
+export declare function approvedLedgerTagFor(sessionId: string): string;
+/**
+ * Phase 6 #6 — substring-pollution defence shared by every PreToolUse
+ * blocker (Claude Code + Codex). Drops policy_decision rows so a
+ * `understanding-approved:<sess>` substring inside an audit row's
+ * JSON-encoded `reason` cannot accidentally satisfy the gate.
+ */
+export declare function isPolicyDecisionRow(e: LedgerEntry): boolean;
+/**
+ * Match a ledger fetch against the per-session approval tag. Kept for
+ * the audit / forensics path only: a ledger entry tagged
+ * `understanding-approved:<sid>` is no longer a sufficient signal to
+ * unblock the gate (agent-tasks/88ca4bb3: the agent has the same MCP
+ * surface and could self-write the row). Use `checkApprovalMarker`
+ * for the gate decision; this helper now serves `harness audit` /
+ * `harness explain --trace` style read paths that surface the
+ * historic ledger trail without granting approval power.
+ */
+export declare function matchLedgerEntries(entries: LedgerEntry[], sessionId: string): {
+    matched: boolean;
+    detail: string;
+};

package/dist/policy-packs/builtin/understanding-before-execution/ledger.js

@@ -0,0 +1,56 @@
+// Ledger audit/forensics helpers, split out of the former monolithic
+// understanding-before-execution-runtime.ts (structural concentration
+// slice 2, agent-tasks 348a4d42). Pure move: see
+// src/policy-packs/builtin/understanding-before-execution/index.ts for
+// the re-exported public surface.
+import { POLICY_DECISION_TYPE } from "../../../io/ledger-record.js";
+import { APPROVAL_MARKER_DIRNAME } from "./markers.js";
+export const APPROVED_LEDGER_TAG_PREFIX = "understanding-approved:";
+/** Build the per-session ledger tag the pack searches for. */
+export function approvedLedgerTagFor(sessionId) {
+    return `${APPROVED_LEDGER_TAG_PREFIX}${sessionId}`;
+}
+/**
+ * Phase 6 #6 — substring-pollution defence shared by every PreToolUse
+ * blocker (Claude Code + Codex). Drops policy_decision rows so a
+ * `understanding-approved:<sess>` substring inside an audit row's
+ * JSON-encoded `reason` cannot accidentally satisfy the gate.
+ */
+export function isPolicyDecisionRow(e) {
+    if (e.type === POLICY_DECISION_TYPE)
+        return true;
+    if (typeof e.content === "string" && e.content.startsWith(`${POLICY_DECISION_TYPE}:`)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Match a ledger fetch against the per-session approval tag. Kept for
+ * the audit / forensics path only: a ledger entry tagged
+ * `understanding-approved:<sid>` is no longer a sufficient signal to
+ * unblock the gate (agent-tasks/88ca4bb3: the agent has the same MCP
+ * surface and could self-write the row). Use `checkApprovalMarker`
+ * for the gate decision; this helper now serves `harness audit` /
+ * `harness explain --trace` style read paths that surface the
+ * historic ledger trail without granting approval power.
+ */
+export function matchLedgerEntries(entries, sessionId) {
+    const wanted = approvedLedgerTagFor(sessionId);
+    let scanned = 0;
+    for (const e of entries) {
+        if (isPolicyDecisionRow(e))
+            continue;
+        scanned += 1;
+        if (typeof e.content === "string" && e.content.includes(wanted)) {
+            return {
+                matched: true,
+                detail: `audit: ledger tag ${wanted} present at ${e.createdAt} (no longer satisfies the gate; see harness.generated/${APPROVAL_MARKER_DIRNAME}/${sessionId})`,
+            };
+        }
+    }
+    return {
+        matched: false,
+        detail: `no ledger entry matched ${wanted} (scanned ${scanned} non-policy_decision row(s))`,
+    };
+}
+//# sourceMappingURL=ledger.js.map

package/dist/policy-packs/builtin/understanding-before-execution/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/ledger.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,sEAAsE;AACtE,iDAAiD;AACjD,uEAAuE;AACvE,kCAAkC;AAElC,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,CAAC,MAAM,0BAA0B,GAAG,yBAAyB,CAAC;AAEpE,8DAA8D;AAC9D,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO,GAAG,0BAA0B,GAAG,SAAS,EAAE,CAAC;AACrD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAc;IAChD,IAAI,CAAC,CAAC,IAAI,KAAK,oBAAoB;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,oBAAoB,GAAG,CAAC,EAAE,CAAC;QACtF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAsB,EACtB,SAAiB;IAEjB,MAAM,MAAM,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC/C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,mBAAmB,CAAC,CAAC,CAAC;YAAE,SAAS;QACrC,OAAO,IAAI,CAAC,CAAC;QACb,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAChE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,qBAAqB,MAAM,eAAe,CAAC,CAAC,SAAS,yDAAyD,uBAAuB,IAAI,SAAS,GAAG;aAC9J,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,2BAA2B,MAAM,aAAa,OAAO,8BAA8B;KAC5F,CAAC;AACJ,CAAC"}

package/dist/policy-packs/builtin/understanding-before-execution/lifecycle.d.ts

@@ -0,0 +1,20 @@
+export interface ApprovalLifecycle {
+    /** Tool-name patterns whose successful PostToolUse expires the marker. */
+    expireOnToolMatch: string[];
+    /** Pre-compiled regex patterns matched against `Bash` tool_input.command. */
+    expireOnBashMatch: RegExp[];
+    /** Max marker age in milliseconds. Undefined means no TTL. */
+    maxAgeMs?: number;
+    /** Whether the operator explicitly opted out via `{ mode: "session" }`. */
+    legacyMode: boolean;
+}
+/**
+ * Parse the optional `approval_lifecycle` block from a pack config.
+ * Best-effort: malformed values fall back to the default (no expiry,
+ * legacyMode=false) and write a one-line warning to the supplied
+ * stderr. The PreToolUse / PostToolUse hooks must keep working even
+ * when the operator typed a typo in the YAML.
+ */
+export declare function parseApprovalLifecycle(raw: unknown, stderr?: {
+    write: (s: string) => void;
+} | null): ApprovalLifecycle;

package/dist/policy-packs/builtin/understanding-before-execution/lifecycle.js

@@ -0,0 +1,79 @@
+// `approval_lifecycle` pack-config parsing, split out of the former
+// monolithic understanding-before-execution-runtime.ts (structural
+// concentration slice 2, agent-tasks 348a4d42). Pure move: see
+// src/policy-packs/builtin/understanding-before-execution/index.ts for
+// the re-exported public surface.
+import { InvalidDurationError, parseDurationSeconds } from "../../../policies/index.js";
+const DEFAULT_LIFECYCLE = {
+    expireOnToolMatch: [],
+    expireOnBashMatch: [],
+    legacyMode: false,
+};
+/**
+ * Parse the optional `approval_lifecycle` block from a pack config.
+ * Best-effort: malformed values fall back to the default (no expiry,
+ * legacyMode=false) and write a one-line warning to the supplied
+ * stderr. The PreToolUse / PostToolUse hooks must keep working even
+ * when the operator typed a typo in the YAML.
+ */
+export function parseApprovalLifecycle(raw, stderr) {
+    if (raw === undefined || raw === null)
+        return DEFAULT_LIFECYCLE;
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        stderr?.write(`harness pack hook: config.approval_lifecycle ignored (expected object, got ${typeof raw})\n`);
+        return DEFAULT_LIFECYCLE;
+    }
+    const obj = raw;
+    if (obj["mode"] === "session") {
+        return { expireOnToolMatch: [], expireOnBashMatch: [], legacyMode: true };
+    }
+    const expireOnToolMatch = [];
+    const list = obj["expire_on_tool_match"];
+    if (Array.isArray(list)) {
+        for (const v of list) {
+            if (typeof v === "string" && v.length > 0)
+                expireOnToolMatch.push(v);
+        }
+    }
+    else if (list !== undefined) {
+        stderr?.write(`harness pack hook: config.approval_lifecycle.expire_on_tool_match ignored (expected string[], got ${typeof list})\n`);
+    }
+    const expireOnBashMatch = [];
+    const bashList = obj["expire_on_bash_match"];
+    if (Array.isArray(bashList)) {
+        for (const v of bashList) {
+            if (typeof v !== "string" || v.length === 0)
+                continue;
+            try {
+                expireOnBashMatch.push(new RegExp(v));
+            }
+            catch (err) {
+                stderr?.write(`harness pack hook: config.approval_lifecycle.expire_on_bash_match entry ignored ("${v}"): ${err.message}\n`);
+            }
+        }
+    }
+    else if (bashList !== undefined) {
+        stderr?.write(`harness pack hook: config.approval_lifecycle.expire_on_bash_match ignored (expected string[], got ${typeof bashList})\n`);
+    }
+    let maxAgeMs;
+    const maxAgeRaw = obj["max_age"];
+    if (typeof maxAgeRaw === "string" && maxAgeRaw.length > 0) {
+        try {
+            maxAgeMs = parseDurationSeconds(maxAgeRaw) * 1_000;
+        }
+        catch (err) {
+            const msg = err instanceof InvalidDurationError ? err.message : String(err);
+            stderr?.write(`harness pack hook: config.approval_lifecycle.max_age ignored: ${msg}\n`);
+        }
+    }
+    else if (maxAgeRaw !== undefined) {
+        stderr?.write(`harness pack hook: config.approval_lifecycle.max_age ignored (expected duration string like "4h", got ${typeof maxAgeRaw})\n`);
+    }
+    return {
+        expireOnToolMatch,
+        expireOnBashMatch,
+        ...(maxAgeMs !== undefined && { maxAgeMs }),
+        legacyMode: false,
+    };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/policy-packs/builtin/understanding-before-execution/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/policy-packs/builtin/understanding-before-execution/markers.d.ts

@@ -0,0 +1,103 @@
+export declare const APPROVAL_MARKER_DIRNAME = ".approvals";
+/** Filesystem path of the per-session approval marker. */
+export declare function approvalMarkerPathFor(generatedDir: string, sessionId: string): string;
+export interface ApprovalMarker {
+    approvedAt: string;
+    approvedBy: string;
+    /**
+     * sha256 hex of the persisted-report content this approval is bound to
+     * at sign-time (harness/f9485cc7). Optional on write (defaults to
+     * `null` — a marker with no report to bind, e.g. `harness approve
+     * branch-protection`, or a ledger-only approval); always present
+     * (possibly `null`) on a marker `checkApprovalMarker` returns.
+     */
+    reportContentHash?: string | null;
+}
+/**
+ * Operator-side: write the marker file the gate consults. Atomic so a
+ * crash mid-write cannot leave a half-empty file the gate would accept
+ * as approved. Caller is `harness approve understanding`, which the
+ * operator runs from their un-hooked shell; if the agent could call
+ * this path the gate's value would collapse, so it lives behind the
+ * approve CLI rather than as a generally importable verb.
+ *
+ * The marker is HMAC-signed (harness/f9485cc7) over (sessionId,
+ * approvedAt, approvedBy, reportContentHash) using an operator-side key
+ * lazily generated at `<generatedDir>/.approval-signing.key` — see
+ * `src/runtime/approval-signing.ts` for the key-management contract and
+ * the honest trust model. Mode 0600 on the marker file itself, best-
+ * effort (matches the signing key's own permission convention); this is
+ * defense-in-depth alongside the signature, not a substitute for it.
+ */
+export declare function writeApprovalMarker(generatedDir: string, sessionId: string, marker: ApprovalMarker): string;
+export interface MarkerCheck {
+    matched: boolean;
+    detail: string;
+    marker: ApprovalMarker | null;
+    /**
+     * True when `matched` is false SPECIFICALLY because a readable marker
+     * existed but its `approvedAt` exceeded `opts.maxAgeMs`
+     * (agent-tasks/d8ee60ca) — as opposed to the marker being absent
+     * (never approved, or cleared by a task-completion boundary tool via
+     * `clearApprovalMarker`), corrupted, or the session id malformed.
+     * False whenever `matched` is true. This is the signal task 6e888423's
+     * recovery-git-commit exemption keys off: "this session/task DID have
+     * a real operator approval and it merely aged out" is safe to treat
+     * differently from "this session/task was never approved" or "a task
+     * boundary just cleared it for a new task" — see
+     * src/runtime/recovery-git-commit.ts for the full argument.
+     */
+    expired: boolean;
+    /**
+     * True when a marker FILE existed at the expected path but failed
+     * signature verification (harness/f9485cc7): missing `signature`/`alg`
+     * fields (a legacy pre-signing marker, or a marker planted without the
+     * operator-side key), a mismatched `alg`, or a signature that does not
+     * verify against the current key. Distinct from the marker being
+     * simply absent (`forged: false`, `matched: false`) so a caller can
+     * log/alert on an active forgery attempt instead of the routine
+     * "nobody has approved yet" case. `matched` is always false when
+     * `forged` is true — a forged marker never satisfies the gate,
+     * regardless of `approval_lifecycle.max_age`. A transient I/O read
+     * failure (`forged: false`, `matched: false`) is kept distinct from
+     * both: it is neither "no marker" nor evidence of tampering, just a
+     * marker whose integrity cannot be proven right now.
+     */
+    forged: boolean;
+}
+export interface CheckApprovalMarkerOptions {
+    /**
+     * Max marker age in milliseconds (agent-tasks/d8ee60ca). When set,
+     * a marker whose `approvedAt` is older than `now - maxAgeMs` is
+     * treated as expired and returns `matched:false` with an
+     * "expired" detail. When omitted, the marker has no TTL — the
+     * legacy contract (one approval per session, no expiry).
+     */
+    maxAgeMs?: number;
+    /** Override "now" for deterministic tests. */
+    now?: Date;
+}
+/**
+ * Gate-side: is the per-session marker file present, readable, AND
+ * validly signed? (harness/f9485cc7 — this replaced the earlier
+ * "existence is enough" contract: a marker's mere presence used to
+ * satisfy the gate even with a malformed or corrupted body, on the
+ * theory that Edit/Write/Bash being gated meant only the operator could
+ * ever create the file. That theory holds only as long as no OTHER
+ * write primitive reaches `harness.generated/` — exactly the invariant
+ * this signing scheme no longer has to trust blindly.) A marker with no
+ * `signature`, a wrong `alg`, or a signature that fails to verify is
+ * REJECTED — see `MarkerCheck.forged` — with the SAME `matched: false`
+ * outcome as no marker at all, but a distinct, forgery-specific detail
+ * string so callers can tell the two apart for audit.
+ *
+ * `opts.maxAgeMs` (agent-tasks/d8ee60ca): when set, a validly-signed
+ * marker whose `approvedAt` is older than the cutoff returns
+ * `matched:false` with an "expired" detail so the agent gets the same
+ * "no approval" UX as a never-approved session and must re-approve.
+ * Expiry is only evaluated AFTER signature verification succeeds — an
+ * unsigned/forged marker is rejected outright, never "expired".
+ */
+export declare function checkApprovalMarker(generatedDir: string, sessionId: string, opts?: CheckApprovalMarkerOptions): MarkerCheck;
+/** Clear the per-session marker (used by `harness approve --revoke` and tests). */
+export declare function clearApprovalMarker(generatedDir: string, sessionId: string): void;

package/dist/policy-packs/builtin/understanding-before-execution/markers.js

@@ -0,0 +1,203 @@
+// Session-scoped approval marker file (filesystem source of the
+// two-source approval check), split out of the former monolithic
+// understanding-before-execution-runtime.ts (structural concentration
+// slice 2, agent-tasks 348a4d42). Pure move: see
+// src/policy-packs/builtin/understanding-before-execution/index.ts for
+// the re-exported public surface.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFile } from "../../../io/atomic-write.js";
+import { readRegularFileRejectingSymlink } from "../../../io/read-regular-file.js";
+import { signMarker, verifyMarkerSignature } from "../../../runtime/approval-signing.js";
+import { rejectMalformedSessionId } from "../../../runtime/reject-malformed-session-id.js";
+import { safeJsonParse } from "./persisted-reports.js";
+export const APPROVAL_MARKER_DIRNAME = ".approvals";
+/** Filesystem path of the per-session approval marker. */
+export function approvalMarkerPathFor(generatedDir, sessionId) {
+    rejectMalformedSessionId(sessionId);
+    return path.join(generatedDir, APPROVAL_MARKER_DIRNAME, sessionId);
+}
+/**
+ * Operator-side: write the marker file the gate consults. Atomic so a
+ * crash mid-write cannot leave a half-empty file the gate would accept
+ * as approved. Caller is `harness approve understanding`, which the
+ * operator runs from their un-hooked shell; if the agent could call
+ * this path the gate's value would collapse, so it lives behind the
+ * approve CLI rather than as a generally importable verb.
+ *
+ * The marker is HMAC-signed (harness/f9485cc7) over (sessionId,
+ * approvedAt, approvedBy, reportContentHash) using an operator-side key
+ * lazily generated at `<generatedDir>/.approval-signing.key` — see
+ * `src/runtime/approval-signing.ts` for the key-management contract and
+ * the honest trust model. Mode 0600 on the marker file itself, best-
+ * effort (matches the signing key's own permission convention); this is
+ * defense-in-depth alongside the signature, not a substitute for it.
+ */
+export function writeApprovalMarker(generatedDir, sessionId, marker) {
+    const filePath = approvalMarkerPathFor(generatedDir, sessionId);
+    const signed = signMarker(generatedDir, sessionId, marker);
+    atomicWriteFile(filePath, `${JSON.stringify(signed, null, 2)}\n`, { mode: 0o600 });
+    return filePath;
+}
+/**
+ * Gate-side: is the per-session marker file present, readable, AND
+ * validly signed? (harness/f9485cc7 — this replaced the earlier
+ * "existence is enough" contract: a marker's mere presence used to
+ * satisfy the gate even with a malformed or corrupted body, on the
+ * theory that Edit/Write/Bash being gated meant only the operator could
+ * ever create the file. That theory holds only as long as no OTHER
+ * write primitive reaches `harness.generated/` — exactly the invariant
+ * this signing scheme no longer has to trust blindly.) A marker with no
+ * `signature`, a wrong `alg`, or a signature that fails to verify is
+ * REJECTED — see `MarkerCheck.forged` — with the SAME `matched: false`
+ * outcome as no marker at all, but a distinct, forgery-specific detail
+ * string so callers can tell the two apart for audit.
+ *
+ * `opts.maxAgeMs` (agent-tasks/d8ee60ca): when set, a validly-signed
+ * marker whose `approvedAt` is older than the cutoff returns
+ * `matched:false` with an "expired" detail so the agent gets the same
+ * "no approval" UX as a never-approved session and must re-approve.
+ * Expiry is only evaluated AFTER signature verification succeeds — an
+ * unsigned/forged marker is rejected outright, never "expired".
+ */
+export function checkApprovalMarker(generatedDir, sessionId, opts = {}) {
+    // Construct the path defensively: a malformed sessionId must fail CLOSED
+    // here (no valid marker, so the gate blocks and demands approval), not
+    // throw out of the gate hook, which the top-level handler turns into a
+    // non-blocking exit that would let the gated tool proceed.
+    let filePath;
+    try {
+        filePath = approvalMarkerPathFor(generatedDir, sessionId);
+    }
+    catch (err) {
+        return {
+            matched: false,
+            detail: `invalid sessionId for approval marker: ${err instanceof Error ? err.message : String(err)}`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    // Shared symlink-rejecting read (src/io/read-regular-file.ts): the lstat
+    // reject is defense-in-depth against a planted symlink
+    // (agent-tasks/d39f160e); each failure mode keeps its distinct detail.
+    const read = readRegularFileRejectingSymlink(filePath);
+    if (read.kind === "missing") {
+        return {
+            matched: false,
+            detail: `no approval marker at ${filePath}`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    if (read.kind === "symlink") {
+        return {
+            matched: false,
+            detail: `approval marker is a symlink, refusing for safety: ${filePath}`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    if (read.kind === "not-regular") {
+        return {
+            matched: false,
+            detail: `approval marker path is not a regular file: ${filePath}`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    if (read.kind === "unreadable") {
+        // A genuine I/O error reading an existing regular file (permissions
+        // changed mid-flight, etc.) — not evidence of tampering, but its
+        // signature cannot be proven either, so fail closed. Kept distinct
+        // from `forged` (no claim of an active forgery attempt).
+        return {
+            matched: false,
+            detail: `approval marker at ${filePath} exists but could not be read (I/O error); treating as unapproved since its signature cannot be verified`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    // read.kind === "ok"
+    const parsed = safeJsonParse(read.content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {
+            matched: false,
+            detail: `forged/unsigned marker rejected: marker body at ${filePath} is not a JSON object`,
+            marker: null,
+            expired: false,
+            forged: true,
+        };
+    }
+    const obj = parsed;
+    const verification = verifyMarkerSignature(generatedDir, sessionId, obj);
+    if (!verification.ok) {
+        if (verification.kind === "key-unavailable") {
+            // Fail-closed I/O problem (permission error / disk issue reading or
+            // creating the signing key), NOT evidence of an active forgery
+            // attempt — a marker written by the operator with a perfectly valid
+            // signature would also fail this exact check if the key file became
+            // unreadable. Kept distinct from `forged` (review LOW 1,
+            // harness/f9485cc7) so a broken key file doesn't read as an attack
+            // in audit output, mirroring the `read.kind === "unreadable"` branch
+            // above.
+            return {
+                matched: false,
+                detail: `approval marker at ${filePath} could not be verified: ${verification.reason}; treating as unapproved`,
+                marker: null,
+                expired: false,
+                forged: false,
+            };
+        }
+        return {
+            matched: false,
+            detail: `forged/unsigned marker rejected: ${verification.reason} (${filePath})`,
+            marker: null,
+            expired: false,
+            forged: true,
+        };
+    }
+    const approvedAt = obj["approvedAt"];
+    const approvedBy = obj["approvedBy"];
+    const reportContentHash = typeof obj["reportContentHash"] === "string" ? obj["reportContentHash"] : null;
+    const marker = { approvedAt, approvedBy, reportContentHash };
+    if (opts.maxAgeMs !== undefined) {
+        const approvedAtMs = Date.parse(approvedAt);
+        if (Number.isFinite(approvedAtMs)) {
+            const nowMs = (opts.now ?? new Date()).getTime();
+            const ageMs = nowMs - approvedAtMs;
+            if (ageMs > opts.maxAgeMs) {
+                const ageMin = Math.round(ageMs / 60_000);
+                const maxMin = Math.round(opts.maxAgeMs / 60_000);
+                return {
+                    matched: false,
+                    detail: `approval marker ${path.basename(filePath)} expired: age ${ageMin}m > max ${maxMin}m (approved at ${approvedAt})`,
+                    marker,
+                    expired: true,
+                    forged: false,
+                };
+            }
+        }
+    }
+    return {
+        matched: true,
+        detail: `approved via marker ${path.basename(filePath)}: approved at ${approvedAt} by ${approvedBy}, signature verified`,
+        marker,
+        expired: false,
+        forged: false,
+    };
+}
+/** Clear the per-session marker (used by `harness approve --revoke` and tests). */
+export function clearApprovalMarker(generatedDir, sessionId) {
+    try {
+        fs.rmSync(approvalMarkerPathFor(generatedDir, sessionId));
+    }
+    catch {
+        /* already gone */
+    }
+}
+//# sourceMappingURL=markers.js.map

package/dist/policy-packs/builtin/understanding-before-execution/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/markers.ts"],"names":[],"mappings":"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"}