@lannguyensi/harness 0.10.1 → 0.12.0

package/dist/policy-packs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/policy-packs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,GAGf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,eAAe,EACf,SAAS,EACT,YAAY,GAEb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAmD,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/policy-packs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAiC,MAAM,aAAa,CAAC;AAC/E,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,GAGf,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,cAAc,EACd,eAAe,EACf,SAAS,EACT,YAAY,GAEb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAmD,MAAM,aAAa,CAAC"}

package/dist/policy-packs/registry.d.ts

@@ -1,4 +1,5 @@
 import type { PolicyPack } from "../schema/index.js";
+import { type ResolvePackOptions } from "./builtin/understanding-before-execution.js";
 import { type Runtime } from "./runtime.js";
 import type { PackContribution } from "./types.js";
 export declare const KNOWN_BUILTIN_PACKS: readonly ["understanding-before-execution"];
@@ -8,4 +9,4 @@ export interface ResolveBuiltinResult {
     contribution: PackContribution;
     warnings: string[];
 }
-export declare function resolveBuiltin(pack: PolicyPack, runtime?: Runtime): ResolveBuiltinResult | null;
+export declare function resolveBuiltin(pack: PolicyPack, runtime?: Runtime, opts?: ResolvePackOptions): ResolveBuiltinResult | null;

package/dist/policy-packs/registry.js

@@ -9,12 +9,12 @@ export const KNOWN_BUILTIN_PACKS = [UNDERSTANDING_BEFORE_EXECUTION];
 export function isBuiltinPackName(name) {
     return KNOWN_BUILTIN_PACKS.includes(name);
 }
