verifyhash 0.1.0 → 0.1.2

package/README.md

@@ -12,7 +12,7 @@ no pause, no upgrade path, and it never holds funds. Each content hash can be an
 **Live deployment — Polygon mainnet (chain id 137):**
 [`0x77d8eF881D5aeEda64788968D13f9146fE1A609B`](https://polygonscan.com/address/0x77d8eF881D5aeEda64788968D13f9146fE1A609B)
 (deployed 2026-07-03; ownerless — the deploying key holds no special power over it). Pin this address
-out-of-band; `vh` reads/writes against it with `--registry 0x77d8eF881D5aeEda64788968D13f9146fE1A609B`.
+out-of-band; `vh` reads/writes against it with `--contract 0x77d8eF881D5aeEda64788968D13f9146fE1A609B`.
 
 > **Ready to charge for it?** [`docs/GO-LIVE.md`](docs/GO-LIVE.md) is the decision-ready "first dollar" page (`npm run go-live`): the **self-serve evidence license** is the recommended default; the design-partner **pilot** is the enterprise fallback.
 
@@ -20,13 +20,15 @@ out-of-band; `vh` reads/writes against it with `--registry 0x77d8eF881D5aeEda647
 
 > **Adopt in one line.** Want to *receive* and *check* sealed artifacts without an account or our toolchain?
 > The self-serve on-ramp is [`docs/ADOPT.md`](docs/ADOPT.md): `npx --yes verify-vh demo` for a 5-second
-> proof, or a one-line GitHub Action (`uses: <owner>/<repo>/verifier/action@<ref>`) to gate your CI — and
+> proof, or a one-line GitHub Action
+> (`uses: verifyhash/verifyhash/verifier/action@17696eff5d910b496b8935052ff42ee2e7c6a85a` — pinned to a
+> real commit on `main`; re-pin to a full commit SHA **you** trust) to gate your CI — and
 > the free→paid bridge to issuing **your own** signed, customer-verifiable seals (the paid producer surface).
 
 `verifyhash` ships the `vh` command. You do **not** need to clone the repo to use it.
 
 ```bash
-# from a published package (publishing to npm is a human step — see below):
+# published on npm — https://www.npmjs.com/package/verifyhash
 npm install -g verifyhash      # puts `vh` on your PATH
 # or run it without installing:
 npx verifyhash --help

package/cli/agent-hook.js

@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+"use strict";
+
+// cli/agent-hook.js — `vh-agent-hook` (T-73.4): ZERO-CONFIG SessionEnd transcript sealing for
+// Claude Code, over the shipped FREE `vh agent seal` path.
+//
+// WHAT THIS IS
+//   A Claude Code `SessionEnd` hook. The host writes ONE JSON hook event to stdin
+//   ({ transcript_path, session_id, cwd, ... }); this bin maps the session's transcript JSONL into
+//   the canonical agent-session event schema (the examples/agent-session/map-transcript.js
+//   approach — a tiny mapping between the MAPPING BEGIN/END markers below), seals it UNSIGNED via
+//   the SHIPPED packet builder (cli/agent.js buildPacket/serializePacket — the exact free
+//   `vh agent seal` path over cli/core/agent-session.js; NO re-implemented crypto), and writes
+//     <outDir>/<session_id>.vhagent.json
+//   where <outDir> is $VH_HOOK_OUT (resolved against the event's cwd) or `.vh-sessions/` under the
+//   event's cwd by default. The `vh agent verify` one-liner is printed on stderr. That converts the
+//   agent-evidence lane's ~20-line adoption cost to ~0: install the package, register the hook, done.
+//
+// POSTURE (all load-bearing):
+//   * FREE tier only: UNSIGNED seal — no key, no license, no network, ever.
+//   * The hook's own code is Node-core only (fs/path) + the shipped seal modules; no new dependency.
+//   * DRIFT-TOLERANT mapping: an unknown/extra JSONL line kind, an unknown content-block kind, or a
+//     malformed (e.g. crash-truncated) line is SKIPPED-AND-COUNTED, never fatal — a host upgrade
+//     must not silently kill sealing.
+//   * NAMED exits, and a top-level catch so this bin can NEVER crash the host's session end:
+//       0 OK                    sealed + written
+//       2 BAD_HOOK_EVENT        malformed stdin (not JSON / not an object / bad session_id)
+//       3 TRANSCRIPT_UNREADABLE transcript_path missing from the event, or unreadable/oversized
+//       4 EMPTY_TRANSCRIPT      the transcript exists but yields ZERO mappable events
+//       5 SEAL_FAILED           the shipped core refused the mapped events (named reason relayed)
+//       6 WRITE_FAILED          cannot create <outDir> or write the packet
+//       7 INTERNAL              the top-level catch (a bug — named, never an unhandled throw)
+//     Every failure writes NOTHING (the packet is written last, in one shot).
+//   * Deterministic: the same transcript + session_id re-seals to BYTE-IDENTICAL packet bytes, so a
+//     repeat run for the same session_id deterministically overwrites.
+//
+// TRUST BOUNDARY (pinned VERBATIM here, in docs/AGENT-HOOK.md, and in the test):
+//   The seal proves the log is INTACT since seal, NOT that the agent behaved well. NOT a trusted
+//   timestamp — ts fields are self-asserted. And payloads embed VERBATIM — redact before sharing.
+
+const fs = require("fs");
+const path = require("path");
+
+// The SHIPPED free unsigned seal (cli/agent.js is the `vh agent seal` surface over the pure
+// cli/core/agent-session.js core). Reused VERBATIM — this file contains zero crypto.
+const { buildPacket, serializePacket, MAX_INPUT_BYTES } = require("./agent");
+
+// ---------------------------------------------------------------------------------------------------
+// The NAMED exit contract (this bin's own — documented in docs/AGENT-HOOK.md).
+// ---------------------------------------------------------------------------------------------------
+
+const EXIT = Object.freeze({
+  OK: 0,
+  BAD_HOOK_EVENT: 2,
+  TRANSCRIPT_UNREADABLE: 3,
+  EMPTY_TRANSCRIPT: 4,
+  SEAL_FAILED: 5,
+  WRITE_FAILED: 6,
+  INTERNAL: 7,
+});
+
+// Reverse map for the named stderr prefix (`vh-agent-hook: TRANSCRIPT_UNREADABLE: ...`).
+const EXIT_NAME = Object.freeze(
+  Object.fromEntries(Object.entries(EXIT).map(([name, code]) => [code, name]))
+);
+
+// The PINNED boundary lines — docs/AGENT-HOOK.md and the test carry these VERBATIM (anti-drift:
+// the doc quotes the exact wording the code prints).
+const BOUNDARY_INTACT_LINE =
+  "The seal proves the log is INTACT since seal, NOT that the agent behaved well.";
+const BOUNDARY_TIMESTAMP_LINE = "NOT a trusted timestamp — ts fields are self-asserted.";
+const BOUNDARY_REDACT_LINE =
+  "Payloads embed VERBATIM (prompts, code, tool output): run `vh agent redact` before sharing a packet.";
+
+// Cap on the stdin hook event — a hook event is a few hundred bytes; a runaway stream is hostile.
+const MAX_STDIN_BYTES = 1024 * 1024; // 1 MiB
+
+// Stdin idle timeout: the host pipes the hook event instantly, so if nothing arrives we must fail
+// with a hint rather than hang the host's session end. $VH_HOOK_STDIN_TIMEOUT_MS overrides; 0 disables.
+const DEFAULT_STDIN_TIMEOUT_MS = 60000; // 60s — generous vs the host's own hook-timeout
+
+// The default out directory, under the hook event's cwd (overridable via $VH_HOOK_OUT).
+const DEFAULT_OUT_DIR = ".vh-sessions";
+
+// A packet embeds prompts / code / tool output VERBATIM, so the zero-config default dir SELF-IGNORES:
+// the first seal drops this `.gitignore` (an all-globbing `*`, which git also applies to the file
+// itself) inside it, so a routine `git add -A` / `git commit` — or a public repo — can never silently
+// commit a secret-bearing packet. Best-effort and only for the default dir; a custom VH_HOOK_OUT is
+// the operator's to manage (see docs/AGENT-HOOK.md).
+const OUT_DIR_GITIGNORE =
+  "# Written by vh-agent-hook. These *.vhagent.json packets embed prompts, code, and tool output\n" +
+  "# VERBATIM — do NOT commit them (run `vh agent redact` before sharing). This ignores the whole dir.\n" +
+  "*\n";
+
+// Printed by `--help` / `-h` (and, verbatim-ish, when stdin is an interactive terminal): this is a
+// HOOK, not an interactive command, so an operator testing the install gets guidance, not a hang.
+const USAGE = [
+  "vh-agent-hook — zero-config Claude Code SessionEnd transcript sealing (FREE, unsigned).",
+  "",
+  "This is a Claude Code SessionEnd HOOK, not an interactive command. The host pipes ONE hook-event",
+  "JSON ({ transcript_path, session_id, cwd }) to stdin; this bin seals the transcript into",
+  "  <outDir>/<session_id>.vhagent.json   (outDir = $VH_HOOK_OUT, else .vh-sessions/ under the event cwd)",
+  "and prints the `vh agent verify` one-liner on stderr. See docs/AGENT-HOOK.md for the 3-line install.",
+  "",
+  "Env:",
+  "  VH_HOOK_OUT=<dir>              override the out dir (a relative value resolves against the event cwd)",
+  "  VH_HOOK_STDIN_TIMEOUT_MS=<n>   stdin idle timeout in ms (default 60000; 0 disables)",
+  "",
+  "Testing the install by hand? It waits for a hook event on stdin — pipe one in, e.g.:",
+  "  printf '{\"session_id\":\"s1\",\"transcript_path\":\"./t.jsonl\",\"cwd\":\".\"}' | vh-agent-hook",
+].join("\n");
+
+// session_id becomes a FILENAME component: strict allowlist (Claude Code ids are UUIDs), no leading
+// dot, no path separators — a traversal-shaped id is a BAD_HOOK_EVENT, never a write outside outDir.
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+// ---------------------------------------------------------------------------------------------------
+// MAPPING BEGIN — ONE Claude Code transcript JSONL line -> canonical `vh agent` events.
+// Claude Code shapes (v1.x): message lines are { type: "user"|"assistant", message: { role,
+// content }, timestamp, ... } where content is a string or an array of blocks ({ type: "text" },
+// { type: "tool_use", id, name, input }, { type: "tool_result", tool_use_id, content, is_error? }).
+// Everything else (summary / system / file-history-snapshot / future kinds) is skipped-and-counted.
+// ---------------------------------------------------------------------------------------------------
+function mapLine(line, skipped) {
+  if (!isPlainObject(line) || (line.type !== "user" && line.type !== "assistant") || !isPlainObject(line.message)) {
+    skipped.lines++; // non-message or unknown line kind — tolerated drift, never fatal
+    return [];
+  }
+  const ts = typeof line.timestamp === "string" ? line.timestamp : ""; // self-asserted; may be absent
+  const actor = line.type === "user" ? "user" : "agent:assistant";
+  const textType = line.type === "user" ? "prompt" : "completion";
+  const content = line.message.content;
+  if (typeof content === "string") return [{ ts, actor, type: textType, payload: content }];
+  if (!Array.isArray(content)) {
+    skipped.lines++; // a message whose content shape we do not know — skip the line, count it
+    return [];
+  }
+  const out = [];
+  for (const b of content) {
+    if (isPlainObject(b) && b.type === "text" && typeof b.text === "string") {
+      out.push({ ts, actor, type: textType, payload: b.text });
+    } else if (isPlainObject(b) && b.type === "tool_use" && line.type === "assistant") {
+      out.push({ ts, actor, type: "tool_call",
+        payload: JSON.stringify({ id: b.id, name: b.name, input: b.input === undefined ? null : b.input }) });
+    } else if (isPlainObject(b) && b.type === "tool_result" && line.type === "user") {
+      const id = typeof b.tool_use_id === "string" ? b.tool_use_id : "unknown";
+      const e = { ts, actor: "tool:" + id, type: "tool_result",
+        payload: typeof b.content === "string" ? b.content : JSON.stringify(b.content === undefined ? null : b.content),
+        meta: b.is_error === true ? { tool_use_id: id, is_error: true } : { tool_use_id: id } };
+      out.push(e);
+    } else {
+      skipped.blocks++; // unknown/extra content-block kind (thinking, image, future) — counted
+    }
+  }
+  return out;
+}
+// MAPPING END
+
+/**
+ * Map a whole Claude Code transcript JSONL text into the canonical, seq-contiguous event array.
+ * PURE and TOTAL: a malformed line (e.g. crash-truncated tail) is skipped-and-counted, never a
+ * throw — the hook must survive host drift.
+ *
+ * @param {string} text the raw transcript JSONL.
+ * @returns {{ events: object[], skipped: { lines: number, blocks: number, malformed: number } }}
+ */
+function mapTranscriptText(text) {
+  const skipped = { lines: 0, blocks: 0, malformed: 0 };
+  const events = [];
+  const lines = String(text).split(/\r?\n/);
+  for (const raw of lines) {
+    if (raw.trim() === "") continue;
+    let line;
+    try {
+      line = JSON.parse(raw);
+    } catch (_) {
+      skipped.malformed++; // tolerated: a truncated/garbled line never kills the seal
+      continue;
+    }
+    for (const ev of mapLine(line, skipped)) events.push({ seq: events.length, ...ev });
+  }
+  return { events, skipped };
+}
+
+// ---------------------------------------------------------------------------------------------------
+// I/O plumbing.
+// ---------------------------------------------------------------------------------------------------
+
+/**
+ * Read all of stdin (size-capped, idle-timeout-guarded). Resolves the UTF-8 text; rejects on a
+ * stream error, on exceeding the cap, or if `timeoutMs > 0` and no data arrives within that idle
+ * window — so a misconfigured/never-closing stdin fails with a hint instead of hanging the host.
+ */
+function readStdin(stream, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let timer = null;
+    const clear = () => {
+      if (timer) clearTimeout(timer);
+      timer = null;
+    };
+    const arm = () => {
+      if (!timeoutMs || timeoutMs <= 0) return;
+      clear();
+      timer = setTimeout(() => {
+        reject(
+          new Error(
+            `no hook event on stdin within ${timeoutMs}ms — this bin reads the SessionEnd hook-event ` +
+              "JSON from stdin (run `vh-agent-hook --help`)"
+          )
+        );
+        stream.destroy();
+      }, timeoutMs);
+      if (timer.unref) timer.unref(); // never keep the process alive just for this timer
+    };
+    stream.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > MAX_STDIN_BYTES) {
+        clear();
+        reject(new Error(`stdin exceeds the ${MAX_STDIN_BYTES}-byte hook-event cap`));
+        stream.destroy();
+        return;
+      }
+      chunks.push(chunk);
+      arm(); // idle window resets on every chunk
+    });
+    stream.on("end", () => {
+      clear();
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    stream.on("error", (e) => {
+      clear();
+      reject(e);
+    });
+    arm();
+  });
+}
+
+/** The stdin idle timeout in ms from $VH_HOOK_STDIN_TIMEOUT_MS (default 60000; 0 disables). */
+function stdinTimeoutMs(env) {
+  const raw = env.VH_HOOK_STDIN_TIMEOUT_MS;
+  if (raw === undefined || raw === "") return DEFAULT_STDIN_TIMEOUT_MS;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_STDIN_TIMEOUT_MS;
+}
+
+/**
+ * Best-effort: drop the self-ignoring `.gitignore` into the DEFAULT out dir so a routine `git add -A`
+ * can never commit a secret-bearing packet. Never fails the seal; never clobbers an operator's own
+ * `.gitignore`. Called ONLY after a successful packet write, and only for the default dir.
+ */
+function writeSelfIgnore(outDir, writeErr) {
+  const giPath = path.join(outDir, ".gitignore");
+  try {
+    if (!fs.existsSync(giPath)) fs.writeFileSync(giPath, OUT_DIR_GITIGNORE);
+  } catch (e) {
+    writeErr(
+      `vh-agent-hook: note: could not self-ignore ${giPath} (${e.message}) — add '${DEFAULT_OUT_DIR}/' to .gitignore yourself\n`
+    );
+  }
+}
+
+function fail(writeErr, code, message) {
+  writeErr(`vh-agent-hook: ${EXIT_NAME[code]}: ${message}\n`);
+  return code;
+}
+
+/**
+ * The whole hook, I/O injected for tests. NEVER throws (its own catch backs up the bin-level one).
+ *
+ * @param {object} io { stdinText?, argv?, stdinIsTTY?, env?, writeErr? }
+ * @returns {Promise<number>} a named EXIT code.
+ */
+async function runHook(io = {}) {
+  const writeErr = io.writeErr || ((s) => process.stderr.write(s));
+  try {
+    const env = io.env || process.env;
+    const argv = io.argv || process.argv.slice(2);
+
+    // `--help`/`-h`: this is a HOOK, not an interactive command. Print usage on STDERR (stdout stays
+    // clean, always) and exit OK, so an operator poking at the install gets guidance, not a hang.
+    if (argv.includes("-h") || argv.includes("--help")) {
+      writeErr(USAGE + "\n");
+      return EXIT.OK;
+    }
+
+    // (1) The hook event from stdin — malformed stdin is BAD_HOOK_EVENT, nothing written.
+    let stdinText;
+    if (io.stdinText !== undefined) {
+      stdinText = io.stdinText;
+    } else {
+      // Run by hand in a terminal (stdin is a TTY — no event piped)? Don't hang the operator; tell them.
+      const isTTY = io.stdinIsTTY !== undefined ? io.stdinIsTTY : process.stdin.isTTY;
+      if (isTTY) {
+        return fail(
+          writeErr,
+          EXIT.BAD_HOOK_EVENT,
+          "no hook event on stdin (stdin is a terminal). This is a Claude Code SessionEnd hook; it reads " +
+            "the hook-event JSON from stdin — run `vh-agent-hook --help`."
+        );
+      }
+      try {
+        stdinText = await readStdin(process.stdin, stdinTimeoutMs(env));
+      } catch (e) {
+        return fail(writeErr, EXIT.BAD_HOOK_EVENT, `cannot read the hook event from stdin: ${e.message}`);
+      }
+    }
+    let event;
+    try {
+      event = JSON.parse(stdinText);
+    } catch (e) {
+      return fail(writeErr, EXIT.BAD_HOOK_EVENT, `stdin is not valid hook-event JSON: ${e.message}`);
+    }
+    if (!isPlainObject(event)) {
+      return fail(writeErr, EXIT.BAD_HOOK_EVENT, "the hook event must be a JSON object ({ transcript_path, session_id, cwd })");
+    }
+    const sessionId = event.session_id;
+    if (typeof sessionId !== "string" || !SESSION_ID_RE.test(sessionId)) {
+      return fail(
+        writeErr,
+        EXIT.BAD_HOOK_EVENT,
+        `the hook event needs a filename-safe session_id (letters/digits/._- , no leading dot), got: ${JSON.stringify(sessionId)}`
+      );
+    }
+
+    // (2) The transcript — a missing field, or an unreadable/oversized file, is TRANSCRIPT_UNREADABLE.
+    if (typeof event.transcript_path !== "string" || event.transcript_path.length === 0) {
+      return fail(writeErr, EXIT.TRANSCRIPT_UNREADABLE, "the hook event carries no transcript_path");
+    }
+    const eventCwd = typeof event.cwd === "string" && event.cwd.length > 0 ? event.cwd : process.cwd();
+    const transcriptPath = path.resolve(eventCwd, event.transcript_path);
+    let transcriptText;
+    try {
+      const stat = fs.statSync(transcriptPath);
+      if (stat.size > MAX_INPUT_BYTES) {
+        return fail(
+          writeErr,
+          EXIT.TRANSCRIPT_UNREADABLE,
+          `transcript ${transcriptPath} is OVERSIZED (${stat.size} bytes > the ${MAX_INPUT_BYTES}-byte limit)`
+        );
+      }
+      transcriptText = fs.readFileSync(transcriptPath, "utf8");
+    } catch (e) {
+      return fail(writeErr, EXIT.TRANSCRIPT_UNREADABLE, `cannot read transcript ${transcriptPath}: ${e.message}`);
+    }
+
+    // (3) Map (drift-tolerant: skips are COUNTED, never fatal) — zero events is EMPTY_TRANSCRIPT.
+    const { events, skipped } = mapTranscriptText(transcriptText);
+    const skippedNote = `skipped ${skipped.lines} non-message line(s), ${skipped.blocks} unmapped block(s), ${skipped.malformed} malformed line(s)`;
+    if (events.length === 0) {
+      return fail(
+        writeErr,
+        EXIT.EMPTY_TRANSCRIPT,
+        `transcript ${transcriptPath} yields no mappable events (${skippedNote}) — nothing to seal`
+      );
+    }
+
+    // (4) Seal UNSIGNED over the SHIPPED path (free tier: no key, no license, no network).
+    const built = buildPacket(events);
+    if (!built.ok) {
+      const at = built.index !== undefined ? ` at event seq ${built.index}` : "";
+      return fail(writeErr, EXIT.SEAL_FAILED, `the shipped seal core refused the mapped events: ${built.reason}${at}`);
+    }
+    const artifactStr = serializePacket(built.packet);
+
+    // (5) Write <outDir>/<session_id>.vhagent.json — deterministic bytes, so a repeat run for the
+    //     same session_id overwrites with the identical packet.
+    const usingDefaultOut = !(typeof env.VH_HOOK_OUT === "string" && env.VH_HOOK_OUT.length > 0);
+    const outDir = path.resolve(eventCwd, usingDefaultOut ? DEFAULT_OUT_DIR : env.VH_HOOK_OUT);
+    const outPath = path.join(outDir, `${sessionId}.vhagent.json`);
+    try {
+      fs.mkdirSync(outDir, { recursive: true });
+      fs.writeFileSync(outPath, artifactStr);
+    } catch (e) {
+      return fail(writeErr, EXIT.WRITE_FAILED, `cannot write packet ${outPath}: ${e.message}`);
+    }
+    // Keep the working tree CLEAN: the zero-config default dir self-ignores so a stray `git add -A`
+    // can never commit these VERBATIM-payload packets. Best-effort — a failed self-ignore never fails
+    // a good seal, and a custom VH_HOOK_OUT is the operator's to manage (point it outside the tree).
+    if (usingDefaultOut) writeSelfIgnore(outDir, writeErr);
+
+    // (6) The receipt + the verify one-liner + the pinned boundary, all on stderr (a SessionEnd hook
+    //     should never pollute stdout).
+    writeErr(
+      `vh-agent-hook: sealed ${events.length} event(s) from ${transcriptPath} (${skippedNote}) -> ${outPath}\n`
+    );
+    writeErr(`vh-agent-hook: verify with: vh agent verify ${outPath}\n`);
+    writeErr(`vh-agent-hook: ${BOUNDARY_INTACT_LINE} ${BOUNDARY_TIMESTAMP_LINE} ${BOUNDARY_REDACT_LINE}\n`);
+    return EXIT.OK;
+  } catch (e) {
+    // The named backstop: a bug in this file must never crash the host's session end.
+    return fail(writeErr, EXIT.INTERNAL, `unexpected failure: ${e && e.message ? e.message : String(e)}`);
+  }
+}
+
+if (require.main === module) {
+  // Top-level catch (bin level): whatever happens, exit with a NAMED code — never an unhandled throw.
+  runHook().then(
+    (code) => process.exit(code),
+    (e) => {
+      try {
+        process.stderr.write(`vh-agent-hook: INTERNAL: ${e && e.message ? e.message : String(e)}\n`);
+      } catch (_) {
+        /* stderr gone — still exit named */
+      }
+      process.exit(EXIT.INTERNAL);
+    }
+  );
+}
+
+module.exports = {
+  EXIT,
+  EXIT_NAME,
+  BOUNDARY_INTACT_LINE,
+  BOUNDARY_TIMESTAMP_LINE,
+  BOUNDARY_REDACT_LINE,
+  DEFAULT_OUT_DIR,
+  OUT_DIR_GITIGNORE,
+  MAX_STDIN_BYTES,
+  DEFAULT_STDIN_TIMEOUT_MS,
+  USAGE,
+  stdinTimeoutMs,
+  mapLine,
+  mapTranscriptText,
+  runHook,
+};

