@monte3l/groundwork 1.0.0-rc.2 → 1.0.0-rc.3

package/templates/packs/harness-extras/files/.claude/hooks/reinject-compact-handoff.mjs

@@ -14,9 +14,31 @@
  * `SessionEnd` has no guaranteed abnormal-termination signal, so the fix is
  * on this read side, not a new write-side hook.
  *
+ * Rooted the same way the write hook is: the git toplevel of the payload's
+ * `cwd` (`resolveRoot` + `currentWorktree`), never a bare
+ * `CLAUDE_PROJECT_DIR`, which stays pinned to the session's original checkout
+ * inside a linked worktree. The artifact is session-keyed
+ * (`tmp/compact-handoff-<session_id>.json`): `findHandoffPath` reads this
+ * session's own file first, and only on `resume`/`startup` falls back to the
+ * newest other handoff (keyed or legacy unkeyed) for orphan recovery -- never
+ * on `compact`, where another session's file belongs to a live session. Only
+ * the file actually read is deleted.
+ *
+ * Orphan recovery honours an age window on OTHER sessions' files (by mtime;
+ * the session's own file has no age limit): younger than
+ * `ORPHAN_MIN_AGE_MS` (10 min) is skipped, since it may belong to a live
+ * session about to compact and reinject it itself; older than
+ * `STALE_THRESHOLD_MS` (24h) is skipped and pruned; between the two, the
+ * newest wins. Every candidate, own file included, must parse as a JSON
+ * object -- an empty/corrupt one is deleted and skipped, and one entry that
+ * vanishes or cannot be stat'd mid-scan is skipped rather than aborting the
+ * scan. Only a missing/unreadable `tmp/` itself means "nothing to recover".
+ *
  * A `resume`/`startup` read has no one-compaction freshness guarantee the
  * way a `compact` read does (it may be reading a handoff several sessions
- * old), so `formatHandoff` flags anything older than 24h as likely stale.
+ * old), so `formatHandoff` flags anything older than 24h as likely stale,
+ * and says "git status unavailable at capture time" when the write side
+ * recorded `uncommittedFiles: null` (git failed) rather than `[]` (clean).
  *
  * Advisory-only: always exits 0. A missing or unreadable artifact (first
  * compaction ever, or the write hook failed) means nothing to inject --
@@ -24,14 +46,31 @@
  * line every time the artifact is legitimately absent.
  */
 import process from "node:process";
-import { readFileSync, existsSync, unlinkSync, realpathSync } from "node:fs";
+import {
+  readFileSync,
+  existsSync,
+  unlinkSync,
+  realpathSync,
+  readdirSync,
+  statSync,
+} from "node:fs";
 import { fileURLToPath } from "node:url";
 import { join } from "node:path";
-import { HANDOFF_REL_PATH } from "./write-compact-handoff.mjs";
+import {
+  HANDOFF_GLOB_PREFIX,
+  currentWorktree,
+  handoffRelPath,
+  resolveRoot,
+} from "./write-compact-handoff.mjs";
 
-const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
+/** Age past which a handoff is flagged stale, and another session's is pruned. */
+export const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
 
