@lannguyensi/harness 0.44.0 → 0.46.0

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

@@ -0,0 +1,89 @@
+// Active-claim tracking (harness/494fd1e5), 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";
+// Active-claim tracking (harness/494fd1e5). When the agent calls
+// `mcp__agent-tasks__task_start`, a PostToolUse hook writes the claimed
+// task id to a stable file. `harness approve understanding` reads it
+// when --task is absent and auto-supplies it as the task-scoped marker
+// target. This closes the v1 ergonomics gap from PR #184 where the
+// operator had to type the taskId by hand.
+//
+// File contract: a single line containing just the taskId. No JSON,
+// no metadata. Operators can `cat` it to debug. The post-tool-use
+// hook on task_finish / task_abandon removes the file.
+export const ACTIVE_CLAIM_FILENAME = "active-claim";
+export function activeClaimPathFor(generatedDir) {
+    return path.join(generatedDir, ACTIVE_CLAIM_FILENAME);
+}
+function rejectMalformedClaimId(taskId) {
+    if (taskId.length === 0) {
+        throw new Error("taskId is empty");
+    }
+    if (taskId.includes("\n") ||
+        taskId.includes("\r") ||
+        taskId.includes("/") ||
+        taskId.includes("\\") ||
+        taskId.includes("..")) {
+        throw new Error(`taskId contains forbidden characters (newline / path-separator / traversal): ${JSON.stringify(taskId)}`);
+    }
+}
+/**
+ * Hook-side: write the active claim file. Atomic. Called from the
+ * track-active-claim PostToolUse hook on `task_start`. The body is
+ * just the taskId (no JSON) so an operator running
+ * `cat ~/.claude/harness.generated/active-claim` sees the id directly.
+ */
+export function writeActiveClaim(generatedDir, taskId) {
+    rejectMalformedClaimId(taskId);
+    const filePath = activeClaimPathFor(generatedDir);
+    atomicWriteFile(filePath, `${taskId}\n`);
+    return filePath;
+}
+/**
+ * Operator-side: read the active claim file. Returns the taskId or
+ * null when the file is absent / unreadable / empty. `harness approve
+ * understanding` calls this when --task is absent, then passes the
+ * resolved id to writeTaskApprovalMarker.
+ *
+ * Defense-in-depth: if the on-disk content fails the same
+ * path-traversal / newline check that gates writes, the read returns
+ * null instead of surfacing a poisoned id. The write side guards
+ * against a malformed taskId reaching the file in the first place,
+ * but a stale file authored before this guard (or hand-edited)
+ * shouldn't escalate into a forged task-marker write downstream.
+ */
+export function readActiveClaim(generatedDir) {
+    const filePath = activeClaimPathFor(generatedDir);
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    try {
+        rejectMalformedClaimId(trimmed);
+    }
+    catch {
+        return null;
+    }
+    return trimmed;
+}
+/** Hook-side: remove the active claim file. Idempotent. */
+export function clearActiveClaim(generatedDir) {
+    try {
+        fs.rmSync(activeClaimPathFor(generatedDir));
+    }
+    catch {
+        /* already gone */
+    }
+}
+//# sourceMappingURL=active-claim.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"active-claim.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/active-claim.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,mEAAmE;AACnE,+DAA+D;AAC/D,uEAAuE;AACvE,kCAAkC;AAElC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,iEAAiE;AACjE,wEAAwE;AACxE,qEAAqE;AACrE,uEAAuE;AACvE,mEAAmE;AACnE,2CAA2C;AAC3C,EAAE;AACF,oEAAoE;AACpE,kEAAkE;AAClE,uDAAuD;AAEvD,MAAM,CAAC,MAAM,qBAAqB,GAAG,cAAc,CAAC;AAEpD,MAAM,UAAU,kBAAkB,CAAC,YAAoB;IACrD,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,qBAAqB,CAAC,CAAC;AACxD,CAAC;AAED,SAAS,sBAAsB,CAAC,MAAc;IAC5C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;IACrC,CAAC;IACD,IACE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QACrB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QACrB,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QACpB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QACrB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EACrB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,gFAAgF,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CACzG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,YAAoB,EAAE,MAAc;IACnE,sBAAsB,CAAC,MAAM,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAClD,eAAe,CAAC,QAAQ,EAAE,GAAG,MAAM,IAAI,CAAC,CAAC;IACzC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe,CAAC,YAAoB;IAClD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,CAAC;QACH,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,gBAAgB,CAAC,YAAoB;IACnD,IAAI,CAAC;QACH,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,kBAAkB;IACpB,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,13 @@
+export type ApprovalSource = "marker" | "ledger" | "persisted-report" | "none" | "recovery-commit";
+export interface ApprovalCheckResult {
+    approved: boolean;
+    source: ApprovalSource;
+    detail: string;
+}
+export { APPROVED_LEDGER_TAG_PREFIX, approvedLedgerTagFor, isPolicyDecisionRow, matchLedgerEntries, } from "./ledger.js";
+export { APPROVAL_MARKER_DIRNAME, approvalMarkerPathFor, type ApprovalMarker, writeApprovalMarker, type MarkerCheck, type CheckApprovalMarkerOptions, checkApprovalMarker, clearApprovalMarker, } from "./markers.js";
+export { type PersistedReport, REPORTS_DIR_ENV, defaultReportsDir, reportsDirForManifest, listPersistedReports, TOLERANT_FALLBACK_MAX_AGE_MS, TOLERANT_FALLBACK_FUTURE_SKEW_MS, type FindReportOptions, type FindReportSelection, selectReportForSession, findLatestReportForSession, type PersistedReportApprovalCheck, expirePersistedReport, checkPersistedReport, } from "./persisted-reports.js";
+export { type ApprovalLifecycle, parseApprovalLifecycle } from "./lifecycle.js";
+export { APPROVAL_MARKER_TASK_PREFIX, taskApprovalMarkerPathFor, writeTaskApprovalMarker, checkActiveClaimApprovalMarker, type OperatorMarkerApproval, checkOperatorApprovalMarkers, clearTaskApprovalMarker, } from "./task-markers.js";
+export { DEFAULT_BASH_TOOL_NAMES, toolNameMatchesAny, bashCommandMatchesAny, extractBashCommandFromToolInput, extractTaskIdFromToolInput, extractTasksTransitionStatusFromToolInput, type PostToolUseBoundaryMatch, matchPostToolUseBoundary, type ApplyPostToolUseExpiryResult, applyPostToolUseExpiry, describePostToolUseExpiry, } from "./post-tool-use-boundary.js";
+export { ACTIVE_CLAIM_FILENAME, activeClaimPathFor, writeActiveClaim, readActiveClaim, clearActiveClaim, } from "./active-claim.js";

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