package/docs/ADOPT.md

@@ -8,7 +8,7 @@ Pick the row that matches where you are, copy the one line, and run it. The **fr
 |---|---|---|
 | **No Node/terminal at all? Verify in your browser** (the 60-second challenge built in) | open [`verifier/dist/verify-vh-standalone.html`](../verifier/dist/verify-vh-standalone.html) | free |
 | **See it work in 5 seconds** (no clone, no flags, no key) | `npx --yes verify-vh demo` | free |
-| **Gate your CI on tampered/forged seals** (GitHub Actions) | `uses: <owner>/<repo>/verifier/action@<ref>` | free |
+| **Gate your CI on tampered/forged seals** (GitHub Actions) | `uses: verifyhash/verifyhash/verifier/action@17696eff5d910b496b8935052ff42ee2e7c6a85a` | free |
 | **Issue signed, customer-verifiable seals of your own** (the paid producer surface) | `vh evidence seal <dir> --sign --license <f> --vendor 0xYOU` | **paid** |
 
 The on-ramp is **deliberately one direction**: the free rows convince you the verdict is real, then the
@@ -69,7 +69,7 @@ see [`verifier/README.md`](../verifier/README.md).
 
 ---
 
-## 2. Gate your CI in one line — `uses: <owner>/<repo>/verifier/action@<ref>`
+## 2. Gate your CI in one line — the pinned `uses:` gate
 
 Drop this workflow at `.github/workflows/verify-vh.yml` in the repo that **receives** sealed verifyhash
 artifacts. Every push / pull request then fails the build the instant any artifact is tampered, forged, or