-const STALE_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+/**
+ * Minimum mtime age before another session's handoff is eligible for orphan
+ * recovery -- a younger one may belong to a live session about to reinject it.
+ */
+export const ORPHAN_MIN_AGE_MS = 10 * 60 * 1000;
 
 /**
  * True when `handoff.capturedAt` parses to a timestamp more than 24h before
@@ -82,7 +121,11 @@ export function formatHandoff(handoff, nowMs = Date.now()) {
   const uncommitted = Array.isArray(handoff.uncommittedFiles)
     ? handoff.uncommittedFiles
     : [];
-  if (uncommitted.length > 0) {
+  if (handoff.uncommittedFiles === null) {
+    lines.push(
+      "  • Uncommitted: unknown -- git status unavailable at capture time",
+    );
+  } else if (uncommitted.length > 0) {
     const shown = uncommitted.slice(0, 10);
     const more = uncommitted.length - shown.length;
     lines.push(
@@ -136,20 +179,108 @@ export function shouldReinject(input) {
 
 /**
  * @param {string} handoffPath absolute path to the handoff artifact
- * @returns {Record<string, any> | null} parsed payload, or null if absent
- *   or unreadable/malformed
+ * @returns {Record<string, any> | null} parsed payload, or null if absent,
+ *   unreadable, malformed, or not a JSON object
  */
 export function readHandoff(handoffPath) {
   if (!existsSync(handoffPath)) return null;
   try {
-    return JSON.parse(readFileSync(handoffPath, "utf8"));
+    const parsed = JSON.parse(readFileSync(handoffPath, "utf8"));
+    return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
     return null;
   }
 }
 
-// Deliberately inlined in every hook rather than shared: this pack's hook
-// budget is exactly its three hooks, so a helper module would cost a slot.
+/** `SessionStart` sources allowed to pick up another session's handoff. */
+const ORPHAN_RECOVERY_SOURCES = new Set(["resume", "startup"]);
+
+const HANDOFF_FILE = new RegExp(`^${HANDOFF_GLOB_PREFIX}.*\\.json$`);
+
+/**
+ * Best-effort delete of a handoff candidate that must not be read again.
+ *
+ * @param {string} path
+ */
+function prune(path) {
+  try {
+    unlinkSync(path);
+  } catch {
+    // Already gone or undeletable -- either way it is skipped, not read.
+  }
+}
+
+/**
+ * True when `path` holds a parseable handoff; an unparseable/empty one is
+ * pruned so it can never shadow a valid candidate on a later scan.
+ *
+ * @param {string} path
+ * @returns {boolean}
+ */
+function isValidCandidate(path) {
+  if (readHandoff(path) !== null) return true;
+  prune(path);
+  return false;
+}
+
+/**
+ * Locate the handoff this session should re-inject.
+ *
+ * @param {string} root git toplevel the handoff lives under
+ * @param {unknown} sessionId the payload's `session_id`
+ * @param {string} source the payload's `source`
+ * @param {number} [nowMs] injectable for testing; defaults to `Date.now()`
+ * @returns {string | null} this session's own file when present and valid
+ *   (any age); else, for `resume`/`startup` only, the newest-by-mtime valid
+ *   other handoff in `tmp/` (keyed or legacy unkeyed) aged between
+ *   `ORPHAN_MIN_AGE_MS` and `STALE_THRESHOLD_MS`; else null. Corrupt
+ *   candidates and stale other-session files are pruned along the way.
+ */
+export function findHandoffPath(root, sessionId, source, nowMs = Date.now()) {
+  const own = join(root, handoffRelPath(sessionId));
+  if (existsSync(own) && isValidCandidate(own)) return own;
+  if (!ORPHAN_RECOVERY_SOURCES.has(source)) return null;
+
+  const tmpDir = join(root, "tmp");
+  let entries;
+  try {
+    entries = readdirSync(tmpDir, { withFileTypes: true });
+  } catch {
+    // Missing/unreadable tmp/ -- nothing to recover.
+    return null;
+  }
+
+  /** @type {Array<{ path: string, mtimeMs: number }>} */
+  const eligible = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !HANDOFF_FILE.test(entry.name)) continue;
+    const candidate = join(tmpDir, entry.name);
+    if (candidate === own) continue;
+    let mtimeMs;
+    try {
+      mtimeMs = statSync(candidate).mtimeMs;
+    } catch {
+      // Vanished or unstat-able mid-scan -- skip this entry, keep scanning.
+      continue;
+    }
+    const ageMs = nowMs - mtimeMs;
+    if (ageMs < ORPHAN_MIN_AGE_MS) continue;
+    if (ageMs > STALE_THRESHOLD_MS) {
+      prune(candidate);
+      continue;
+    }
+    eligible.push({ path: candidate, mtimeMs });
+  }
+
+  eligible.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  for (const { path } of eligible) {
+    if (isValidCandidate(path)) return path;
+  }
+  return null;
+}
+
+// Deliberately inlined in every hook rather than shared, so each hook stays
+// one self-contained file.
 // `import.meta.url` is symlink-resolved but `process.argv[1]` is not, so
 // comparing them directly is false under any symlinked path and the body would
 // never run -- exit 0.
