vouchington-tooling 0.47.0 → 0.48.0

package/README.md

@@ -165,7 +165,11 @@ pass `--root`, `--workflow-directory`, or `--action-directory` for consumer-owne
 Claude-compatible transcript when `CURSOR_SESSION_ID` is set, and Grok's `updates.jsonl` session
 layout when `GROK_SESSION_ID` is set. Use `--grok-sessions-dir` to point discovery at a nondefault
 Grok session root. Without `--session-id`, it reads those session identities from the host
-environment.
+environment. `resolveTranscriptFile` is the canonical resolver: it lowercases and UUID-validates
+session ids, honors `CODEX_HOME`, `CLAUDE_CONFIG_DIR` and `GROK_HOME`, and errors when more than one
+transcript matches. The subpath also exports `normalizeCommandPrefix`, `splitCommandSegments`,
+`isPackageRunner`, `asRecord`, `asArray` and `openTranscriptLines(path, { maxRecordBytes })`, which
+streams lines (2 MiB per record by default) and throws from the iterable on an oversized record.
 
 `retrospective-facts` keeps local Git evidence separate from GitHub PR data. `Commits ahead of
 origin/main` is populated only from a local ancestry range; GitHub responses instead populate

package/dist/agent-harness-identity/index.d.mts

@@ -1,26 +1,4 @@
-export declare const HARNESS_IDS: readonly ["claude", "codex", "grok", "cursor"];
-export type HarnessId = (typeof HARNESS_IDS)[number];
-export interface HarnessEnvironment {
-    readonly claude: {
-        readonly compatMode: boolean;
-        readonly sessionId?: string;
-    };
-    readonly codex: {
-        readonly sessionId?: string;
-    };
-    readonly cursor: {
-        readonly agentMarker: boolean;
-        readonly sessionId?: string;
-    };
-    readonly grok: {
-        readonly agentMarker: boolean;
-        readonly hookEvent: boolean;
-        readonly sessionId?: string;
-    };
-}
-export interface HarnessSessionIdentity {
-    readonly harness: HarnessId;
-    readonly sessionId: string;
-}
+import { type HarnessEnvironment } from 'agent-blackboard';
+export { HARNESS_IDS, selectHarnessSession } from 'agent-blackboard';
+export type { HarnessEnvironment, HarnessId, HarnessSessionIdentity } from 'agent-blackboard';
 export declare function inspectHarnessEnvironment(env?: NodeJS.ProcessEnv): HarnessEnvironment;
-export declare function selectHarnessSession(environment: HarnessEnvironment, precedence: readonly HarnessId[]): HarnessSessionIdentity | undefined;

package/dist/agent-harness-identity/index.mjs

@@ -1,30 +1,5 @@
-export const HARNESS_IDS = ['claude', 'codex', 'grok', 'cursor'];
-function session(value) {
-    return value ? { sessionId: value } : {};
-}
+import { inspectHarnessEnvironment as inspect } from 'agent-blackboard';
+export { HARNESS_IDS, selectHarnessSession } from 'agent-blackboard';
 export function inspectHarnessEnvironment(env = process.env) {
-    return {
-        claude: {
-            compatMode: env.CLAUDECODE === '1',
-            ...session(env.CLAUDE_CODE_SESSION_ID),
-        },
-        codex: session(env.CODEX_THREAD_ID),
-        cursor: {
-            agentMarker: Boolean(env.CURSOR_AGENT),
-            ...session(env.CURSOR_SESSION_ID),
-        },
-        grok: {
-            agentMarker: Boolean(env.GROK_AGENT),
-            hookEvent: Boolean(env.GROK_HOOK_EVENT),
-            ...session(env.GROK_SESSION_ID),
-        },
-    };
-}
-export function selectHarnessSession(environment, precedence) {
-    for (const harness of precedence) {
-        const sessionId = environment[harness].sessionId;
-        if (sessionId)
-            return { harness, sessionId };
-    }
-    return undefined;
+    return inspect(env);
 }