@@ -84,14 +84,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: <owner>/<repo>/verifier/action@<ref>
+      - uses: verifyhash/verifyhash/verifier/action@17696eff5d910b496b8935052ff42ee2e7c6a85a
         with:
           vendor: "0xYOUR_PRODUCER_SIGNER_ADDRESS"   # the key that must have signed (omit to check tamper only)
           manifest: "release.manifest"               # OR set `artifacts:` instead
 ```
 
-Replace `<owner>/<repo>` with this repository's slug and `<ref>` with a tag or commit SHA you trust (pin a
-SHA for supply-chain safety). The composite action installs **only** the standalone verifier (`js-sha3`) and
+The `uses:` line is pre-pinned to this repository's real slug (`verifyhash/verifyhash`) and a full 40-hex
+commit SHA reachable from `main`, so it works exactly as pasted. Supply-chain hygiene: **re-pin `@<sha>` to
+a commit SHA you have audited and trust** — keep the full-SHA form (a mutable ref like `@main` can change
+under you). The composite action installs **only** the standalone verifier (`js-sha3`) and
 resolves its bundled `verifier/` tree via `${{ github.action_path }}` at run time — so you do **not** vendor
 `verifier/` into your repo. The action lives at [`verifier/action/`](../verifier/action/action.yml); its full
 input table and exit-code contract are in [`verifier/action/README.md`](../verifier/action/README.md).
@@ -178,6 +180,14 @@ time T") is a separate, human-gated step (see
   **zero** install: email ONE file ([`trustledger/dist/trustledger-standalone.html`](../trustledger/dist/trustledger-standalone.html)),
   the partner double-clicks it, drags their real exports in, and the page makes **no network request** (free tier only).
 
+## Anchor a sealed artifact on-chain — and verify the receipt offline (free)
+
+Both anchoring verbs are free and gate-less: `vh anchor-artifact` writes a sealed artifact's digest into a
+ContributionRegistry deployment (your own RPC, your own key — the only cost is your own gas), and
+`vh verify-anchored` re-proves the receipt fully offline, needing no key at all. Honest boundary up front: a
+receipt from a LOCAL dev chain proves MECHANISM only — what an anchored receipt does and does not prove, the
+worked commands, and the committed fixtures you can verify right now with zero setup live in
+[`ANCHORING.md`](ANCHORING.md) and [`examples/anchoring/`](../examples/anchoring/).
 
 ---
 <sub>© 2026 verifyhash.com · Licensed under Apache-2.0 (SPDX-License-Identifier: Apache-2.0) — see the [LICENSE](https://verifyhash.com/LICENSE) and [NOTICE](https://verifyhash.com/NOTICE) served with this file.</sub>

package/docs/AGENT-HOOK.md

@@ -0,0 +1,111 @@
+# `vh-agent-hook` — zero-config session sealing for Claude Code
+
+`vh-agent-hook` is a [Claude Code `SessionEnd` hook](https://docs.anthropic.com/en/docs/claude-code/hooks):
+when a session ends, the host pipes one JSON hook event (`{ transcript_path, session_id, cwd, ... }`)
+to the hook's stdin, and `vh-agent-hook` maps the session's transcript JSONL into the canonical
+agent-session event schema and seals it — **UNSIGNED, on the FREE tier: no key, no license, no
+network** — into one tamper-evident packet:
+
+```
+<outDir>/<session_id>.vhagent.json
+```
+
+`<outDir>` defaults to **`.vh-sessions/`** under the hook event's `cwd`; set the environment
+variable **`VH_HOOK_OUT`** to choose another directory (a relative value resolves against the
+event's `cwd`). The sealing itself is the shipped free `vh agent seal` path over
+`cli/core/agent-session.js` — the hook re-implements no crypto; it is only the transcript mapper
+plus filesystem plumbing. Anyone can then check the packet offline with `vh agent verify` (or the
+zero-install independent verifier — see [AGENTTRACE.md](AGENTTRACE.md)).
+
+### Your working tree stays clean automatically
+
+A packet embeds your prompts, code, and tool output **verbatim** (see the boundary below), so the
+zero-config default dir is made **self-ignoring**: the first seal drops a `.gitignore` (containing
+`*`) inside `.vh-sessions/`, so a routine `git add -A` / `git commit` — or a public repo, like this
+one — can **never** silently commit a secret-bearing packet, and `git status` stays clean. You don't
+have to add anything to your own `.gitignore`.
+
+Prefer to keep packets out of the repo entirely? Point **`VH_HOOK_OUT` at a directory outside your
+working tree** (e.g. `VH_HOOK_OUT=~/.vh-sessions`). If instead you point `VH_HOOK_OUT` at a path
+**inside** the tree, add that directory to your `.gitignore` yourself — the automatic self-ignore is
+written only for the default `.vh-sessions/`. Packets accumulate one-per-session with no rotation, so
+prune the directory when you no longer need the older sealed sessions.
+
+## The 3-line install
+
+```bash
+npm install -g verifyhash    # 1. installs the `vh` and `vh-agent-hook` bins
+echo '{"hooks":{"SessionEnd":[{"hooks":[{"type":"command","command":"vh-agent-hook"}]}]}}' > .claude/settings.json    # 2. register the hook (merge the "hooks" key if the file already exists)
+vh agent verify .vh-sessions/<session_id>.vhagent.json    # 3. after any session ends: verify the sealed packet
+```
+
+That is the entire integration: every session end now writes one verifiable
+`.vh-sessions/<session_id>.vhagent.json`, and the hook prints the exact `vh agent verify` one-liner
+on stderr each time it seals.
+
+## The honest boundary (pinned — read before you rely on a packet)
+
+- **The seal proves the log is INTACT since seal, NOT that the agent behaved well.** Garbage-in is
+  out of scope: the packet's Merkle head proves the transcript events are unaltered since sealing
+  and any disclosed event is verbatim as recorded — it does not prove the transcript faithfully
+  records what the agent actually did, and it is not a claim the work was correct or safe.
+- **NOT a trusted timestamp — ts fields are self-asserted.** Event `ts` values are carried verbatim
+  from the transcript and are never verified against any clock; "sealed at time T" needs the
+  human-owned signing/timestamp trust root (see [TRUST-BOUNDARIES.md](TRUST-BOUNDARIES.md)).
+- **Payloads embed VERBATIM (prompts, code, tool output): run `vh agent redact` before sharing a
+  packet.** A sealed packet contains your full prompts, file contents, and tool output. Redaction
+  withholds any payload behind its hash commitment WITHOUT changing a single leaf or the root, so
+  the redacted copy still verifies: `vh agent redact <packet> --seq <list> --out <redacted>`.
+
+## What the hook writes, and when it refuses
+
+The packet is written **last, in one shot** — every failure path writes NOTHING. The mapping is
+**drift-tolerant**: unknown/extra transcript line kinds (`summary`, `file-history-snapshot`, future
+kinds), unknown content-block kinds, and malformed (e.g. crash-truncated) lines are
+**skipped-and-counted** on stderr, never fatal. Sealing is **deterministic**: re-running the hook
+for the same `session_id` and transcript overwrites the packet with byte-identical content.
+
+Named exit codes (the hook has a top-level catch, so it can never crash the host's session end):
+
+| exit | name                    | meaning                                                          |
+| ---- | ----------------------- | ---------------------------------------------------------------- |
+| 0    | `OK`                    | sealed and written; verify one-liner printed on stderr           |
+| 2    | `BAD_HOOK_EVENT`        | stdin is not valid hook-event JSON, or `session_id` is missing/not filename-safe |
+| 3    | `TRANSCRIPT_UNREADABLE` | the event carries no `transcript_path`, or the file is missing/unreadable/oversized |
+| 4    | `EMPTY_TRANSCRIPT`      | the transcript yields zero mappable events — nothing to seal     |
+| 5    | `SEAL_FAILED`           | the shipped seal core refused the mapped events (reason relayed) |
+| 6    | `WRITE_FAILED`          | cannot create the out directory or write the packet              |
+| 7    | `INTERNAL`              | the top-level catch — a bug, reported by name, never a crash     |
+
+(Exit `1` is deliberately reserved for a generic Node crash and is never used by the hook.)
+
+### Testing the install by hand
+
+The hook reads its event from **stdin**, so running `vh-agent-hook` in a terminal would otherwise
+just wait. Run **`vh-agent-hook --help`** for usage, or pipe a hook event in yourself:
+
+```bash
+printf '{"session_id":"s1","transcript_path":"./session.jsonl","cwd":"."}' | vh-agent-hook
+```
+
+If stdin is an interactive terminal (no event piped), the hook exits `BAD_HOOK_EVENT` with a hint
+rather than hanging; a never-closing stdin is bounded by an idle timeout
+(**`VH_HOOK_STDIN_TIMEOUT_MS`**, default `60000`; `0` disables).
+
+## What lands in the packet
+
+Claude Code transcript lines map to canonical events the way
+[`examples/agent-session/map-transcript.js`](../examples/agent-session/map-transcript.js) maps
+OpenAI-style exports (see the committed Claude Code fixture
+[`examples/agent-session/transcript.claude-code.jsonl`](../examples/agent-session/transcript.claude-code.jsonl)):
+
+- a `user` message (string content or `text` blocks) → `prompt` events (actor `user`);
+- an `assistant` `text` block → a `completion` event (actor `agent:assistant`);
+- an `assistant` `tool_use` block → a `tool_call` event (payload `{ id, name, input }`);
+- a `user` `tool_result` block → a `tool_result` event (actor `tool:<tool_use_id>`, the
+  `tool_use_id` carried in `meta`);
+- everything else is skipped-and-counted.
+
+The full packet semantics — redaction, single-event proofs, checkpoints, append-only growth, and
+the paid signed-head surface — are documented in [AGENTTRACE.md](AGENTTRACE.md). This hook stays
+entirely on the free tier.