@@ -174,7 +305,9 @@ if (isEntryPoint()) {
 
   if (!shouldReinject(input)) process.exit(0);
 
-  const handoffPath = join(root, HANDOFF_REL_PATH);
+  const root = currentWorktree(resolveRoot(input, process.env, process.cwd()));
+  const handoffPath = findHandoffPath(root, input.session_id, input.source);
+  if (handoffPath === null) process.exit(0);
   const handoff = readHandoff(handoffPath);
   if (handoff === null) process.exit(0);
 
@@ -187,7 +320,8 @@ if (isEntryPoint()) {
   process.stdout.write(JSON.stringify(output));
 
   // One-shot: a stale handoff re-injected after a SECOND compaction would
-  // describe state from before the FIRST, no longer current. Consumed once.
+  // describe state from before the FIRST, no longer current. Consumed once --
+  // and only the file actually read, never another session's.
   try {
     unlinkSync(handoffPath);
   } catch {

package/templates/packs/{statusline → harness-extras}/files/.claude/hooks/statusline.mjs

@@ -2,7 +2,11 @@
 /**
  * statusLine: renders a fixed five-row layout -- session, model, context,
  * quota, work -- built entirely from the JSON Claude Code pipes to stdin
- * (code.claude.com/docs/en/statusline). The five-row guarantee is
+ * (code.claude.com/docs/en/statusline). Each row starts with a "gutter": a
+ * short, dim, fixed-width label (e.g. "session") that lines the rows up
+ * visually. A row with nothing to show renders a "placeholder" (a plain
+ * filler segment) after its gutter instead of going blank, so every row is
+ * always exactly one non-empty line. The five-row guarantee is
  * `renderStatusLine`'s own contract on the success path only: the CLI entry's
  * `catch` (bottom of this file) falls back to a single minimal `ctx --%` line
  * on a JSON-parse failure, by design -- the fallback must never itself risk
@@ -351,7 +355,7 @@ export function formatSessionNameSegment(payload) {
  *   detached; only shown when there is no branch, so a rebase or bisect keeps
  *   its git segment instead of silently losing it.
  * @returns {RowSegment | null} the branch segment. `main` is flagged as a
- *   warning: the baseline's workflow is feature branches and PRs, never work
+ *   warning: this project's workflow is feature branches and PRs, never work
  *   directly on `main`.
  */
 export function formatBranchSegment(branchName, detachedSha = null) {

package/templates/packs/harness-extras/files/.claude/hooks/write-compact-handoff.mjs

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 /**
- * PreCompact: writes a structured handoff artifact to `tmp/compact-handoff.json`
- * before Claude Code compacts the conversation.
+ * PreCompact: writes a structured handoff artifact to
+ * `tmp/compact-handoff-<session_id>.json` before Claude Code compacts the
+ * conversation.
  *
- * Durable artifacts outperform in-place summarization for long-running work:
- * post-compaction state reconstruction shouldn't depend on the summary
- * having retained it. `reinject-compact-handoff.mjs` (`SessionStart`,
- * matcher `compact|resume|startup`) reads this artifact back as
- * `additionalContext`.
+ * "Compaction" is Claude Code's process of shrinking a long conversation down
+ * to a summary once it gets too large for the model's context window, so the
+ * session can keep going. A "durable artifact" here just means a plain file
+ * written to disk: unlike the compaction summary itself, a file on disk
+ * survives intact no matter how well that summary captured the details, so
+ * reconstructing state after a compaction (branch, last commit, uncommitted
+ * files) doesn't depend on the summary having retained it.
+ * `reinject-compact-handoff.mjs` (`SessionStart`, matcher
+ * `compact|resume|startup`) reads this artifact back as `additionalContext`.
  *
  * Deliberately git/fs-only, no network calls (no lookup for a PR number) --
  * a PreCompact hook runs on the hot path of every compaction, so a network
@@ -16,7 +21,10 @@
  *
  * "Pending gates" is deliberately NOT a live re-run of `pnpm verify` (far
  * too slow for a hook) -- it's `git status --porcelain`, a fast, honest
- * proxy for "there is uncommitted work here."
+ * proxy for "there is uncommitted work here." `uncommittedFiles` is `null`
+ * when `git status` itself failed (not a repo, git missing) and `[]` only
+ * for a genuinely clean tree, so the reinject side can say "git status
+ * unavailable" instead of implying a clean worktree it never observed.
  *
  * "Journal paths" is best-effort: a hook has no documented way to address
  * the ephemeral session scratchpad directory a subagent may have journaled
@@ -24,10 +32,33 @@
  * gitignored `tmp/` scratch directory (real, cheap, deterministic), not a
  * claim of session-scratchpad discovery this hook cannot honestly make.
  *
+ * Rooted at the hook payload's `cwd`, not `CLAUDE_PROJECT_DIR`: Claude Code
+ * pins `CLAUDE_PROJECT_DIR` to the session's ORIGINAL checkout and does not
+ * move it into a linked worktree, so trusting it would record (and write
+ * into) the wrong checkout. `resolveRoot` prefers `cwd`, then
+ * `CLAUDE_PROJECT_DIR`, then `process.cwd()`; the file lands at that
+ * directory's git toplevel.
+ *
+ * The file is keyed by the payload's `session_id` (`handoffRelPath`) so
+ * concurrent sessions in one checkout never read or delete each other's
+ * handoff. A missing or path-unsafe id falls back to the legacy unkeyed
+ * `tmp/compact-handoff.json`.
+ *
+ * The write is atomic: the payload goes to `<handoff>.<pid>.partial` first
+ * and is then `renameSync`d over the final name, so a reader never sees a
+ * half-written file and a crash mid-write leaves only a `.partial` sibling
+ * (which the reinject side's `compact-handoff*.json` scan never matches).
+ * If the resolved directory itself no longer exists (a removed worktree), or
+ * is not inside a git repository at all (there is no git state to hand off,
+ * and a non-repo `cwd` may be `$HOME` itself), nothing is created -- only
+ * `tmp/` inside an existing git worktree may be.
+ *
  * Advisory-only: always exits 0. A write failure (e.g. `tmp/` unwritable)
- * is swallowed -- losing a handoff on this one compaction is a hint the
- * next session can't reconstruct as cheaply, not a fatal failure of the
- * turn in progress.
+ * never fails the turn -- losing a handoff on this one compaction is a hint
+ * the next session can't reconstruct as cheaply, not a fatal failure of the
+ * turn in progress -- but it is not silent either: one
+ * `write-compact-handoff: handoff not written (<reason>)` line goes to
+ * stderr.
  */
 import process from "node:process";
 import {
@@ -36,13 +67,53 @@ import {
   readdirSync,
   existsSync,
   realpathSync,
+  renameSync,
+  unlinkSync,
 } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 
-const root = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
-export const HANDOFF_REL_PATH = "tmp/compact-handoff.json";
+/** Filename prefix shared by every keyed and legacy handoff artifact. */
+export const HANDOFF_GLOB_PREFIX = "compact-handoff";
+
+const SAFE_SESSION_ID = /^[A-Za-z0-9_-]{1,128}$/;
+
+/**
+ * Root-relative path of the handoff artifact for one session. Only a
+ * path-safe id (`[A-Za-z0-9_-]`, 1-128 chars) is embedded in the filename --
+ * anything else (missing, non-string, `../x`) maps to the legacy unkeyed
+ * name rather than letting payload text steer the write outside `tmp/`.
+ *
+ * @param {unknown} sessionId the hook payload's `session_id`
+ * @returns {string}
+ */
+export function handoffRelPath(sessionId) {
+  return typeof sessionId === "string" && SAFE_SESSION_ID.test(sessionId)
+    ? `tmp/${HANDOFF_GLOB_PREFIX}-${sessionId}.json`
+    : `tmp/${HANDOFF_GLOB_PREFIX}.json`;
+}
+
+/**
+ * The directory the session is actually running in: the payload's `cwd`,
+ * else `env.CLAUDE_PROJECT_DIR`, else `fallbackCwd` (empty strings skipped).
+ * `input` may be any JSON value -- read defensively.
+ *
+ * @param {unknown} input the parsed hook payload
+ * @param {Record<string, string | undefined>} env
+ * @param {string} fallbackCwd
+ * @returns {string}
+ */
+export function resolveRoot(input, env, fallbackCwd) {
+  const cwd =
+    typeof input === "object" && input !== null
+      ? /** @type {{ cwd?: unknown }} */ (input).cwd
+      : undefined;
+  if (typeof cwd === "string" && cwd !== "") return cwd;
+  const projectDir = env.CLAUDE_PROJECT_DIR;
+  if (typeof projectDir === "string" && projectDir !== "") return projectDir;
+  return fallbackCwd;
+}
 
 /**
  * Trims only trailing whitespace/newlines, never leading -- `git status
@@ -55,12 +126,14 @@ export const HANDOFF_REL_PATH = "tmp/compact-handoff.json";
  * @returns {string | null} trailing-trimmed stdout, or null on any failure
  *   (missing git, not a repo, command error) -- never throws.
  */
-export function runGit(args, cwd = root) {
+export function runGit(args, cwd = process.cwd()) {
   try {
     return execFileSync("git", args, {
       cwd,
       encoding: "utf8",
       timeout: 5000,
+      // A non-repo `cwd` is an expected case, not an error worth printing.
+      stdio: ["ignore", "pipe", "ignore"],
     }).replace(/\s+$/, "");
   } catch {
     return null;
@@ -68,13 +141,38 @@ export function runGit(args, cwd = root) {
 }
 
 /** @returns {string} current branch, "" if unavailable */
-export function currentBranch(cwd = root) {
+export function currentBranch(cwd = process.cwd()) {
   return runGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd) ?? "";
 }
 
-/** @returns {string} repo root of the worktree the hook is running in */
-export function currentWorktree(cwd = root) {
-  return runGit(["rev-parse", "--show-toplevel"], cwd) ?? cwd;
+/**
+ * Toplevel of the (possibly linked) worktree containing `cwd`, or `cwd`
+ * itself outside a repo. Derived from `--show-cdup` against `cwd` so the
+ * caller's own spelling of the path survives (`--show-toplevel` returns the
+ * symlink-resolved path, e.g. `/private/var/...` for `/var/...` on macOS);
+ * `--show-toplevel` is used only when that lexical walk disagrees with git.
+ *
+ * @param {string} [cwd]
+ * @param {string | null} [toplevel] `git rev-parse --show-toplevel` for
+ *   `cwd`, when the caller already ran it (null: not a repo); run here when
+ *   omitted
+ * @returns {string}
+ */
+export function currentWorktree(
+  cwd = process.cwd(),
+  toplevel = runGit(["rev-parse", "--show-toplevel"], cwd),
+) {
+  if (toplevel === null || toplevel === "") return cwd;
+  const cdup = runGit(["rev-parse", "--show-cdup"], cwd);
+  if (cdup !== null) {
+    const logical = resolve(cwd, cdup);
+    try {
+      if (realpathSync(logical) === realpathSync(toplevel)) return logical;
+    } catch {
+      // Fall through to git's own answer.
+    }
+  }
+  return toplevel;
 }
 
 /**
@@ -82,7 +180,7 @@ export function currentWorktree(cwd = root) {
  *   SHA and its `%G?` signature-verification code (`G`=good, `B`=bad,
  *   `N`=unsigned, ...), or null if no commits/not a repo.
  */
-export function lastCommitInfo(cwd = root) {
+export function lastCommitInfo(cwd = process.cwd()) {
   const raw = runGit(["log", "-1", "--format=%H%x09%G?"], cwd);
   if (raw === null || raw === "") return null;
   const [sha, signature] = raw.split("\t");
@@ -91,12 +189,15 @@ export function lastCommitInfo(cwd = root) {
 }
 
 /**
- * @returns {string[]} `git status --porcelain` lines -- a fast, honest proxy
- *   for "there is uncommitted work here," not a gate re-run.
+ * @returns {string[] | null} `git status --porcelain` lines -- a fast, honest
+ *   proxy for "there is uncommitted work here," not a gate re-run. `[]` for a
+ *   clean tree; `null` when `git status` itself failed (not a repo, git
+ *   missing), so a failure is never mistaken for "clean".
  */
-export function uncommittedFiles(cwd = root) {
+export function uncommittedFiles(cwd = process.cwd()) {
   const raw = runGit(["status", "--porcelain"], cwd);
-  if (raw === null || raw === "") return [];
+  if (raw === null) return null;
+  if (raw === "") return [];
   return raw.split("\n").filter((line) => line.length > 0);
 }
 
@@ -128,11 +229,16 @@ export function findScratchJournals(repoRoot) {
 /**
  * Build the full handoff payload from live git/fs state.
  *
- * @param {string} cwd
+ * @param {string} [cwd]
+ * @param {string} [worktree] the worktree toplevel containing `cwd`, when the
+ *   caller already resolved it (`writeHandoff` does) -- resolved here via
+ *   currentWorktree when omitted
  * @returns {Record<string, unknown>}
  */
-export function buildHandoff(cwd = root) {
-  const worktree = currentWorktree(cwd);
+export function buildHandoff(
+  cwd = process.cwd(),
+  worktree = currentWorktree(cwd),
+) {
   return {
     capturedAt: new Date().toISOString(),
     branch: currentBranch(cwd),
@@ -143,8 +249,91 @@ export function buildHandoff(cwd = root) {
   };
 }
 
-// Deliberately inlined in every hook rather than shared: this pack's hook
-// budget is exactly its three hooks, so a helper module would cost a slot.
+/**
+ * One stderr line naming why no handoff was written -- advisory, so the
+ * failure is observable without failing the compaction.
+ *
+ * @param {string} reason
+ * @returns {null}
+ */
+function reportNotWritten(reason) {
+  try {
+    process.stderr.write(
+      `write-compact-handoff: handoff not written (${reason})\n`,
+    );
+  } catch {
+    // A broken stderr must not turn an advisory hook into a failing one.
+  }
+  return null;
+}
+
+/**
+ * Write this session's handoff under the git toplevel of `resolveRoot(...)`,
+ * atomically (`<handoff>.<pid>.partial` then `renameSync` over the final
+ * name). Creates nothing when the resolved directory does not exist or is
+ * not inside a git repository -- there is no git state to hand off there,
+ * and writing anyway would litter an arbitrary directory (even `$HOME`).
+ * `git rev-parse --show-toplevel` runs once per write; its answer is threaded
+ * through to currentWorktree/buildHandoff.
+ *
+ * @param {unknown} input the parsed `PreCompact` hook payload
+ * @param {Record<string, string | undefined>} env
+ * @param {string} fallbackCwd
+ * @returns {string | null} absolute path written, or null on any failure
+ *   (reported as one stderr line) -- never throws (advisory-only).
+ */
+export function writeHandoff(input, env, fallbackCwd) {
+  let partialPath = null;
+  try {
+    const root = resolveRoot(input, env, fallbackCwd);
+    if (!existsSync(root)) {
+      return reportNotWritten("target directory does not exist");
+    }
+    const gitToplevel = runGit(["rev-parse", "--show-toplevel"], root);
+    if (gitToplevel === null || gitToplevel === "") {
+      return reportNotWritten("not a git repository");
+    }
+    const toplevel = currentWorktree(root, gitToplevel);
+    const sessionId =
+      typeof input === "object" && input !== null
+        ? /** @type {{ session_id?: unknown }} */ (input).session_id
+        : undefined;
+    const handoff = {
+      ...buildHandoff(toplevel, toplevel),
+      sessionId: typeof sessionId === "string" ? sessionId : null,
+    };
+    const handoffPath = join(toplevel, handoffRelPath(sessionId));
+    mkdirSync(join(toplevel, "tmp"), { recursive: true });
+    partialPath = `${handoffPath}.${process.pid}.partial`;
+    writeFileSync(partialPath, `${JSON.stringify(handoff, null, 2)}\n`);
+    renameSync(partialPath, handoffPath);
+    partialPath = null;
+    return handoffPath;
+  } catch (error) {
+    if (partialPath !== null) {
+      try {
+        unlinkSync(partialPath);
+      } catch {
+        // Best-effort -- a leftover `.partial` never matches the reinject scan.
+      }
+    }
+    // Advisory-only -- never block or fail a compaction over this.
+    const code =
+      typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+    return reportNotWritten(
+      typeof code === "string"
+        ? code
+        : error instanceof Error
+          ? error.message
+          : String(error),
+    );
+  }
+}
+
+// Deliberately inlined in every hook rather than shared, so each hook stays
+// one self-contained file.
 // `import.meta.url` is symlink-resolved but `process.argv[1]` is not, so
 // comparing them directly is false under any symlinked path and the body would
 // never run -- exit 0.
@@ -158,23 +347,17 @@ function isEntryPoint() {
 
 // Only run when invoked directly, not when imported for testing.
 if (isEntryPoint()) {
-  // Drain stdin (Claude Code pipes the hook payload) even though this hook
-  // doesn't need any field from it -- leaving it unread can leave the pipe
-  // open under some harness/runtime combinations. `void` references the
-  // loop variable explicitly rather than relying on a project's eslint
-  // config exempting `^_`-prefixed vars for .mjs files, which this
-  // baseline's own eslint.config.js only does for `.ts`.
-  for await (const chunk of process.stdin) {
-    void chunk;
-  }
-
+  // Read the payload for `cwd`/`session_id`; a malformed payload degrades to
+  // `{}` (CLAUDE_PROJECT_DIR / process.cwd(), legacy unkeyed file).
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  let input;
   try {
-    const handoff = buildHandoff();
-    const handoffPath = join(root, HANDOFF_REL_PATH);
-    mkdirSync(join(root, "tmp"), { recursive: true });
-    writeFileSync(handoffPath, `${JSON.stringify(handoff, null, 2)}\n`);
+    input = JSON.parse(Buffer.concat(chunks).toString("utf8"));
   } catch {
-    // Advisory-only -- never block or fail a compaction over this.
+    input = {};
   }
+
+  writeHandoff(input, process.env, process.cwd());
   process.exit(0);
 }

package/templates/packs/harness-extras/pack.json

@@ -1,17 +1,17 @@
 {
   "schemaVersion": 1,
   "name": "harness-extras",
-  "description": "Compaction handoff hooks, a read-only Bash guard, a type-design analyzer agent, and a file-budget gate -- cut from the baseline purely to fit its hard caps, not because they failed the generalization test.",
+  "description": "Adds Claude Code session ergonomics on top of the baseline: a pair of hooks that carry a work summary across a context-window compaction, a hook that blocks non-read-only Bash commands from read-only review spokes, and a five-row statusLine (plus a per-subagent row renderer) -- the only documented surface carrying live context-window pressure.",
   "modes": ["fresh", "adopt"],
   "budget": {
-    "agents": 1,
+    "agents": 0,
     "skills": 0,
-    "hooks": 3,
+    "hooks": 6,
     "workflows": 0,
     "scripts": 0
   },
   "requires": {
-    "paths": ["bin/lib/agent-roster.mjs", "bin/lib/report.mjs"]
+    "paths": ["bin/lib/agent-roster.mjs"]
   },
   "wiring": {
     "settings": {
@@ -51,15 +51,20 @@
         }
       ]
     },
-    "packageScripts": {},
-    "verifySteps": [
-      {
-        "id": "file-budget",
-        "group": "build",
-        "name": "Check file budget",
-        "cmd": ["node", "bin/check-file-budget.mjs"]
+    "settingsTopLevel": {
+      "statusLine": {
+        "type": "command",
+        "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/statusline.mjs\"",
+        "refreshInterval": 30,
+        "padding": 1
+      },
+      "subagentStatusLine": {
+        "type": "command",
+        "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-statusline.mjs\""
       }
-    ]
+    },
+    "packageScripts": {},
+    "verifySteps": []
   },
-  "adoptNotes": "check-file-budget.mjs's ROOTS default assumes a flat src/+tests/ layout and its ceilings are this baseline's defaults -- in an adopted project, re-point ROOTS at the project's real source layout (or drop the gate) before wiring it. The hooks and the agent have no such dependency and install anywhere a .claude/ directory exists. The verify step assumes a bin/verify.mjs-shaped gate runner; if the project has none, install the other artifacts and report the gate as not installable rather than inventing one."
+  "adoptNotes": "The statusline and compaction hooks install anywhere a .claude/ directory exists, but guard-readonly-bash.mjs imports ../../bin/lib/agent-roster.mjs (the baseline's list of writer spokes) -- copy that file alongside it in an adopted project, or skip that one hook. The PreCompact hook writes tmp/compact-handoff-<session_id>.json under the git worktree the session runs in (from the hook payload's cwd, since CLAUDE_PROJECT_DIR does not follow a session into a linked worktree) -- fresh mode's baseline .gitignore already lists tmp/ unconditionally, but an adopted project's own .gitignore was never touched by adopt mode, so add tmp/ there too before this pack's hooks run, or the handoff artifact can end up committed. The statusline scripts read only the stdin payload, .git/HEAD (via node:fs, never a git subprocess) and process.availableMemory()/os.totalmem(), so they install anywhere a .claude/ directory exists -- no dependency on the baseline's file layout. The one real adopt risk is the two top-level settings keys: a project that already defines statusLine or subagentStatusLine collides, and its existing value must be shown and decided on, never overwritten -- if either is already set, skip that key and the three statusline scripts, and install the rest of this pack (the hooks) normally rather than failing the whole install. A .claude/settings.local.json or the user's own ~/.claude/settings.json statusLine also shadows the project one -- check both before concluding the pack is wired. rate_limits.spend_limit and prompt_cache need Claude Code v2.1.251+, and the per-subagent model/contextWindowSize/effort fields need v2.1.205+/v2.1.214+; each renders only when present, so an older Claude Code degrades to fewer segments rather than breaking. The scripts behave the same on macOS and Linux; the memory segment uses process.availableMemory() (Node 22+), and on macOS with an older Node it is hidden rather than shown from os.freemem(), which undercounts there. Below roughly 40 columns the layout drops segments by priority rather than wrapping. The size-ratchet gate and the type-design-analyzer agent that used to ship here are now the separate `quality` pack."
 }