package/dist/mcp-server/pr-agent.mjs

@@ -1,5 +1,5 @@
+import { HARNESS_SESSION_PRECEDENCE } from 'agent-blackboard';
 import { inspectHarnessEnvironment } from "../agent-harness-identity/index.mjs";
-const PRECEDENCE = ['codex', 'claude', 'cursor', 'grok'];
 /**
  * The harness that launched this server, from the launch environment first and the MCP client's
  * `initialize` `clientInfo.name` second. Neither comes from a tool argument.
@@ -12,11 +12,11 @@ export function deriveAgent(env, clientName) {
         cursor: found.cursor.agentMarker || Boolean(found.cursor.sessionId),
         grok: found.grok.agentMarker || found.grok.hookEvent || Boolean(found.grok.sessionId),
     };
-    const fromEnv = PRECEDENCE.find((id) => present[id]);
+    const fromEnv = HARNESS_SESSION_PRECEDENCE.find((id) => present[id]);
     if (fromEnv !== undefined)
         return fromEnv;
     const name = clientName?.toLowerCase() ?? '';
-    return PRECEDENCE.find((id) => name.includes(id));
+    return HARNESS_SESSION_PRECEDENCE.find((id) => name.includes(id));
 }
 /**
  * The text of the `Agent:` line before the session. The agent is the derived harness; a caller

package/dist/retrospective-transcript/as-array.d.mts

@@ -0,0 +1 @@
+export declare function asArray(value: unknown): unknown[];

package/dist/retrospective-transcript/as-array.mjs

@@ -0,0 +1,3 @@
+export function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}

package/dist/retrospective-transcript/command-prefix.d.mts

@@ -0,0 +1 @@
+export declare function normalizeCommandPrefix(command: string): string;

package/dist/retrospective-transcript/command-prefix.mjs

@@ -0,0 +1,124 @@
+import { isPackageRunner, splitCommandSegments } from "./command-segments.mjs";
+// A real command/subcommand token (binary name, git subcommand, short flag, script
+// name) is always well under this length. A token that exceeds it isn't a command
+// token at all — it's payload that got tokenized as one word because it had no
+// internal whitespace (a `VAR={...json...}` assignment, a giant quoted printf arg).
+// Such tokens are replaced with a redaction marker rather than truncated: truncation
+// still leaks a prefix of whatever the token contains (a secret can sit at the front,
+// e.g. "AWS_SECRET_ACCESS_KEY=AKIA..."), while a full-token redaction leaks nothing
+// regardless of where sensitive content falls inside it. This intentionally also
+// redacts long-but-benign tokens (e.g. a `cd /very/long/worktree/path` argument) —
+// for a privacy boundary, over-redacting a legitimate token is the safe failure mode.
+const MAX_COMMAND_TOKEN_LENGTH = 40;
+const REDACTED_TOKEN = '…';
+function redactOverlongToken(token) {
+    return token.length > MAX_COMMAND_TOKEN_LENGTH ? REDACTED_TOKEN : token;
+}
+const ENV_ASSIGNMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*=/;
+// A segment's real command starts after any leading `VAR=value` assignments (e.g.
+// "CI=1 pnpm exec vitest", "GIT_EDITOR=true git rebase --continue" — both real
+// patterns used in real agent sessions). Without stripping these, the
+// env-var token itself gets normalized as if it were the command, so "CI=1 pnpm exec
+// vitest" would classify as prefix "CI=1 pnpm" instead of "pnpm exec vitest". Only
+// strips when a token remains afterward — a segment that is *entirely*
+// assignment-shaped tokens (e.g. a lone `OLD_POLICY_JSON={...}` token with no
+// whitespace) has no command to recover, and is left alone so it still falls through
+// to the general redaction path below instead of normalizing to an empty prefix.
+function stripEnvPrefix(segment) {
+    const index = segment.findIndex((token) => !ENV_ASSIGNMENT_PATTERN.test(token));
+    return index === -1 ? segment : segment.slice(index);
+}
+// Git global options precede the real subcommand — "git -C <path> status" and
+// "git status" are the same command family for policy-matching purposes (`git -h`
+// documents `git [-C <path>] [-c <name>=<value>] ... <command> [<args>]`). `-C`/`-c`
+// take a separate-token argument; `--git-dir=<path>`-style options fold their argument
+// into one `=`-joined token; the rest take no argument at all. Skipping them keeps the
+// normalized prefix on the subcommand instead of stalling on the option — without this,
+// e.g. `git -C <worktree> status` normalizes to "git -C" and reports as an uncovered
+// escalation/block candidate under the wrong prefix, even though `git status` is
+// already covered by an existing narrow allow rule.
+const GIT_GLOBAL_OPTIONS_WITH_ARG = new Set(['-C', '-c']);
+const GIT_GLOBAL_OPTIONS_NO_ARG = new Set([
+    '-v',
+    '--version',
+    '-h',
+    '--help',
+    '--exec-path',
+    '--html-path',
+    '--man-path',
+    '--info-path',
+    '-p',
+    '--paginate',
+    '-P',
+    '--no-pager',
+    '--no-replace-objects',
+    '--bare',
+]);
+const GIT_GLOBAL_OPTION_WITH_INLINE_ARG = /^--[a-z-]+=/;
+function stripGitGlobalOptions(tokens) {
+    let index = 0;
+    while (index < tokens.length) {
+        const token = tokens[index];
+        if (GIT_GLOBAL_OPTIONS_WITH_ARG.has(token))
+            index += 2;
+        else if (GIT_GLOBAL_OPTIONS_NO_ARG.has(token) || GIT_GLOBAL_OPTION_WITH_INLINE_ARG.test(token))
+            index += 1;
+        else
+            break;
+    }
+    return tokens.slice(index);
+}
+// Normalizes a segment to "<leading token> <first subcommand>" (e.g. "git status",
+// "gh pr", or just "cat" when there's no second token), with one exception that goes
+// one token deeper because a permissions file may distinguish at that depth:
+// package runners — "pnpm run build" vs "pnpm exec build" are different
+// permission entries, so the run/exec target must
+// stay out of the generic two-token rule.
+function normalizeSegment(segment) {
+    const [first, ...rest] = segment;
+    if (!first)
+        return '';
+    // A segment that is only assignments (stripEnvPrefix left it intact) has no command;
+    // its value may be a secret of any length, so always redact it.
+    if (ENV_ASSIGNMENT_PATTERN.test(first))
+        return REDACTED_TOKEN;
+    if (isPackageRunner(first) && (rest[0] === 'run' || rest[0] === 'exec') && rest[1]) {
+        return `${redactOverlongToken(first)} ${rest[0]} ${redactOverlongToken(rest[1])}`;
+    }
+    const effectiveRest = first === 'git' ? stripGitGlobalOptions(rest) : rest;
+    return effectiveRest[0]
+        ? `${redactOverlongToken(first)} ${redactOverlongToken(effectiveRest[0])}`
+        : redactOverlongToken(first);
+}
+// A leading "cd <path> && ..." (or "cd <path>; ...") prelude is not itself the
+// actionable command — it's a workdir change common in Bash sessions with no separate
+// cwd param. Without skipping it, "cd /repo && pnpm install" would normalize to "cd
+// /repo" and both miss existing pnpm policy coverage and leak a checkout path into
+// non-raw retro output. Only a *leading run* of cd segments is skipped — a bare `cd
+// /repo` with nothing after it has no other segment to fall back to, so it still
+// normalizes as-is.
+function skipLeadingCdSegments(segments) {
+    let index = 0;
+    while (index < segments.length - 1 && stripEnvPrefix(segments[index])[0] === 'cd')
+        index++;
+    return segments.slice(index);
+}
+// Produces a classification key for a raw shell command, for comparison against the
+// prefix lists in a consumer permissions file (excluded commands, allow,
+// and deny lists). This is a privacy
+// boundary: callers building non---raw report output must emit only this normalized
+// prefix, never the raw `command` string.
+//
+// Only the first non-cd segment of a compound command (`git status && git push`) is
+// normalized — this is a rough per-command categorization tool, not a full command
+// parser, so a compound command is bucketed by its first actionable part.
+//
+// The leading token is preserved as-is (no basename stripping for a path-qualified
+// binary like "/usr/bin/git"):
+// permissions files may also list literal relative-path scripts (e.g. "./scripts/run")
+// that must not be collapsed to a basename.
+export function normalizeCommandPrefix(command) {
+    const segments = skipLeadingCdSegments(splitCommandSegments(command));
+    const segment = stripEnvPrefix(segments[0] ?? []);
+    return normalizeSegment(segment);
+}

package/dist/retrospective-transcript/command-segments.d.mts

@@ -0,0 +1,2 @@
+export declare function splitCommandSegments(command: string): string[][];
+export declare function isPackageRunner(word: string | undefined): boolean;

package/dist/retrospective-transcript/command-segments.mjs

@@ -0,0 +1,54 @@
+// Commands are matched by command position, not by scanning for words anywhere in
+// the string. The string is split into segments on unquoted `;`, `&`, `|` and
+// newlines (so `git push;gh pr view` splits even with no surrounding whitespace).
+// Quoted spans, including any whitespace inside them, are grouped into a single
+// word, mirroring real shell tokenization.
+export function splitCommandSegments(command) {
+    const segments = [];
+    let current = [];
+    let word = '';
+    let quote = null;
+    const flushWord = () => {
+        if (word) {
+            current.push(word);
+            word = '';
+        }
+    };
+    const flushSegment = () => {
+        flushWord();
+        if (current.length) {
+            segments.push(current);
+            current = [];
+        }
+    };
+    for (const char of command) {
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            else
+                word += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === ';' || char === '&' || char === '|' || char === '\n' || char === '\r') {
+            flushSegment();
+            continue;
+        }
+        if (/\s/.test(char)) {
+            flushWord();
+            continue;
+        }
+        word += char;
+    }
+    flushSegment();
+    return segments;
+}
+const PACKAGE_RUNNERS = ['npx', 'pnpm', 'pnpx', 'yarn'];
+export function isPackageRunner(word) {
+    if (!word)
+        return false;
+    return PACKAGE_RUNNERS.some((runner) => word === runner || word.endsWith(`/${runner}`));
+}

package/dist/retrospective-transcript/index.d.mts

@@ -5,6 +5,11 @@ export { codexChildren, codexIdentity } from './codex.mts';
 export { formatTranscriptFacts, formatUnavailable } from './format.mts';
 export type { ResolveOptions } from './resolve-transcript-file.mts';
 export { resolveTranscriptFile } from './resolve-transcript-file.mts';
+export { asRecord } from './shared.mts';
+export { asArray } from './as-array.mts';
+export { normalizeCommandPrefix } from './command-prefix.mts';
+export { isPackageRunner, splitCommandSegments } from './command-segments.mts';
+export { DEFAULT_MAX_RECORD_BYTES, openTranscriptLines } from './transcript-lines.mts';
 export type RetrospectiveTranscriptReport = {
     markdown: string;
     coverage: 'complete' | 'partial' | 'unavailable';

package/dist/retrospective-transcript/index.mjs

@@ -11,6 +11,11 @@ import { emptyFacts, hasMalformedInteriorRecord, parseLines, } from "./shared.mj
 export { codexChildren, codexIdentity } from "./codex.mjs";
 export { formatTranscriptFacts, formatUnavailable } from "./format.mjs";
 export { resolveTranscriptFile } from "./resolve-transcript-file.mjs";
+export { asRecord } from "./shared.mjs";
+export { asArray } from "./as-array.mjs";
+export { normalizeCommandPrefix } from "./command-prefix.mjs";
+export { isPackageRunner, splitCommandSegments } from "./command-segments.mjs";
+export { DEFAULT_MAX_RECORD_BYTES, openTranscriptLines } from "./transcript-lines.mjs";
 const MALFORMED_INTERIOR = 'malformed interior transcript record';
 function partialCapture(lines) {
     return parseLines(lines).length !== lines.filter((line) => line.trim()).length;

package/dist/retrospective-transcript/resolve-transcript-file.d.mts

@@ -15,5 +15,15 @@ type TranscriptResolution = {
     error: string;
 };
 export declare function globFrom(root: string, pattern: string): string[];
+/**
+ * Canonical transcript resolution for consumers.
+ *
+ * - Session ids are validated as UUIDs and lowercased (`invalid session id format` otherwise).
+ * - Roots honor `CODEX_HOME`, `CLAUDE_CONFIG_DIR` and `GROK_HOME` from `options.env`
+ *   (default `process.env`), unless an explicit `*SessionsDir`/`projectsDir` is given.
+ * - Returns `{ error }` when more than one transcript matches a session, rather than
+ *   picking the first match, and when none matches.
+ * - An explicit `jsonlPath` skips discovery.
+ */
 export declare function resolveTranscriptFile(options: ResolveOptions): TranscriptResolution;
 export {};

