@lannguyensi/harness 0.59.1 → 0.60.0

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

@@ -37,7 +37,7 @@
 // harness gate; `harness approve understanding` is the approval path.
 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, selectNewestStrictSessionReport, findLatestReportForSession, expirePersistedReport, checkPersistedReport, } from "./persisted-reports.js";
+export { REPORTS_DIR_ENV, defaultReportsDir, reportsDirForManifest, listPersistedReports, TOLERANT_FALLBACK_MAX_AGE_MS, TOLERANT_FALLBACK_FUTURE_SKEW_MS, selectReportForSession, selectNewestStrictSessionReport, findLatestReportForSession, expirePersistedReport, checkPersistedReport, canonicalReportHash, canonicalReportHashOfFile, MAX_HASHED_REPORT_BYTES, readReportFileBounded, hashReportFile, verifyApprovedReportHash, } from "./persisted-reports.js";
 export { parseApprovalLifecycle } from "./lifecycle.js";
 export { AUTO_APPROVED_BY_PREFIX, CLAUDE_CODE_HARNESS, autoApprovedByFor, parseAutoApprovedBy, autoApprovedLedgerTagFor, parseAutoApprove, permissionModeAllowed, harnessAllowed, AUTO_APPROVE_HARNESS_VALUES, DEFAULT_AUTO_APPROVE_HARNESSES, DEFAULT_REPORT_SCAN_MAX_WAIT_MS, REPORT_SCAN_MAX_WAIT_CEILING_MS, parseReportScanMaxWait, } from "./auto-approve.js";
 // D-004 shipped default (task 8f637efd): the one `auto_approve` snippet
@@ -57,7 +57,7 @@ export { defaultAutoApproveConfig, renderAutoApproveSnippet, } from "./auto-appr
 // missing-`auto_approve` finding (task 8f637efd), see
 // permission-mode-observations.ts's module header.
 export { PERMISSION_MODE_OBSERVATION_DIRNAME, listPermissionModeObservations, permissionModeObservationPathFor, recordPermissionModeObservation, sanitizeForDisplay, } from "./permission-mode-observations.js";
