@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/framework/hooks/shared/activity-logger.js

@@ -1,28 +1,5 @@
-/**
- * Activity Logger — Session-scoped hook event log
- *
- * Writes hook activity to .morph/logs/activity.jsonl for live consumption
- * (statusline, `morph-spec fleet`, etc).
- *
- * Design constraints:
- * - Synchronous only (hooks run in process, no async overhead)
- * - Fail-silent (never throws — hooks must not be blocked by the logger)
- * - ≤5ms per call (no retries, no network)
- * - APPEND-ONLY: one `appendFileSync` line per event, O(1) per call. The
- *   previous format did a read-modify-write of the WHOLE JSON doc per call
- *   (logHookActivity/logEvent both read, mutated, and rewrote the entire
- *   file) — O(n²) across a session once tool calls number in the hundreds,
- *   with 6 hooks each calling this 3-5x per Write. Same discipline as
- *   telemetry-logger.js's events.jsonl.
- * - Windows-safe paths via path.join
- *
- * Exported names/signatures are unchanged from the previous doc-based
- * implementation on purpose — hooks outside this file's ownership
- * (gate-guard.js, enforce-phase-writes.js,
- * loop-detect.js, protect-spec-files.js, validate-completion.js) call
- * logHookActivity/logEvent and must keep working untouched. Only the
- * on-disk format changed.
- */
+// Append-only on purpose: rewriting a whole JSON doc per event is O(n²) across
+// a session. Fail-silent: never blocks a hook.
 
 import {
   appendFileSync, readFileSync, mkdirSync, existsSync, statSync, renameSync, writeFileSync,
@@ -32,10 +9,7 @@ import { join } from 'path';
 const LOGS_DIR = '.morph/logs';
 export const ACTIVITY_FILE = join(LOGS_DIR, 'activity.jsonl');
 
-// SessionStart (worktree-context.js) rotates the log once it crosses this
-// size — the archive/rotation call site resetActivity()/archiveSession()
-// were written for but never got until now.
-export const ROTATE_THRESHOLD_BYTES = 2 * 1024 * 1024; // 2 MB
+export const ROTATE_THRESHOLD_BYTES = 2 * 1024 * 1024;
 
 function getActivityPath(projectPath) {
   return join(projectPath || process.cwd(), ACTIVITY_FILE);
@@ -49,20 +23,17 @@ function ensureLogsDir(projectPath) {
 }
 
 function nowTs() {
-  return new Date().toTimeString().slice(0, 8); // HH:MM:SS — matches the previous format
+  return new Date().toTimeString().slice(0, 8);
 }
 
-/** Append one JSON line. Fail-silent, O(1) regardless of file size. */
 function appendLine(projectPath, line) {
   try {
     ensureLogsDir(projectPath);
     appendFileSync(getActivityPath(projectPath), JSON.stringify(line) + '\n', 'utf-8');
   } catch {
-    // Fail-silent — never block hooks
   }
 }
 
-/** Read every parseable line back. A corrupt/truncated line is skipped, not fatal. */
 function readLines(projectPath) {
   try {
     const activityPath = getActivityPath(projectPath);
@@ -75,7 +46,7 @@ function readLines(projectPath) {
       try {
         lines.push(JSON.parse(trimmed));
       } catch {
-        // skip a single corrupt line — don't lose the whole stream
+        // a process killed mid-write leaves a truncated line
       }
     }
     return lines;
@@ -84,38 +55,15 @@ function readLines(projectPath) {
   }
 }
 
-/**
- * Log a hook firing event to the session activity log.
- *
- * @param {string} name   - Hook name (e.g. 'dispatch.js', 'enrich-prompt')
- * @param {string} event  - Claude Code event (e.g. 'PostToolUse', 'UserPromptSubmit')
- * @param {string} result - Outcome summary (e.g. 'ok', 'blocked', 'checkpoint_saved')
- * @param {string} [projectPath] - Project root (defaults to cwd)
- */
 export function logHookActivity(name, event, result, projectPath) {
   appendLine(projectPath, { kind: 'hook', name, event, result, ts: nowTs() });
 }
 
-/**
- * Log a structured event to the session activity log.
- *
- * @param {string} type   - Event type (e.g., 'task_start', 'loop_detected')
- * @param {Object} data   - Event data payload
- * @param {string} [projectPath] - Project root (defaults to cwd)
- */
 export function logEvent(type, data, projectPath) {
   appendLine(projectPath, { kind: 'event', type, data, ts: nowTs() });
 }
 
-/**
- * Read the current activity log, reconstructed into the aggregate shape
- * older consumers expect: `{ sessionId, feature, phase, hooks, events }`.
- * `sessionId`/`feature`/`phase` come from the synthetic 'session' header
- * line `resetActivity()` writes, when present.
- *
- * @param {string} [projectPath]
- * @returns {{ sessionId: string, feature: string, phase: string, hooks: Array, events: Array }|null}
- */
+/** @returns {{ sessionId: string, feature: string, phase: string, hooks: Array, events: Array }|null} */
 export function readActivity(projectPath) {
   const lines = readLines(projectPath);
   if (lines.length === 0) return null;
@@ -132,17 +80,8 @@ export function readActivity(projectPath) {
   };
 }
 
-/**
- * Reset the activity log for a new session — the one operation in this file
- * that is NOT append-only (a session boundary, not a log entry). Truncates
- * the file and writes a 'session' header line so `readActivity()` can
- * recover sessionId/feature/phase.
- *
- * @param {string} sessionId  - ISO timestamp of new session
- * @param {string} feature    - Active feature name (empty string if none)
- * @param {string} phase      - Current phase (empty string if none)
- * @param {string} [projectPath]
- */
+// The one write that truncates: the 'session' header is what `readActivity()`
+// recovers sessionId/feature/phase from.
 export function resetActivity(sessionId, feature, phase, projectPath) {
   try {
     ensureLogsDir(projectPath);
@@ -154,18 +93,9 @@ export function resetActivity(sessionId, feature, phase, projectPath) {
     };
     writeFileSync(getActivityPath(projectPath), JSON.stringify(session) + '\n', 'utf-8');
   } catch {
-    // Fail-silent
   }
 }
 
-/**
- * Archive the current activity log to sessions/ for historical logging.
- * Only archives when there is at least one hook or event line — a bare (or
- * absent) log is not worth preserving. `renameSync` keeps this O(1) even at
- * the multi-MB sizes rotation is meant to catch (no read+rewrite of content).
- *
- * @param {string} [projectPath] - Project root (defaults to cwd)
- */
 export function archiveSession(projectPath) {
   try {
     const activityPath = getActivityPath(projectPath);
@@ -183,20 +113,10 @@ export function archiveSession(projectPath) {
     const archivePath = join(sessionsDir, `${stamp}.jsonl`);
     renameSync(activityPath, archivePath);
   } catch {
-    // Fail-silent
   }
 }
 
-/**
- * Rotate the activity log when it crosses `thresholdBytes` — the real call
- * site for archiveSession() (previously written but never invoked anywhere).
- * Called from worktree-context.js on SessionStart, the only reliable
- * "between sessions" checkpoint the harness gets.
- *
- * @param {string} [projectPath] - Project root (defaults to cwd)
- * @param {number} [thresholdBytes] - Rotate once the log is at least this large
- * @returns {boolean} true if a rotation was performed
- */
+/** @returns {boolean} true if a rotation was performed */
 export function rotateActivityLogIfLarge(projectPath, thresholdBytes = ROTATE_THRESHOLD_BYTES) {
   try {
     const activityPath = getActivityPath(projectPath);

package/framework/hooks/shared/agent-reap.js

@@ -1,15 +1,5 @@
-/**
- * agent-reap.js — dispara `morph-spec worktree reap` em background no SessionStart.
- *
- * O hook de SessionStart tem 5 s de timeout e o reaper mede git por árvore: por isso o
- * disparo só olha o disco (nenhum subprocesso) e solta este arquivo como worker DESTACADO
- * (`--run <raiz>`), que chama o CLI. Só a raiz: o worker nasce com `cwd` no git common dir
- * e nunca segura o diretório de uma worktree.
- *
- * Fail-open em tudo. `MORPH_WORKTREE_REAP=0` desliga.
- *
- * @module agent-reap
- */
+// O SessionStart tem 5 s: o disparo só olha o disco e solta um worker DESTACADO
+// com `cwd` no git common dir, que nunca segura o diretório de uma worktree.
 
 import { spawn } from 'child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
@@ -29,7 +19,6 @@ function anyEntry(dir, pattern) {
   try { return readdirSync(dir).some((name) => pattern.test(name)); } catch { return false; }
 }
 
-/** Uma worktree de agent registrada, ou uma branch `morph-task/agent-*` (solta ou empacotada). */
 export function hasAgentLeftovers(common) {
   if (anyEntry(join(common, 'worktrees'), ADMIN_DIR)) return true;
   if (anyEntry(join(common, 'refs', 'heads', 'morph-task'), AGENT_BRANCH_FILE)) return true;
@@ -49,10 +38,6 @@ function recentlyKicked(marker, now) {
   }
 }
 
-/**
- * @param {string} dir - diretório do projeto da sessão
- * @returns {{ kicked: boolean, reason?: string, pid?: number }}
- */
 export function kickAgentReap(dir, { spawnFn = spawn, env = process.env, now = Date.now } = {}) {
   if (env.MORPH_WORKTREE_REAP === '0') return { kicked: false, reason: 'disabled' };
   const common = resolveGitCommonDir(dir);

package/framework/hooks/shared/build-check.js

@@ -1,12 +1,3 @@
-/**
- * Build/Typecheck verification utility.
- *
- * Stack-aware: determines the correct build command(s) based on project stack.
- * Used by the Stop hook and `morph-spec verify` to verify code health.
- *
- * Pure functions — no I/O except the actual build execution.
- */
-
 import { execSync } from 'child_process';
 import { existsSync } from 'fs';
 import { join } from 'path';
@@ -22,25 +13,8 @@ function isFrontendStack(s) {
   return s.includes('nextjs') || s.includes('node') || s.includes('react') || s.includes('vue');
 }
 
-/**
- * Determine the build command for a SINGLE (non-monorepo) stack string.
- *
- * Kept for backward compatibility with single-stack projects and existing
- * callers. A monorepo stack that mixes a frontend token with "dotnet" (e.g.
- * the detector's own `${frontendStack}+dotnet` format, or a hyphenated
- * `dotnet-nextjs`) should resolve through `getBuildSteps()` instead: this
- * function alone can only ever return ONE command, and — because it checks
- * `dotnet` before the frontend tokens — a compound stack always resolves to
- * `dotnet build` even when the frontend is what actually needs checking (or
- * when there's no root-level `.sln`/`.csproj`, e.g. in a monorepo where the
- * backend lives in a subfolder). `getBuildSteps()` runs BOTH sides, each
- * from its own working directory, instead of one command winning by
- * substring match order.
- *
- * @param {string} stack - Project stack (e.g., 'dotnet-nextjs', 'nextjs')
- * @param {boolean} [hasTsConfig] - Whether tsconfig.json exists (for TS projects)
- * @returns {string|null} Build command or null if no check available
- */
+// Single stack only: a compound stack resolves to `dotnet build` alone. Use
+// `getBuildSteps()` for those.
 export function getBuildCommand(stack, hasTsConfig = false) {
   if (!stack) return null;
   const s = stack.toLowerCase();
@@ -56,26 +30,8 @@ export function getBuildCommand(stack, hasTsConfig = false) {
   return null;
 }
 
-/**
- * Resolve the build step(s) to run for a project, monorepo-aware.
- *
- * A monorepo stack mixes a frontend token and "dotnet" (see
- * `detectProject()`'s own `${frontendStack}+dotnet` format) — in that case
- * BOTH sides are checked, each from its own working directory
- * (`frontendPath` / `backendPath`, as stored in
- * `.morph/config/config.json → project`), instead of one command silently
- * winning — or running from the wrong cwd — by substring match order.
- * Single-stack projects (no `frontendPath`/`backendPath`, or a stack that
- * only matches one side) resolve to exactly one step, from `cwd`, matching
- * `getBuildCommand()`'s existing single-stack behavior.
- *
- * @param {string} stack
- * `backendTarget` names the solution/project to build (relative to the backend
- * directory) when that directory holds none itself.
- *
- * @param {{ cwd: string, frontendPath?: string, backendPath?: string, backendTarget?: string }} opts
- * @returns {Array<{ command: string, cwd: string }>}
- */
+// A compound stack checks BOTH sides, each from its own directory.
+// `backendTarget` names the solution when the backend directory holds none.
 export function getBuildSteps(stack, { cwd, frontendPath, backendPath, backendTarget } = {}) {
   if (!stack || !cwd) return [];
   const s = stack.toLowerCase();
@@ -88,10 +44,7 @@ export function getBuildSteps(stack, { cwd, frontendPath, backendPath, backendTa
 
   if (isFrontendStack(s)) {
     const frontendDir = frontendPath ? join(cwd, frontendPath) : cwd;
-    // node_modules guard : a fresh worktree before
-    // `morph-spec worktree link` has tsconfig.json (versioned) but no toolchain — running
-    // `npx tsc` there fetches an unrelated "tsc" package and fails noisily. No toolchain →
-    // no tsc step; the real typecheck runs wherever node_modules exists (root/CI).
+    // Without node_modules, `npx tsc` fetches an unrelated "tsc" package.
     if (
       existsSync(join(frontendDir, 'tsconfig.json')) &&
       existsSync(join(frontendDir, 'node_modules'))
@@ -103,39 +56,17 @@ export function getBuildSteps(stack, { cwd, frontendPath, backendPath, backendTa
   return steps;
 }
 
-/**
- * Parse build command result into a structured object.
- *
- * @param {number} exitCode - Process exit code (0 = success)
- * @param {string} output - stdout+stderr from build
- * @returns {{ status: 'pass'|'fail', output: string }}
- */
 export function parseBuildResult(exitCode, output) {
   const trimmed = (output || '').trim();
   if (exitCode === 0) {
     return { status: 'pass', output: '' };
   }
-  // Truncate to last 20 lines
   const lines = trimmed.split('\n');
   const truncated = lines.slice(-20).join('\n');
   return { status: 'fail', output: truncated };
 }
 
-/**
- * Run build check for a project — monorepo-aware (see `getBuildSteps()`).
- *
- * For a compound stack (e.g. "nextjs+dotnet"), runs each resolved step in
- * its own working directory and fails if any step fails; output from all
- * failing steps is concatenated (prefixed by the command that produced it)
- * so a frontend typecheck failure and a backend build failure are never
- * silently masked by one another.
- *
- * @param {string} cwd - Project root directory
- * @param {string} stack - Project stack string
- * @param {number} [timeout=30000] - Timeout in ms
- * @param {{ frontendPath?: string, backendPath?: string, backendTarget?: string }} [paths] - Monorepo sub-paths, from config.json → project
- * @returns {{ status: 'pass'|'fail'|'skip', output: string }}
- */
+/** @returns {{ status: 'pass'|'fail'|'skip', output: string }} */
 export function runBuildCheck(cwd, stack, timeout = 30000, paths = {}) {
   const steps = getBuildSteps(stack, { cwd, frontendPath: paths.frontendPath, backendPath: paths.backendPath, backendTarget: paths.backendTarget });
   if (steps.length === 0) return { status: 'skip', output: '' };

package/framework/hooks/shared/claim-registry.js

@@ -1,44 +1,13 @@
-/**
- * claim-registry.js — advisory feature ownership across parallel sessions.
- *
- * Two Claude Code sessions worked the SAME feature at the same time without
- * seeing each other: one finished it and removed the worktree out from under
- * the other's running sub-agent. A complete recap.md was discarded, a sub-agent
- * wasted, and a decision taken on state that was already obsolete. There was no
- * lock, no claim, no heartbeat — not even a warning.
- *
- * DELIBERATELY ADVISORY. This is not a lock: nothing here ever blocks a
- * command. The framework is fail-open by principle, and a strong lock left
- * behind by a crashed session would strand a feature for no gain. Being
- * VISIBLE is the whole fix.
- *
- * Location: `<git-common-dir>/morph-spec/claims.json`, beside the fleet's
- * env-registry, for the same three reasons — it can never dirty the `git
- * status` the finish gates read, it survives `git clean -fdx`, and the COMMON
- * dir is the one place every linked worktree of the repo shares. That last one
- * is decisive here: in the observed incident one session sat inside the
- * worktree and the other in the primary root, so a claim written to the
- * branch-local `feature.json` would have been invisible to exactly the session
- * that needed to read it.
- *
- * Writes are tmp+rename (torn file impossible); a corrupt registry reads as
- * empty — the cost is a lost warning, never a crash.
- */
+// ADVISORY, never a lock: a lock left by a crashed session would strand a feature.
+// Lives in the git COMMON dir, the one place every worktree of the repo shares.
 
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 
-/**
- * A claim with no heartbeat for this long is considered dead. The heartbeat
- * fires on tool activity, so this is really "how long a session may sit idle
- * before its claim stops warning others".
- */
 export const CLAIM_TTL_MS = 30 * 60 * 1000;
 
-/** Minimum gap between heartbeat WRITES. The heartbeat runs on every tool call. */
 export const HEARTBEAT_THROTTLE_MS = 60 * 1000;
 
-/** Claim file path for a repo's common git dir. */
 export function claimsPath(gitCommonDir) {
   return join(gitCommonDir, 'morph-spec', 'claims.json');
 }
@@ -60,23 +29,13 @@ function writeRegistry(gitCommonDir, registry) {
   renameSync(tmp, path);
 }
 
-/** Is this claim still within its TTL? A missing/unparseable heartbeat is dead. */
 export function isLive(claim, now = Date.now()) {
   const beat = Date.parse(claim?.heartbeatAt ?? '');
   return Number.isFinite(beat) && now - beat < CLAIM_TTL_MS;
 }
 
-/**
- * Claim a feature for this session, or refresh an existing claim of ours.
- *
- * A claim held by ANOTHER session is TAKEN OVER, not refused — advisory by
- * design, and the caller has already been warned via `foreignClaim`. The
- * takeover is recorded in `previousSessionId` so it is never silent.
- *
- * @param {string} feature
- * @param {{ gitCommonDir: string, sessionId: string, pid?: number, path?: string }} opts
- * @returns {object} the stored claim
- */
+// Another session's claim is TAKEN OVER, not refused; `previousSessionId` keeps
+// the takeover visible.
 export function acquireClaim(feature, { gitCommonDir, sessionId, pid = process.pid, path = null }) {
   const registry = readRegistry(gitCommonDir);
   const previous = registry.claims[feature];
@@ -95,17 +54,7 @@ export function acquireClaim(feature, { gitCommonDir, sessionId, pid = process.p
   return claim;
 }
 
-/**
- * Refresh our own claim's heartbeat. Throttled — this runs on every tool call,
- * and a write per call would be pure I/O waste.
- *
- * Never touches a claim owned by another session: a heartbeat is proof of life,
- * and forging someone else's would defeat the TTL.
- *
- * @param {string} feature
- * @param {{ gitCommonDir: string, sessionId: string }} opts
- * @returns {boolean} true when a write actually happened
- */
+// Never another session's claim: forging its heartbeat would defeat the TTL.
 export function heartbeatClaim(feature, { gitCommonDir, sessionId }) {
   const registry = readRegistry(gitCommonDir);
   const claim = registry.claims[feature];
@@ -119,45 +68,13 @@ export function heartbeatClaim(feature, { gitCommonDir, sessionId }) {
   return true;
 }
 
-/** Local, git-independent heartbeat pre-check marker — see `shouldHeartbeat`. */
 function heartbeatMarkPath(cwd) {
   return join(cwd, '.morph', 'logs', '.heartbeat-check.json');
 }
 
-/**
- * Cheap, git-independent pre-check for whether a heartbeat is even worth
- * ATTEMPTING. `heartbeatClaim` already throttles the WRITE to `claims.json`,
- * but that registry lives under the git COMMON dir — resolving it (even via
- * the pure-FS `git-paths.js`, never mind the old `execSync('git rev-parse
- * --git-common-dir')`) is work `telemetry-log.js` pays on every tool call.
- * This answers "is it due" from a tiny marker colocated with the CALLER's own
- * `.morph/logs/` (already known, no git lookup of any kind) so that on ~99%
- * of calls NOTHING git-related happens at all — not the subprocess, not even
- * the FS walk.
- *
- * Side effect: when it returns `true` (heartbeat IS due), it immediately
- * stamps the marker — mirroring `heartbeatClaim`'s own check-and-write
- * pattern — so the NEXT call within the throttle window short-circuits here
- * even if the caller's subsequent git resolution then fails (not actually a
- * git repo, say): a failed attempt should not be retried on every single tool
- * call either.
- *
- * This is a SEPARATE, LOCAL throttle from `claims.json`'s own authoritative
- * `heartbeatAt` (keyed by git-common-dir, enforced inside `heartbeatClaim`) —
- * the two can drift by up to one throttle window with no consequence: a
- * missed local pre-check only costs a claim heartbeat that gets written on
- * the very next call, and claims are advisory to begin with.
- *
- * Fail-open: any read/write error is treated as "due" — a broken marker must
- * never permanently suppress the actual (authoritative) heartbeat. Not
- * tmp+rename like `claims.json` — this file is low-stakes (worst case from a
- * torn write is corrupt JSON, which just reads back as "due" next time) and
- * shared by nobody outside this one project tree.
- *
- * @param {string} feature
- * @param {{ cwd: string, sessionId: string, now?: number }} opts
- * @returns {boolean}
- */
+// Local pre-check so most tool calls skip resolving the git common dir. Stamps
+// the marker when due, so a failed attempt is not retried on every call; an
+// unreadable marker counts as due.
 export function shouldHeartbeat(feature, { cwd, sessionId, now = Date.now() }) {
   const markPath = heartbeatMarkPath(cwd);
   try {
@@ -167,27 +84,16 @@ export function shouldHeartbeat(feature, { cwd, sessionId, now = Date.now() }) {
       if (Number.isFinite(at) && now - at < HEARTBEAT_THROTTLE_MS) return false;
     }
   } catch {
-    // missing/corrupt marker — treat as due
   }
 
   try {
     mkdirSync(dirname(markPath), { recursive: true });
     writeFileSync(markPath, JSON.stringify({ feature, sessionId, at: new Date(now).toISOString() }));
   } catch {
-    // best-effort — a failed stamp only costs a repeated attempt next call
   }
   return true;
 }
 
-/**
- * The LIVE claim on this feature held by a session that is not us — the thing
- * worth warning about. Returns null when the feature is unclaimed, claimed by
- * us, or claimed by a session whose heartbeat went stale.
- *
- * @param {string} feature
- * @param {{ gitCommonDir: string, sessionId?: string }} opts
- * @returns {object|null}
- */
 export function foreignClaim(feature, { gitCommonDir, sessionId }) {
   const claim = readRegistry(gitCommonDir).claims[feature];
   if (!claim) return null;
@@ -195,14 +101,6 @@ export function foreignClaim(feature, { gitCommonDir, sessionId }) {
   return isLive(claim) ? claim : null;
 }
 
-/**
- * Drop a feature's claim. Called by the manual `morph-spec claim <f> --release`
- * (recovering from a session that died without releasing) and by `finish`.
- *
- * @param {string} feature
- * @param {{ gitCommonDir: string }} opts
- * @returns {boolean} false when there was nothing to release
- */
 export function releaseClaim(feature, { gitCommonDir }) {
   const registry = readRegistry(gitCommonDir);
   if (!registry.claims[feature]) return false;
@@ -211,14 +109,7 @@ export function releaseClaim(feature, { gitCommonDir }) {
   return true;
 }
 
-/**
- * Every claim on record, live and stale, newest heartbeat first. `live` is
- * computed, never stored — a stored flag would go wrong the moment nobody
- * rewrites the file.
- *
- * @param {string} gitCommonDir
- * @returns {object[]}
- */
+// `live` is computed, never stored: a stored flag goes wrong once nobody rewrites the file.
 export function listClaims(gitCommonDir) {
   const now = Date.now();
   return Object.values(readRegistry(gitCommonDir).claims)
@@ -226,7 +117,6 @@ export function listClaims(gitCommonDir) {
     .sort((a, b) => String(b.heartbeatAt).localeCompare(String(a.heartbeatAt)));
 }
 
-/** Human-readable age of a claim's last heartbeat ("3 min", "2 h", "—"). */
 export function claimAge(claim, now = Date.now()) {
   const beat = Date.parse(claim?.heartbeatAt ?? '');
   if (!Number.isFinite(beat)) return '—';

package/framework/hooks/shared/command-tokens.js

@@ -1,19 +1,6 @@
-/**
- * command-tokens.js — shell-ish tokenizer shared by the PreToolUse Bash guards.
- *
- * Lives in shared/ (not inside a hook) on purpose: every core hook ends in a
- * standalone tail that reads stdin and exits, so a hook importing a sibling
- * hook for a helper would fire THAT tail in its own process — consuming the
- * payload and exiting before the importer ever ran. block-raw-worktree-add
- * and block-destructive-worktree-removal both read paths off these tokens,
- * so they agree on what a quoted path is.
- */
+// Lives in shared/: a hook importing a sibling hook would fire that hook's
+// stdin-reading tail in its own process.
 
-/**
- * Split a shell-ish command into tokens, honoring single and double quotes.
- * @param {string} command
- * @returns {string[]}
- */
 export function tokenize(command) {
   const tokens = [];
   const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
@@ -22,7 +9,6 @@ export function tokenize(command) {
   return tokens;
 }
 
-/** Index of the first pipe (`|`, not `||` nor `>|`) outside quotes, or -1. */
 function firstUnquotedPipe(command) {
   const s = String(command || '');
   let quote = null;
@@ -43,24 +29,11 @@ function firstUnquotedPipe(command) {
   return -1;
 }
 
-/**
- * Does the command pipe one process into another outside quotes? Without
- * `pipefail` the shell reports the LAST command's status, so the exit code of
- * `dotnet test … | grep …` is grep's, not the test run's.
- * @param {string} command
- * @returns {boolean}
- */
 export function hasUnquotedPipe(command) {
   return firstUnquotedPipe(command) >= 0;
 }
 
-/**
- * The work a command does, without the filter that shapes its output:
- * `dotnet test 2>&1 | tail -25` and `dotnet test | tail -20` run the same
- * tests. Whitespace collapsed, stderr redirections dropped.
- * @param {string} command
- * @returns {string}
- */
+/** The command without the pipe filter and stderr redirections that shape its output. */
 export function producerOf(command) {
   const s = String(command || '');
   const pipe = firstUnquotedPipe(s);
@@ -70,11 +43,6 @@ export function producerOf(command) {
     .trim();
 }
 
-/**
- * The command split at `;`, newline and background `&` outside quotes, plus
- * whether a background `&` was seen. `&&`, `||` and `>&`/`&>` redirections
- * stay inside their segment.
- */
 function topLevelSegments(command) {
   const s = String(command || '');
   const segments = [];
@@ -102,14 +70,7 @@ function topLevelSegments(command) {
 
 const REPORTER = /^(?:echo|printf|true|:|exit\s+0)\b/;
 
-/**
- * Is the exit code of this command the exit code of the work it ran? The
- * shell reports the last segment of a `;` sequence: `dotnet test > log;
- * echo "exit=$?"` always exits 0, and so does `dotnet test || true`. A pipe
- * without `pipefail` reports the filter, and a background `&` reports 0.
- * @param {string} command
- * @returns {boolean}
- */
+/** True when the shell reports something other than the work's exit code (`; echo`, `|| true`, pipe, `&`). */
 export function exitCodeMasked(command) {
   const { segments, background } = topLevelSegments(command);
   if (background) return true;
@@ -253,14 +214,8 @@ function commandWriteTargets(head, body) {
   return targets;
 }
 
-/**
- * Files a command writes: stdout redirection (`>`, `>>`, `1>`, `&>`), `tee`, `sed -i`,
- * `perl -i`, the `cp`/`mv` destination, and a python/node `-c`/`-e`/heredoc script's writes.
- * The redirect scan stops at the line that opens a heredoc: the body is data, and an
- * apostrophe in it would derail the quote-aware split. Quoted operators are text.
- * @param {string} command
- * @returns {string[]}
- */
+// The redirect scan stops at the heredoc line: the body is data, and an
+// apostrophe in it would derail the quote-aware split.
 export function writeTargets(command) {
   const lines = String(command || '').split('\n');
   const heredocAt = lines.findIndex((line) => line.includes('<<'));