package/dist/retrospective-transcript/resolve-transcript-file.mjs

@@ -7,6 +7,16 @@ export const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9
 export function globFrom(root, pattern) {
     return globSync(pattern, { cwd: root }).map((path) => join(root, path));
 }
+/**
+ * Canonical transcript resolution for consumers.
+ *
+ * - Session ids are validated as UUIDs and lowercased (`invalid session id format` otherwise).
+ * - Roots honor `CODEX_HOME`, `CLAUDE_CONFIG_DIR` and `GROK_HOME` from `options.env`
+ *   (default `process.env`), unless an explicit `*SessionsDir`/`projectsDir` is given.
+ * - Returns `{ error }` when more than one transcript matches a session, rather than
+ *   picking the first match, and when none matches.
+ * - An explicit `jsonlPath` skips discovery.
+ */
 export function resolveTranscriptFile(options) {
     if (options.sessionId && !SESSION_ID.test(options.sessionId))
         return { error: 'invalid session id format' };

package/dist/retrospective-transcript/transcript-lines.d.mts

@@ -0,0 +1,22 @@
+export declare const DEFAULT_MAX_RECORD_BYTES: number;
+export type OpenTranscriptLinesOptions = {
+    /** Largest allowed record (one line, excluding its newline) in bytes. Defaults to 2 MiB. */
+    maxRecordBytes?: number;
+};
+export type OpenTranscriptLinesResult = {
+    lines: AsyncIterable<string>;
+} | {
+    error: string;
+};
+/**
+ * Opens a transcript for streaming, one line at a time, with `String.split('\n')`
+ * semantics (a trailing newline yields a final empty line, `\r` is preserved).
+ *
+ * A `maxRecordBytes` that is not a non-negative safe integer rejects with `RangeError`.
+ * An open failure resolves to `{ error }`. An oversized record is NOT skipped or
+ * reported inline: the returned async iterable throws
+ * `transcript record exceeds <maxRecordBytes> byte limit` when it reaches the
+ * record, ending iteration, and the underlying stream is destroyed. Lines yielded
+ * before the oversized record remain valid.
+ */
+export declare function openTranscriptLines(path: string, { maxRecordBytes }?: OpenTranscriptLinesOptions): Promise<OpenTranscriptLinesResult>;

package/dist/retrospective-transcript/transcript-lines.mjs

@@ -0,0 +1,74 @@
+import { createReadStream } from 'node:fs';
+export const DEFAULT_MAX_RECORD_BYTES = 2 * 1024 * 1024;
+/**
+ * Opens a transcript for streaming, one line at a time, with `String.split('\n')`
+ * semantics (a trailing newline yields a final empty line, `\r` is preserved).
+ *
+ * A `maxRecordBytes` that is not a non-negative safe integer rejects with `RangeError`.
+ * An open failure resolves to `{ error }`. An oversized record is NOT skipped or
+ * reported inline: the returned async iterable throws
+ * `transcript record exceeds <maxRecordBytes> byte limit` when it reaches the
+ * record, ending iteration, and the underlying stream is destroyed. Lines yielded
+ * before the oversized record remain valid.
+ */
+export async function openTranscriptLines(path, { maxRecordBytes = DEFAULT_MAX_RECORD_BYTES } = {}) {
+    if (!Number.isSafeInteger(maxRecordBytes) || maxRecordBytes < 0)
+        throw new RangeError('maxRecordBytes must be a non-negative integer');
+    const stream = createReadStream(path);
+    try {
+        await new Promise((resolve, reject) => {
+            stream.once('open', () => resolve());
+            stream.once('error', reject);
+        });
+        const lines = streamTranscriptLines(stream, maxRecordBytes);
+        const release = lines.return.bind(lines);
+        // The file is already open, so cancelling before the first next() must still close it;
+        // an unstarted generator never reaches its own finally block.
+        lines.return = (value) => {
+            stream.destroy();
+            return release(value);
+        };
+        return { lines };
+    }
+    catch (err) {
+        stream.destroy();
+        return { error: err.message };
+    }
+}
+async function* streamTranscriptLines(stream, maxRecordBytes) {
+    const pending = [];
+    let pendingBytes = 0;
+    const tooLarge = () => new Error(`transcript record exceeds ${maxRecordBytes} byte limit`);
+    const line = (tail) => {
+        const bytes = pendingBytes + (tail?.byteLength ?? 0);
+        if (bytes > maxRecordBytes)
+            throw tooLarge();
+        const value = Buffer.concat(tail ? [...pending, tail] : pending, bytes).toString('utf8');
+        pending.length = 0;
+        pendingBytes = 0;
+        return value;
+    };
+    try {
+        for await (const chunk of stream) {
+            let start = 0;
+            for (;;) {
+                const newline = chunk.indexOf(10, start);
+                if (newline === -1)
+                    break;
+                yield line(chunk.subarray(start, newline));
+                start = newline + 1;
+            }
+            if (start < chunk.byteLength) {
+                const tail = chunk.subarray(start);
+                pendingBytes += tail.byteLength;
+                if (pendingBytes > maxRecordBytes)
+                    throw tooLarge();
+                pending.push(tail);
+            }
+        }
+        yield line();
+    }
+    finally {
+        stream.destroy();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -375,6 +375,7 @@
     "@types/mdast": "4.0.4",
     "@types/unist": "3.0.3",
     "@typescript-eslint/parser": "^8.71.1",
+    "agent-blackboard": "^0.7.0",
     "csv-parse": "7.0.3",
     "csv-stringify": "6.9.0",
     "dockerfile-ast": "0.7.1",
@@ -390,22 +391,17 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "@types/picomatch": "^4.0.3",
     "@types/spdx-expression-parse": "4.0.0",
-    "agent-blackboard": "^0.6.1",
     "no-mistakes": "0.83.0",
     "smol-toml": "1.9.1",
     "typescript5": "npm:typescript@5.9.3"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
-    "agent-blackboard": "^0.6.1",
     "no-mistakes": "*",
     "typescript": ">=5",
     "vitest": ">=5"
   },
   "peerDependenciesMeta": {
-    "agent-blackboard": {
-      "optional": true
-    },
     "@modelcontextprotocol/sdk": {
       "optional": true
     },