-export { APPROVAL_MARKER_TASK_PREFIX, taskApprovalMarkerPathFor, writeTaskApprovalMarker, checkActiveClaimApprovalMarker, checkSessionApprovalMarker, checkOperatorApprovalMarkers, clearTaskApprovalMarker, } from "./task-markers.js";
+export { APPROVAL_MARKER_TASK_PREFIX, taskApprovalMarkerPathFor, writeTaskApprovalMarker, checkActiveClaimApprovalMarker, checkSessionApprovalMarker, checkOperatorApprovalMarkers, verifyMatchedMarkerReport, 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";
 // Slice 3 of docs/decisions/2026-08-27-ug-auto-mode-approval.md: signed
@@ -77,4 +77,7 @@ export { DELEGATION_MARKER_DIRNAME, ADOPTION_LEDGER_DIRNAME, DELEGATION_REPORT_D
 // the same reason: later consumers (SubagentStart/SubagentStop hooks,
 // the PreToolUse blocker) import every sibling gate symbol through it.
 export { INFLIGHT_RECORD_DIRNAME, DEFAULT_INFLIGHT_STALE_AFTER_MS, rejectMalformedAgentId, inflightMarkerIdFor, inflightRecordPathFor, writeInflightRecord, verifyInflightRecord, clearInflightRecord, listInflightRecords, } from "./inflight-records.js";
+// Wording of the approval-expiry reason in the PreToolUse block message and
+// the event a PostToolUse expiry persists (expiry-reason.ts).
+export { approvalExpiryNotice, describeMarkerTtlExpiry, describePostToolUseTrigger, noApprovalMarkerReason, } from "./expiry-reason.js";
 //# sourceMappingURL=index.js.map

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

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

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

@@ -214,6 +214,7 @@ export function checkApprovalMarker(generatedDir, sessionId, opts = {}) {
             if (ageMs > opts.maxAgeMs) {
                 const ageMin = Math.round(ageMs / 60_000);
                 const maxMin = Math.round(opts.maxAgeMs / 60_000);
+                // KEEP IN SYNC: describeMarkerTtlExpiry (expiry-reason.ts) parses this detail.
                 return {
                     matched: false,
                     detail: `approval marker ${path.basename(filePath)} expired: age ${ageMin}m > max ${maxMin}m (approved at ${approvedAt})`,

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

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

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

@@ -3,6 +3,15 @@ export interface PersistedReport {
     sessionId: string | null;
     approvalStatus: string | null;
     approvedAt: string | null;
+    /**
+     * Event a PostToolUse boundary expired this report for
+     * (`tool:<tool_name>` or `bash:/<regex>/`), stamped by
+     * `expirePersistedReport`; null for a report without the field (older
+     * reports, package producers, or a TTL-only lapse).
+     */
+    expiredBy: string | null;
+    /** ISO timestamp `expirePersistedReport` stamped; null when absent. */
+    expiredAt: string | null;
     /**
      * ISO timestamp the producer stamped when it wrote the report; null
      * for legacy reports without the field.
@@ -165,6 +174,18 @@ export declare function selectNewestStrictSessionReport(reports: PersistedReport
  * only need the report (the gate read and expiry paths).
  */
 export declare function findLatestReportForSession(reports: PersistedReport[], sessionId: string, opts?: FindReportOptions): PersistedReport | null;
+/**
+ * `detail` is not an inert log line: both PreToolUse hooks embed it
+ * verbatim into their block `reason`, and the Codex hook additionally
+ * writes it to stderr, the block-reason surface an operator reads
+ * directly. The report file's basename and its `approvedAt` field both
+ * come from a JSON file whose content the gated agent controls (it is
+ * only unsigned evidence, task 7402301d), so neither is trusted
+ * verbatim here: control characters (including newlines, which could
+ * forge extra `reason:`-looking lines) are replaced with a space and
+ * the result is capped so one field cannot blow out the surface.
+ */
+export declare function sanitizeDetailValue(value: string): string;
 /**
  * What the gate learns from the persisted report: EVIDENCE, never
  * authority (task 7402301d). Until that task the report was the second
@@ -209,7 +230,7 @@ export interface PersistedReportEvidence {
  * best-effort cleanup so a missing report dir or unrelated I/O issue
  * does not escalate into a session-breaking hook failure.
  */
-export declare function expirePersistedReport(reportsDir: string, sessionId: string, now?: Date): {
+export declare function expirePersistedReport(reportsDir: string, sessionId: string, now?: Date, trigger?: string): {
     ok: true;
     filePath: string;
     previousStatus: string | null;
@@ -235,3 +256,186 @@ export declare function expirePersistedReport(reportsDir: string, sessionId: str
  * `understanding-gate approve` CLI, which writes no signed marker).
  */
 export declare function checkPersistedReport(reportsDir: string, sessionId: string): PersistedReportEvidence;
+/**
+ * `approval expired because <event> at <time>` for a report a PostToolUse
+ * boundary expired (`expirePersistedReport` stamps `expiredBy` and
+ * `expiredAt`), `undefined` for any other report, including an older one or
+ * one a package producer wrote that carries no `expiredBy`. Both values come
+ * from a JSON file the gated agent can write, so both pass
+ * `sanitizeDetailValue`.
+ */
+export declare function describeBoundaryExpiry(report: Pick<PersistedReport, "approvalStatus" | "expiredBy" | "expiredAt">): string | undefined;
+/**
+ * Largest report file, in bytes, the canonical hash reads from disk (1 MiB).
+ * Every `*.json` entry of the reports directory reaches the hash through the
+ * gate-read scan, and the agent can write that directory, so without a bound
+ * a planted file of a few hundred megabytes made the hook run out of heap or
+ * past its time budget instead of deciding (a hook that dies or overruns is a
+ * non-blocking error for the runtime). A real report is a few kilobytes, far
+ * below the cap. A file over the cap matches nothing at gate read, and both
+ * producers refuse to approve such a report.
+ */
+export declare const MAX_HASHED_REPORT_BYTES: number;
+/** Result of {@link walkContainerDepth}. */
+export interface ContainerDepthWalk {
+    /** True when some array/object nests deeper than the walk's `max` levels. */
+    tooDeep: boolean;
+    /** Values the walk took off its stack: the root plus every array/object below it. */
+    visited: number;
+}
+/**
+ * Iterative walk over the arrays and objects of `value` (the value itself is
+ * level 1) that stops at the first one nested deeper than `max` levels.
+ * Iterative, so the walk itself cannot overflow the stack. Only arrays and
+ * objects are pushed: a scalar child (string, number, boolean, null) cannot
+ * nest, so a wide array of scalars costs no stack slot per element, and
+ * `visited` counts the root plus the containers below it. Exported for tests.
+ */
+export declare function walkContainerDepth(value: unknown, max: number): ContainerDepthWalk;
+/**
+ * The hash an approval marker signs as its `reportContentHash`, and the one
+ * the gate recomputes at read time (task fa423e9b): sha256 over a key-sorted
+ * JSON serialisation of the parsed report with the lifecycle fields in
+ * `LIFECYCLE_REPORT_FIELDS` removed. A raw-bytes hash cannot do this job: the
+ * producers hash before `rewriteReportApproved` re-serialises the file and
+ * `expirePersistedReport` rewrites it again, so the raw bytes of an untouched
+ * report never match what the marker signed. One function on purpose, shared
+ * by both producers (`harness approve understanding`, the auto-approval path)
+ * and the verifier.
+ *
+ * Total: returns null instead of throwing for a report nested deeper than
+ * `MAX_CANONICAL_REPORT_DEPTH`. The verifier counts such a file as one that
+ * matches nothing; both producers refuse to approve such a report, so no
+ * marker is ever signed without a content binding because of it. Report
+ * files reach it only after {@link readReportFileBounded} bounded their type
+ * and size (the gate-read scan and `harness approve understanding` through
+ * {@link hashReportFile}, the auto-approval path directly).
+ */
+export declare function canonicalReportHash(report: Record<string, unknown>): string | null;
+/** Why {@link readReportFileBounded} returned no content. */
+export type ReportFileReadFailure = "unreadable" | "not-regular" | "too-large" | "grew";
+export type BoundedReportRead = {
+    ok: true;
+    raw: string;
+} | {
+    ok: false;
+    reason: ReportFileReadFailure;
+    detail: string;
+};
+/**
+ * Read a report file for hashing, bounded by type and size. This is the one
+ * read every canonical report hash goes through: the gate-read scan (via
+ * {@link hashReportFile}) and both producers. The path is opened once,
+ * read-only and non-blocking (`O_NONBLOCK`: opening a FIFO with no writer
+ * returns at once instead of waiting for one); its type and size come from
+ * `fstat` on that descriptor, and the content is read through the same
+ * descriptor, so nothing can be swapped in between (no separate stat of the
+ * path, which a symlink flipped to a FIFO used to race). Refused without
+ * reading: anything that is not a regular file, and a file larger than
+ * `MAX_HASHED_REPORT_BYTES`. The read stops one byte past the fstat size
+ * (never more than the cap plus one byte); a file that grows into that byte
+ * while being read is refused too. The descriptor is always closed. Never
+ * throws.
+ */
+export declare function readReportFileBounded(filePath: string): BoundedReportRead;
+/** Why a report file has no canonical hash. */
+export type UnhashableReportReason = ReportFileReadFailure | "not-json-object" | "too-deep";
+export type ReportFileHash = {
+    ok: true;
+    hash: string;
+} | {
+    ok: false;
+    reason: UnhashableReportReason;
+    detail: string;
+};
+/**
+ * Canonical hash of the report file at `filePath`, read through
+ * {@link readReportFileBounded}, or why it has none: not a regular file, over
+ * `MAX_HASHED_REPORT_BYTES`, unreadable, grown while read, not a JSON object,
+ * or nested too deeply. `harness approve understanding` refuses a report on
+ * any of these (the `detail` is its message); the gate-read scan counts such
+ * a file as one that matches nothing. Never throws.
+ */
+export declare function hashReportFile(filePath: string): ReportFileHash;
+/** Canonical hash of the report file at `filePath` ({@link hashReportFile}); null when it has none. */
+export declare function canonicalReportHashOfFile(filePath: string): string | null;
+/** Marker kind whose signed report hash the gate checks. */
+export type ApprovalMarkerKind = "task" | "session";
+/** One matched marker's signed `reportContentHash`, tagged with its kind. */
+export interface MarkerReportBinding {
+    kind: ApprovalMarkerKind;
+    reportContentHash: string | null;
+}
+export type ApprovedReportHashVerification = {
+    ok: true;
+    kind: ApprovalMarkerKind;
+} | {
+    ok: false;
+    detail: string;
+};
+/**
+ * Gate-read cross-check of a matched approval marker against the persisted
+ * reports (task fa423e9b). Both PreToolUse hooks call it after
+ * `checkOperatorApprovalMarkers` matched, through `verifyMatchedMarkerReport`.
+ *
+ * Rule: a marker with a non-null signed `reportContentHash` is valid iff at
+ * least one parseable report file in `reportsDir` (any session, any
+ * `approvalStatus`) has a canonical hash equal to it. The hash already
+ * leaves the lifecycle fields out, so approving, expiring or re-approving
+ * the report never changes it. The signed hash therefore proves one thing:
+ * the content the operator approved is still on disk unmodified. Editing
+ * that file (in place, by swap, by symlink, by an unparseable rewrite)
+ * removes the only match and the marker stops opening the gate. Comparing
+ * against the session's newest approved report instead would deny
+ * legitimate approvals (a newer report approved for the same claim, two
+ * sessions on one claim) and would let a swap pass by moving the swapped
+ * report out of the selection.
+ *
+ * Bounded input: only a regular file of at most `MAX_HASHED_REPORT_BYTES`
+ * (1 MiB) that parses as a JSON object nested at most 64 levels deep has a
+ * canonical hash, read through {@link readReportFileBounded} (opened
+ * non-blocking, typed and sized by `fstat` on the open descriptor, read
+ * through it). Every other `*.json` entry (a FIFO, a directory, a device, a
+ * symlink to one of them, a file over the cap, an unreadable, unparseable or
+ * too deeply nested file) still counts as a report file but matches nothing,
+ * so it can neither open the gate nor make the scan block, run out of
+ * memory or die instead of deciding.
+ *
+ * Residuals: (1) the check proves only that some file carries the approved
+ * content. Any regular `*.json` file within the size cap whose content
+ * equals it keeps a match, whether it was kept before the edit (a copy) or
+ * re-created after it (the agent wrote that content, so it can write it
+ * again), and the marker still opens the gate. (2) A reports directory that
+ * is empty, unreadable or holds no `*.json` entry at all (every report
+ * deleted, the directory made unreadable, the reports renamed) falls back to
+ * the "no report file" allow, the same as before this check existed. The
+ * marker and the operator's approval itself are untouched in both cases;
+ * only the audit trail loses its claim to be the approved content. (3) The
+ * cap bounds each file, not their number: the scan time grows with the
+ * total volume of report files, so an agent that plants hundreds of
+ * megabytes of files just under the cap can still push one scan past the
+ * hook's time budget, which the runtime treats as a non-blocking error (the
+ * same allow as before this check existed).
+ *
+ * Removing the approved report while other report files remain is a deny:
+ * nothing on disk carries the signed content any more. `harness gc --apply`
+ * can do that legitimately: it ages approved reports out by their createdAt
+ * but markers by their file mtime, so a report written long before its
+ * approval can go while the marker stays. Re-approving recovers.
+ *
+ * `primary` is the marker that satisfied the gate (task-scoped first),
+ * `fallback` a session marker that matched behind a task marker. The
+ * fallback is consulted only when the primary fails the check, so a task
+ * marker signed for another report does not hide a session marker that
+ * verifies. Unchanged behaviour: a null hash on the accepted marker (no
+ * report resolved, or `--force` over a report the producer could not hash:
+ * too deeply nested or over the size cap) and a reports directory with no
+ * `*.json` entry at all both allow. A forced approval of a hashable report
+ * signs its hash and is checked like any other.
+ *
+ * The `detail` is the block reason. It names the failing marker kind and the
+ * one-command fix, which is also the single migration step for a marker
+ * written before the canonical hash existed. It carries no report-derived
+ * value, so nothing in it needs sanitising.
+ */
+export declare function verifyApprovedReportHash(reportsDir: string, primary: MarkerReportBinding, fallback?: MarkerReportBinding | null): ApprovedReportHashVerification;