vouchington-tooling 0.46.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/mcp-server/pr-body.d.mts

@@ -12,9 +12,9 @@ export type PullRequestProvenance = {
 };
 /**
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
- * provenance lines. With `noSourceIssue` the Related issues section holds `noSourceStatement`
- * (default {@link defaultNoSourceStatement}) instead of `- None`. Pure; the caller supplies the
- * device and worktree facts.
+ * provenance lines. With `noSourceIssue` the Related issues section ends with `noSourceStatement`
+ * (default {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure;
+ * the caller supplies the device and worktree facts.
  */
 export declare function renderPullRequestBody(input: PullRequestInput, provenance: PullRequestProvenance, noSourceStatement?: string): string;
 /**

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

@@ -1,7 +1,9 @@
 import { basename } from 'node:path';
+import { formatReferenceKey } from "../gh-cli/closing-refs.mjs";
 function relatedLine(issue) {
     const verb = issue.relation === 'closes' ? 'Closes' : 'Refs';
-    return `- ${verb} #${issue.number} — ${issue.reason}`;
+    const [owner, repo] = issue.repository?.split('/') ?? [];
+    return `- ${verb} ${formatReferenceKey({ number: issue.number, owner, repo })} — ${issue.reason}`;
 }
 /** The default no-source statement; a policy `renderNoSourceIssue` export may replace it. */
 function defaultNoSourceStatement(reason) {
@@ -9,18 +11,16 @@ function defaultNoSourceStatement(reason) {
 }
 /**
  * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
- * provenance lines. With `noSourceIssue` the Related issues section holds `noSourceStatement`
- * (default {@link defaultNoSourceStatement}) instead of `- None`. Pure; the caller supplies the
- * device and worktree facts.
+ * provenance lines. With `noSourceIssue` the Related issues section ends with `noSourceStatement`
+ * (default {@link defaultNoSourceStatement}), after any `Refs` lines, instead of `- None`. Pure;
+ * the caller supplies the device and worktree facts.
  */
 export function renderPullRequestBody(input, provenance, noSourceStatement) {
-    const related = input.relatedIssues.length
-        ? input.relatedIssues.map(relatedLine)
-        : [
-            input.noSourceIssue === undefined
-                ? '- None'
-                : (noSourceStatement ?? defaultNoSourceStatement(input.noSourceIssue.reason)),
-        ];
+    const related = input.relatedIssues.map(relatedLine);
+    if (input.noSourceIssue !== undefined)
+        related.push(noSourceStatement ?? defaultNoSourceStatement(input.noSourceIssue.reason));
+    if (!related.length)
+        related.push('- None');
     return [
         '## Summary',
         '',

package/dist/mcp-server/pr-input.d.mts

@@ -4,13 +4,15 @@ export type RelatedIssue = {
     number: number;
     relation: 'closes' | 'refs';
     reason: string;
+    /** `owner/name` of a cross-repository issue (rendered lowercase); absent for this repository. */
+    repository?: string;
 };
 export type PullRequestInput = {
     title: string;
     summary: string;
     impact: string;
     relatedIssues: RelatedIssue[];
-    /** Set instead of relatedIssues when the pull request has no source issue. */
+    /** Declares no source issue; relatedIssues beside it must all be `refs`. */
     noSourceIssue?: {
         reason: string;
     };

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

@@ -1,3 +1,4 @@
+import { hasClosingIssueReference } from "../gh-cli/closing-refs.mjs";
 import { optionalString, rejectUnknown, requireObject, requiredChoice, requiredString, requiredStringArray, } from "./args.mjs";
 import { trustedMode } from "./pr-mode.mjs";
 const PR_MODES = ['interactive', 'autonomous'];
@@ -9,17 +10,30 @@ export function positiveInteger(value, label) {
         throw new Error(`${label} must be a positive integer`);
     return value;
 }
+// The owner is a GitHub login: alphanumerics and single hyphens, at most 39 characters.
+const REPOSITORY_RE = /^(?=[^/]{1,39}\/)[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*\/[\w.-]+$/;
+function readRepository(issue, label) {
+    if (issue.repository === undefined)
+        return undefined;
+    // Not lowercased here: redaction runs on this value first, and rendering lowercases it.
+    const value = singleLine(issue, 'repository');
+    if (!REPOSITORY_RE.test(value))
+        throw new Error(`${label} must be a single owner/name`);
+    return value;
+}
 function readRelatedIssues(args) {
     const value = args.relatedIssues;
     if (!Array.isArray(value))
         throw new Error('relatedIssues is required and must be an array');
     return value.map((item, index) => {
         const issue = requireObject(item);
-        rejectUnknown(issue, ['number', 'relation', 'reason']);
+        rejectUnknown(issue, ['number', 'relation', 'reason', 'repository']);
+        const repository = readRepository(issue, `relatedIssues[${index}].repository`);
         return {
             number: positiveInteger(issue.number, `relatedIssues[${index}].number`),
             relation: requiredChoice(issue, 'relation', RELATIONS),
             reason: requiredString(issue, 'reason'),
+            ...(repository === undefined ? {} : { repository }),
         };
     });
 }
@@ -28,8 +42,12 @@ function readNoSourceIssue(args, related) {
         return undefined;
     const value = requireObject(args.noSourceIssue);
     rejectUnknown(value, ['reason']);
-    if (related.length)
-        throw new Error('noSourceIssue and a non-empty relatedIssues are mutually exclusive');
+    if (related.some((issue) => issue.relation === 'closes'))
+        throw new Error('noSourceIssue cannot be combined with a relatedIssues entry that closes');
+    related.forEach((issue, index) => {
+        if (hasClosingIssueReference(issue.reason))
+            throw new Error(`relatedIssues[${index}].reason must not contain a closing reference beside noSourceIssue`);
+    });
     return { reason: singleLine(value, 'reason') };
 }
 function readDetails(args) {

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

@@ -12,14 +12,20 @@ const FIELDS = {
     impact: text('Who or what is affected, as markdown.'),
     relatedIssues: {
         type: 'array',
-        description: 'Issues this pull request closes or refs. Empty when it has none; with no source issue ' +
-            'at all, give noSourceIssue as well (it is rejected beside a non-empty list).',
+        description: 'Issues this pull request closes or refs. Empty when it has none; with no source issue, ' +
+            'give noSourceIssue as well (beside a non-empty list every entry must be refs).',
         items: {
             type: 'object',
             properties: {
                 number: { type: 'integer', minimum: 1 },
                 relation: { enum: ['closes', 'refs'] },
                 reason: text('Why the issue is related.'),
+                repository: {
+                    type: 'string',
+                    pattern: '^(?=[^/]{1,39}/)[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*/[\\w.-]+$',
+                    description: 'Optional owner/name (lowercased) of the issue repository, rendered as ' +
+                        'owner/name#N; omit for an issue in this repository. Allowed for closes and refs.',
+                },
             },
             required: ['number', 'relation', 'reason'],
             additionalProperties: false,
@@ -27,9 +33,10 @@ const FIELDS = {
     },
     noSourceIssue: {
         type: 'object',
-        description: 'Declares a pull request with no source issue, mutually exclusive with a non-empty ' +
-            'relatedIssues. Rendered inside Related issues (the policy may supply the wording) and ' +
-            'passed to the policy, which may allow it only in interactive mode.',
+        description: 'Declares a pull request with no source issue; rejected beside a closes relatedIssues ' +
+            'entry, allowed beside refs-only ones. Rendered inside Related issues after any Refs ' +
+            'lines (the policy may supply the wording) and passed to the policy, which may allow it ' +
+            'only in interactive mode.',
         properties: { reason: text('Single-line reason there is no source issue.') },
         required: ['reason'],
         additionalProperties: false,

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/docs/mcp-server.md

@@ -286,8 +286,10 @@ shape is an error, never a pass.
 retrospective tools. All three take `sessionId` (required) and `worktree` (optional), need a server
 launched inside a repository worktree (they run the checkout policy), and share this structured
 input: `title` (single line, at most 256 characters), `summary`, `impact`, `relatedIssues`
-(`[{ number, relation: "closes" | "refs", reason }]`, may be empty), optional `noSourceIssue`
-(`{ reason }`, see below), `details` (string array), `base` (default `main`), optional `agent`, optional
+(`[{ number, relation: "closes" | "refs", reason, repository? }]`, may be empty; the optional
+`repository` is a single `owner/name` and renders the line as lowercase `owner/name#N`), optional
+`noSourceIssue` (`{ reason }`, see below), `details` (string array), `base` (default `main`),
+optional `agent`, optional
 `model`, optional `mode` (`interactive` | `autonomous`) and `workspaceSetup`. `pr_update` also
 requires `pr`; `pr_validate` accepts an optional `pr`.
 
@@ -319,9 +321,11 @@ which may keep sending it.
 
 ### Pull requests with no source issue
 
-Pass `noSourceIssue: { reason }` (a single line) with an empty `relatedIssues`; a non-empty
-`relatedIssues` beside it is rejected. The Related issues section then holds the generic statement
-`- No source issue — <reason>` instead of `- None`. A policy may replace the statement by
+Pass `noSourceIssue: { reason }` (a single line) with an empty `relatedIssues`, or with a
+`relatedIssues` whose every entry is `refs`; a `closes` entry beside it is rejected. The Related
+issues section then holds the generic statement `- No source issue — <reason>` instead of `- None`,
+preceded by the `- Refs … — <reason>` lines when there are any (the statement is always the last
+line). A policy may replace the statement by
 exporting `renderNoSourceIssue({ reason })`, returning a non-empty string (30 s). The field also
 reaches `validatePullRequest` (with the trusted `mode`, so the policy can apply an interactive-only
 rule) and `pullRequestDefaults`.
@@ -339,8 +343,9 @@ rule) and `pullRequestDefaults`.
 
 ## Related issues
 
-- Closes #N — <reason>      (or "Refs #N"; "- None" when empty;
-                             "- No source issue — <reason>" for noSourceIssue)
+- Closes #N — <reason>      (or "Refs #N"; owner/name#N with `repository`; "- None" when empty;
+                             "- No source issue — <reason>" for noSourceIssue, rendered
+                             after any Refs lines)
 
 ## Details
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.46.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
     },