-export function resolveBuiltin(pack, runtime = DEFAULT_RUNTIME) {
+export function resolveBuiltin(pack, runtime = DEFAULT_RUNTIME, opts = {}) {
     if (!isBuiltinPackName(pack.name))
         return null;
     switch (pack.name) {
         case UNDERSTANDING_BEFORE_EXECUTION:
-            return resolveUnderstandingBeforeExecution(pack, runtime);
+            return resolveUnderstandingBeforeExecution(pack, runtime, opts);
     }
 }
 //# sourceMappingURL=registry.js.map

package/dist/policy-packs/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/policy-packs/registry.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,mEAAmE;AAGnE,OAAO,EACL,SAAS,IAAI,8BAA8B,EAC3C,OAAO,IAAI,mCAAmC,GAC/C,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,eAAe,EAAgB,MAAM,cAAc,CAAC;AAG7D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,8BAA8B,CAAU,CAAC;AAG7E,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAQ,mBAAyC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC;AAOD,MAAM,UAAU,cAAc,CAC5B,IAAgB,EAChB,UAAmB,eAAe;IAElC,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,QAAQ,IAAI,CAAC,IAAuB,EAAE,CAAC;QACrC,KAAK,8BAA8B;YACjC,OAAO,mCAAmC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/policy-packs/registry.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,mEAAmE;AAGnE,OAAO,EACL,SAAS,IAAI,8BAA8B,EAC3C,OAAO,IAAI,mCAAmC,GAE/C,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,eAAe,EAAgB,MAAM,cAAc,CAAC;AAG7D,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,8BAA8B,CAAU,CAAC;AAG7E,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAQ,mBAAyC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACnE,CAAC;AAOD,MAAM,UAAU,cAAc,CAC5B,IAAgB,EAChB,UAAmB,eAAe,EAClC,OAA2B,EAAE;IAE7B,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC/C,QAAQ,IAAI,CAAC,IAAuB,EAAE,CAAC;QACrC,KAAK,8BAA8B;YACjC,OAAO,mCAAmC,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACpE,CAAC;AACH,CAAC"}

package/dist/runtime/git-context.d.ts

@@ -0,0 +1,16 @@
+export interface GitRepoContext {
+    /** Basename of the work-tree root, or "" when `cwd` is not in a repo. */
+    repo: string;
+    /**
+     * Current branch name, or "" when not in a repo or HEAD is detached
+     * (a raw SHA — there is no branch to name).
+     */
+    branch: string;
+}
+/**
+ * Resolve `{ repo, branch }` for a working directory. Returns empty
+ * strings (never throws) when `cwd` is not inside a git work tree, or
+ * when any individual lookup fails — callers treat "" as "unknown" and
+ * fall through to their own behaviour.
+ */
+export declare function resolveGitContext(cwd: string): GitRepoContext;

package/dist/runtime/git-context.js

@@ -0,0 +1,97 @@
+// Resolves the `REPO` and `BRANCH` policy builtins from a working
+// directory.
+//
+// The intercept engine exposes `${REPO}` / `${BRANCH}` as `ledger_tag`
+// template builtins, but they were only ever populated from the
+// `HARNESS_REPO` / `HARNESS_BRANCH` env vars — which nothing sets — so
+// every `preflight:${REPO}` tag collapsed to the literal `preflight:`.
+// That silently degraded the founding-incident policies to one global
+// tag: a preflight done in repo A satisfied the gate in repo B.
+//
+// This module derives both values from the filesystem, not a `git`
+// subprocess: the intercept hook runs on every Bash / Edit / Write
+// tool call, so the resolution must stay cheap. A bounded walk up the
+// directory tree to find `.git`, plus one small `HEAD` read, is
+// microseconds and spawns no process.
+//
+// It is a deliberate approximation of `git rev-parse`: it reads the
+// work tree's basename and `.git/HEAD` directly and does NOT consult
+// `GIT_DIR` / `GIT_WORK_TREE` / `core.worktree`. For namespacing a
+// ledger tag, the on-disk layout is the right (and more stable)
+// signal; those exotic overrides are out of scope.
+import * as fs from "node:fs";
+import * as path from "node:path";
+const EMPTY = { repo: "", branch: "" };
+// A `.git` *file* (linked worktree / submodule) points at the real git
+// dir: `gitdir: <path>`.
+const GITDIR_RE = /^gitdir:\s*(.+)$/;
+// `.git/HEAD` on a branch: `ref: refs/heads/<branch>`. A detached HEAD
+// holds a raw SHA instead and matches nothing here.
+const HEAD_REF_RE = /^ref:\s*refs\/heads\/(.+)$/;
+/**
+ * Walk up from `startDir` looking for a `.git` entry. Handles both the
+ * common `.git` directory and the `.git` *file* form used by linked
+ * worktrees and submodules. The walk is bounded so a pathologically
+ * deep cwd cannot spin.
+ */
+function findGitEntry(startDir) {
+    let dir = path.resolve(startDir);
+    for (let depth = 0; depth < 128; depth++) {
+        const dotGit = path.join(dir, ".git");
+        let stat;
+        try {
+            stat = fs.statSync(dotGit);
+        }
+        catch {
+            stat = undefined;
+        }
+        if (stat?.isDirectory()) {
+            return { worktreeRoot: dir, gitDir: dotGit };
+        }
+        if (stat?.isFile()) {
+            let gitDir = "";
+            try {
+                const match = GITDIR_RE.exec(fs.readFileSync(dotGit, "utf8").trim());
+                if (match)
+                    gitDir = path.resolve(dir, match[1].trim());
+            }
+            catch {
+                /* unreadable `.git` file — leave gitDir empty, repo still resolves */
+            }
+            return { worktreeRoot: dir, gitDir };
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null; // hit the filesystem root
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Resolve `{ repo, branch }` for a working directory. Returns empty
+ * strings (never throws) when `cwd` is not inside a git work tree, or
+ * when any individual lookup fails — callers treat "" as "unknown" and
+ * fall through to their own behaviour.
+ */
+export function resolveGitContext(cwd) {
+    if (typeof cwd !== "string" || cwd.length === 0)
+        return EMPTY;
+    const entry = findGitEntry(cwd);
+    if (!entry)
+        return EMPTY;
+    const repo = path.basename(entry.worktreeRoot);
+    let branch = "";
+    if (entry.gitDir) {
+        try {
+            const head = fs.readFileSync(path.join(entry.gitDir, "HEAD"), "utf8").trim();
+            const match = HEAD_REF_RE.exec(head);
+            if (match)
+                branch = match[1].trim();
+        }
+        catch {
+            /* unreadable HEAD — branch stays "" */
+        }
+    }
+    return { repo, branch };
+}
+//# sourceMappingURL=git-context.js.map

package/dist/runtime/git-context.js.map

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

package/dist/runtime/index.d.ts

@@ -1,4 +1,5 @@
 export { intercept, type ClaudeDenyJson, type InterceptOptions, type InterceptResult, type LedgerClient, type PolicyDecision, type PolicyOutcome, type ToolEvent, } from "./intercept.js";
 export { recordPolicyDecision, payloadFromDecision, encodeLedgerContent, decodeLedgerContent, decisionSortKey, type LedgerRecordOptions, type PolicyDecisionPayload, } from "./ledger-record.js";
 export { resolveSessionId } from "./session-id.js";
+export { resolveGitContext, type GitRepoContext } from "./git-context.js";
 export { addLedgerFact, type AddLedgerFactOptions, type AddLedgerFactResult, } from "./ledger-add.js";

package/dist/runtime/index.js

@@ -1,5 +1,6 @@
 export { intercept, } from "./intercept.js";
 export { recordPolicyDecision, payloadFromDecision, encodeLedgerContent, decodeLedgerContent, decisionSortKey, } from "./ledger-record.js";
 export { resolveSessionId } from "./session-id.js";
+export { resolveGitContext } from "./git-context.js";
 export { addLedgerFact, } from "./ledger-add.js";
 //# sourceMappingURL=index.js.map

package/dist/runtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,GAQV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAGhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EACL,aAAa,GAGd,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,GAQV,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAGhB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAuB,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EACL,aAAa,GAGd,MAAM,iBAAiB,CAAC"}

package/dist/runtime/pending-approval.d.ts

@@ -0,0 +1,31 @@
+export declare const GENERATED_DIRNAME = "harness.generated";
+export declare const PENDING_APPROVAL_BASENAME = ".pending-approval";
+/**
+ * Resolve `harness.generated/` the way `harness apply` does: a sibling of
+ * the manifest, unless an explicit `homeDir` override is in play (tests,
+ * non-default home).
+ */
+export declare function resolveGeneratedDir(opts: {
+    homeDir?: string;
+    manifestPath: string;
+}): string;
+export declare function pendingApprovalPath(generatedDir: string): string;
+/**
+ * Producer: stage `sessionId` for a later `harness approve`. `atomicWriteFile`
+ * creates `generatedDir` if missing, so a hand-wired hook with no prior
+ * apply still benefits. Callers treat this as best-effort — a write
+ * failure must never escalate a gate block into a thrown hook error.
+ */
+export declare function writePendingApproval(generatedDir: string, sessionId: string): void;
+/**
+ * Consumer: read the staged session id, or null when the file is absent,
+ * empty, whitespace-only, or unreadable. Trims the trailing newline the
+ * producer writes plus any surrounding whitespace.
+ */
+export declare function readPendingApproval(generatedDir: string): string | null;
+/**
+ * Consumer: drop the staging file once its id has been consumed, so a
+ * later arg-less `harness approve` cannot revive a stale session id.
+ * Best-effort — a missing file counts as success.
+ */
+export declare function clearPendingApproval(generatedDir: string): void;

package/dist/runtime/pending-approval.js

@@ -0,0 +1,80 @@
+// Task 33abc147 — `.pending-approval` session-id staging file.
+//
+// The understanding-gate PreToolUse hook knows the running session's
+// exact `session_id` (it arrives on the hook event's stdin). `harness
+// approve`, run from the operator's `!`-shell, does NOT: $CLAUDE_SESSION_ID
+// is unset in that shell, and guessing the id from the newest project
+// transcript is a heuristic that breaks on subagent / parallel-session
+// transcripts (the approve error message warns about exactly that).
+//
+// So the producer hands the id off instead of making the consumer guess:
+// on every block / ask the gate hook writes the `session_id` to
+// `<generatedDir>/.pending-approval`, and `harness approve` reads it when
+// no `--session` flag and no `$CLAUDE_SESSION_ID` are given. Deterministic,
+// not a guess.
+//
+// `harness apply` only writes its own known files into harness.generated/
+// (it never wipes the directory), so the staging file survives applies.
+// `harness approve` deletes it after a successful resolve so a later
+// arg-less invocation cannot revive a stale session id.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFile } from "../io/atomic-write.js";
+// Mirrors `GENERATED_DIRNAME` in cli/apply/apply.ts — also independently
+// duplicated in cli/pack/remove.ts and cli/diff/since-apply.ts. The
+// constant has no single home yet; consolidating the four copies is a
+// separate cleanup.
+export const GENERATED_DIRNAME = "harness.generated";
+export const PENDING_APPROVAL_BASENAME = ".pending-approval";
+/**
+ * Resolve `harness.generated/` the way `harness apply` does: a sibling of
+ * the manifest, unless an explicit `homeDir` override is in play (tests,
+ * non-default home).
+ */
+export function resolveGeneratedDir(opts) {
+    if (opts.homeDir !== undefined)
+        return path.join(opts.homeDir, GENERATED_DIRNAME);
+    return path.join(path.dirname(opts.manifestPath), GENERATED_DIRNAME);
+}
+export function pendingApprovalPath(generatedDir) {
+    return path.join(generatedDir, PENDING_APPROVAL_BASENAME);
+}
+/**
+ * Producer: stage `sessionId` for a later `harness approve`. `atomicWriteFile`
+ * creates `generatedDir` if missing, so a hand-wired hook with no prior
+ * apply still benefits. Callers treat this as best-effort — a write
+ * failure must never escalate a gate block into a thrown hook error.
+ */
+export function writePendingApproval(generatedDir, sessionId) {
+    atomicWriteFile(pendingApprovalPath(generatedDir), `${sessionId}\n`);
+}
+/**
+ * Consumer: read the staged session id, or null when the file is absent,
+ * empty, whitespace-only, or unreadable. Trims the trailing newline the
+ * producer writes plus any surrounding whitespace.
+ */
+export function readPendingApproval(generatedDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(pendingApprovalPath(generatedDir), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Consumer: drop the staging file once its id has been consumed, so a
+ * later arg-less `harness approve` cannot revive a stale session id.
+ * Best-effort — a missing file counts as success.
+ */
+export function clearPendingApproval(generatedDir) {
+    try {
+        fs.rmSync(pendingApprovalPath(generatedDir));
+    }
+    catch {
+        /* already gone (or never written) — nothing to clean up */
+    }
+}
+//# sourceMappingURL=pending-approval.js.map

package/dist/runtime/pending-approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pending-approval.js","sourceRoot":"","sources":["../../src/runtime/pending-approval.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,EAAE;AACF,qEAAqE;AACrE,sEAAsE;AACtE,4EAA4E;AAC5E,sEAAsE;AACtE,uEAAuE;AACvE,oEAAoE;AACpE,EAAE;AACF,yEAAyE;AACzE,gEAAgE;AAChE,0EAA0E;AAC1E,4EAA4E;AAC5E,eAAe;AACf,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,qEAAqE;AACrE,wDAAwD;AAExD,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,yEAAyE;AACzE,oEAAoE;AACpE,sEAAsE;AACtE,oBAAoB;AACpB,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAErD,MAAM,CAAC,MAAM,yBAAyB,GAAG,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAGnC;IACC,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAClF,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,yBAAyB,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAoB,EAAE,SAAiB;IAC1E,eAAe,CAAC,mBAAmB,CAAC,YAAY,CAAC,EAAE,GAAG,SAAS,IAAI,CAAC,CAAC;AACvE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACtD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,mBAAmB,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAoB;IACvD,IAAI,CAAC;QACH,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,YAAY,CAAC,CAAC,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,2DAA2D;IAC7D,CAAC;AACH,CAAC"}

package/dist/runtime/session-id.d.ts

@@ -1,5 +1,5 @@
 /**
- * Resolve the active grounding session id.
+ * Resolve the active grounding session id (WRITE path).
  *
  * Empty strings are treated as "not provided" — both for the explicit
  * argument and for the env var, since `--session ''` from a forgetful
@@ -8,3 +8,42 @@
  * empty session.
  */
 export declare function resolveSessionId(explicit?: string): string;
+export interface DiscoverSessionOptions {
+    /** Override the Claude Code projects root (tests). */
+    projectsRoot?: string;
+    /** Override `$HOME` used to derive the projects root (tests). */
+    homeDir?: string;
+}
+/**
+ * Discover the current Claude Code session id from the most recently
+ * modified transcript JSONL under `~/.claude/projects/<project>/`.
+ *
+ * Claude Code appends to the active session's transcript live, so the
+ * newest-mtime `<uuid>.jsonl` across all project dirs is the running
+ * session. Returns `null` when the projects root is absent or holds no
+ * transcript files — callers fall through to their own default.
+ */
+export declare function discoverNewestSessionId(opts?: DiscoverSessionOptions): string | null;
+export interface ResolveReadSessionOptions extends DiscoverSessionOptions {
+    /**
+     * Test seam — override the transcript-discovery tier wholesale. The
+     * default scans the real `~/.claude/projects` via
+     * `discoverNewestSessionId`.
+     */
+    discover?: (opts: DiscoverSessionOptions) => string | null;
+}
+/**
+ * Resolve the session id for the READ path (`audit`,
+ * `explain --trace/--last`).
+ *
+ * Precedence:
+ *   1. explicit value (the `--session` flag)
+ *   2. `$CLAUDE_SESSION_ID` env
+ *   3. newest Claude Code transcript (the live session)
+ *   4. literal `"default"`
+ *
+ * The WRITE path keeps `resolveSessionId`: it always has
+ * `event.session_id`, so it never reaches the discovery tier, and a
+ * per-hook-event filesystem scan would be wasteful.
+ */
+export declare function resolveReadSessionId(explicit?: string, opts?: ResolveReadSessionOptions): string;

package/dist/runtime/session-id.js

@@ -9,16 +9,28 @@
 // audit/trace even though the writes had landed correctly under the
 // real UUID.
 //
-// This helper lifts the precedence chain into one place:
-//   1. explicit value (from a `--session` flag or the runtime's
-//      `event.session_id`)
-//   2. `$CLAUDE_SESSION_ID` env (set by the Claude Code harness inside
-//      every session)
-//   3. literal `"default"` — preserves prior behaviour for ad-hoc
-//      invocations outside a Claude Code session.
+// `resolveSessionId` lifts the precedence chain into one place for the
+// WRITE path (`policy intercept`), which always carries a concrete
+// `event.session_id`:
+//   1. explicit value (the runtime's `event.session_id`)
+//   2. `$CLAUDE_SESSION_ID` env
+//   3. literal `"default"`
+//
+// The READ path (`audit`, `explain --trace/--last`) needs more. The
+// Phase 5 #2 fix assumed `$CLAUDE_SESSION_ID` is exported into the
+// session's shell environment — it is not (Claude Code does not put it
+// in the Bash tool env), so tier 2 is inert in practice and the readers
+// still fell through to `"default"`. `resolveReadSessionId` adds a
+// transcript-discovery tier: when no explicit id and no env, it reads
+// the active session id off the newest Claude Code transcript JSONL.
+// That is the programmatic form of the heuristic `harness approve`'s
+// own help text recommends to humans.
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 const FALLBACK = "default";
 /**
- * Resolve the active grounding session id.
+ * Resolve the active grounding session id (WRITE path).
  *
  * Empty strings are treated as "not provided" — both for the explicit
  * argument and for the env var, since `--session ''` from a forgetful
@@ -34,4 +46,83 @@ export function resolveSessionId(explicit) {
         return env;
     return FALLBACK;
 }
+// Claude Code names each session's transcript `<uuid>.jsonl`. Anchored
+// so sibling files (memory dirs, `.pending-approval`, etc.) are ignored.
+const SESSION_TRANSCRIPT_RE = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i;
+/**
+ * Discover the current Claude Code session id from the most recently
+ * modified transcript JSONL under `~/.claude/projects/<project>/`.
+ *
+ * Claude Code appends to the active session's transcript live, so the
+ * newest-mtime `<uuid>.jsonl` across all project dirs is the running
+ * session. Returns `null` when the projects root is absent or holds no
+ * transcript files — callers fall through to their own default.
+ */
+export function discoverNewestSessionId(opts = {}) {
+    const projectsRoot = opts.projectsRoot ??
+        path.join(opts.homeDir ?? os.homedir(), ".claude", "projects");
+    let projectDirs;
+    try {
+        projectDirs = fs.readdirSync(projectsRoot);
+    }
+    catch {
+        return null;
+    }
+    let newest = null;
+    for (const dir of projectDirs) {
+        const projectPath = path.join(projectsRoot, dir);
+        let files;
+        try {
+            files = fs.readdirSync(projectPath);
+        }
+        catch {
+            continue; // not a directory, or unreadable — skip
+        }
+        for (const file of files) {
+            const match = SESSION_TRANSCRIPT_RE.exec(file);
+            if (!match)
+                continue;
+            let mtimeMs;
+            try {
+                mtimeMs = fs.statSync(path.join(projectPath, file)).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (newest === null || mtimeMs > newest.mtimeMs) {
+                newest = { id: match[1], mtimeMs };
+            }
+        }
+    }
+    return newest === null ? null : newest.id;
+}
+/**
+ * Resolve the session id for the READ path (`audit`,
+ * `explain --trace/--last`).
+ *
+ * Precedence:
+ *   1. explicit value (the `--session` flag)
+ *   2. `$CLAUDE_SESSION_ID` env
+ *   3. newest Claude Code transcript (the live session)
+ *   4. literal `"default"`
+ *
+ * The WRITE path keeps `resolveSessionId`: it always has
+ * `event.session_id`, so it never reaches the discovery tier, and a
+ * per-hook-event filesystem scan would be wasteful.
+ */
+export function resolveReadSessionId(explicit, opts = {}) {
+    if (typeof explicit === "string" && explicit.length > 0)
+        return explicit;
+    const env = process.env.CLAUDE_SESSION_ID;
+    if (typeof env === "string" && env.length > 0)
+        return env;
+    const discover = opts.discover ?? discoverNewestSessionId;
+    const discovered = discover({
+        ...(opts.projectsRoot !== undefined && { projectsRoot: opts.projectsRoot }),
+        ...(opts.homeDir !== undefined && { homeDir: opts.homeDir }),
+    });
+    if (typeof discovered === "string" && discovered.length > 0)
+        return discovered;
+    return FALLBACK;
+}
 //# sourceMappingURL=session-id.js.map

package/dist/runtime/session-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-id.js","sourceRoot":"","sources":["../../src/runtime/session-id.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,EAAE;AACF,uEAAuE;AACvE,iEAAiE;AACjE,qEAAqE;AACrE,8DAA8D;AAC9D,wEAAwE;AACxE,iEAAiE;AACjE,oEAAoE;AACpE,aAAa;AACb,EAAE;AACF,yDAAyD;AACzD,gEAAgE;AAChE,2BAA2B;AAC3B,uEAAuE;AACvE,sBAAsB;AACtB,kEAAkE;AAClE,kDAAkD;AAElD,MAAM,QAAQ,GAAG,SAAS,CAAC;AAE3B;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAiB;IAChD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;IAC1C,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,GAAG,CAAC;IAC1D,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"session-id.js","sourceRoot":"","sources":["../../src/runtime/session-id.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lannguyensi/harness",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "description": "Declarative control plane for agent harnesses — one YAML for grounding, tools, memory, and hooks.",
   "license": "MIT",
   "homepage": "https://github.com/LanNguyenSi/harness",