@@ -0,0 +1,39 @@
+// Phase 6 #4 — runtime helpers for the understanding-before-execution pack.
+//
+// Two-source approval check that the harness-side PreToolUse blocker
+// consults:
+//
+//   1. Filesystem marker `<generatedDir>/.approvals/<sessionId>` written
+//      by `harness approve understanding` from the operator's shell.
+//      Canonical for harnessed sessions. Replaces the ledger-substring
+//      check that shipped through v0.13.0 (agent-tasks/88ca4bb3): the
+//      agent has direct MCP access to the same ledger that gate path
+//      consulted, so any agent could write `understanding-approved:<sid>`
+//      itself and self-approve. Edit / Write / Bash are all gated by
+//      this same PreToolUse hook, and the configured MCP servers do not
+//      expose filesystem writes, so the marker file is reachable only
+//      from a process the operator launched (their `!`-shell or any
+//      other un-hooked terminal). Operator-side: writeApprovalMarker
+//      below. Forensics: the ledger row is still written by
+//      `harness approve understanding`, for audit only.
+//   2. Persisted JSON report under `.understanding-gate/reports/`
+//      (canonical for solo `@lannguyensi/understanding-gate` users).
+//      The package writes one file per session; the latest with
+//      `approvalStatus: "approved"` matching the session_id wins. The
+//      report is flipped to "approved" by `harness approve`; the
+//      agent's Stop hook only writes `pending` reports and cannot flip
+//      them (Edit/Write/Bash gated), so this source is also operator-
+//      authored.
+//
+// Either source approves. The persisted-report fallback is what makes a
+// solo user without grounding-mcp wired still able to approve via the
+// package's CLI; the marker path is what makes a harnessed session see
+// the approval immediately on the next tool call.
+export { APPROVED_LEDGER_TAG_PREFIX, approvedLedgerTagFor, isPolicyDecisionRow, matchLedgerEntries, } from "./ledger.js";
+export { APPROVAL_MARKER_DIRNAME, approvalMarkerPathFor, writeApprovalMarker, checkApprovalMarker, clearApprovalMarker, } from "./markers.js";
+export { REPORTS_DIR_ENV, defaultReportsDir, reportsDirForManifest, listPersistedReports, TOLERANT_FALLBACK_MAX_AGE_MS, TOLERANT_FALLBACK_FUTURE_SKEW_MS, selectReportForSession, findLatestReportForSession, expirePersistedReport, checkPersistedReport, } from "./persisted-reports.js";
+export { parseApprovalLifecycle } from "./lifecycle.js";
+export { APPROVAL_MARKER_TASK_PREFIX, taskApprovalMarkerPathFor, writeTaskApprovalMarker, checkActiveClaimApprovalMarker, checkOperatorApprovalMarkers, clearTaskApprovalMarker, } from "./task-markers.js";
+export { DEFAULT_BASH_TOOL_NAMES, toolNameMatchesAny, bashCommandMatchesAny, extractBashCommandFromToolInput, extractTaskIdFromToolInput, extractTasksTransitionStatusFromToolInput, matchPostToolUseBoundary, applyPostToolUseExpiry, describePostToolUseExpiry, } from "./post-tool-use-boundary.js";
+export { ACTIVE_CLAIM_FILENAME, activeClaimPathFor, writeActiveClaim, readActiveClaim, clearActiveClaim, } from "./active-claim.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,qEAAqE;AACrE,YAAY;AACZ,EAAE;AACF,yEAAyE;AACzE,qEAAqE;AACrE,uEAAuE;AACvE,sEAAsE;AACtE,qEAAqE;AACrE,0EAA0E;AAC1E,qEAAqE;AACrE,wEAAwE;AACxE,sEAAsE;AACtE,oEAAoE;AACpE,qEAAqE;AACrE,4DAA4D;AAC5D,wDAAwD;AACxD,kEAAkE;AAClE,qEAAqE;AACrE,gEAAgE;AAChE,sEAAsE;AACtE,iEAAiE;AACjE,uEAAuE;AACvE,sEAAsE;AACtE,iBAAiB;AACjB,EAAE;AACF,wEAAwE;AACxE,sEAAsE;AACtE,uEAAuE;AACvE,kDAAkD;AAelD,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EAErB,mBAAmB,EAGnB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAEL,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,4BAA4B,EAC5B,gCAAgC,EAGhC,sBAAsB,EACtB,0BAA0B,EAE1B,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAA0B,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAEhF,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,uBAAuB,EACvB,8BAA8B,EAE9B,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,+BAA+B,EAC/B,0BAA0B,EAC1B,yCAAyC,EAEzC,wBAAwB,EAExB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC"}

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;