@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/core/release-notes/parser.js

@@ -0,0 +1,241 @@
+/**
+ * Keep-a-Changelog parser — .
+ *
+ * Parses a `CHANGELOG.md` written в the Keep-a-Changelog v1.1 layout
+ * (https://keepachangelog.com) into an ordered list of version
+ * sections. The parser is intentionally minimal — it understands the
+ * `## [<version>] - <date>` header marker and the section body up к
+ * the next header, and ignores every other Markdown construct (links,
+ * footnotes, sub-sub-headers). That is enough к drive the
+ * `pugi release-notes` diff between last-seen and current.
+ *
+ * # Module contract
+ *
+ *  - Pure function. Takes the raw CHANGELOG text + returns parsed
+ *    sections. Zero IO; the file read happens at the call site so the
+ *    spec can pin fixtures without touching disk.
+ *
+ *  - Header grammar: `## [<version>] - <YYYY-MM-DD>`. The leading
+ *    `## ` is required (h2). The version is everything between the
+ *    square brackets — semver-shaped strings are not validated
+ *    beyond non-emptiness so pre-release tags like `0.1.0-beta.21`
+ *    parse correctly. The date is captured verbatim; the comparator
+ *    does not parse it — version ordering is enough.
+ *
+ *  - Section body: every line from the header (exclusive) up к the
+ *    next `## [...] - ...` header (exclusive). Lines are joined
+ *    verbatim with `\n`; leading + trailing blank lines are trimmed
+ *    so the renderer can paste sections back-to-back without double
+ *    blank lines piling up.
+ *
+ *  - Pre-header content (the leading `# Changelog` + introduction
+ *    blurb) is discarded. The parser only surfaces version sections;
+ *    callers that want к render the introduction read the source
+ *    file directly.
+ *
+ *  - Sections appear в the order they are written in the file. The
+ *    Keep-a-Changelog convention is newest-first; the parser does
+ *    NOT re-sort. The slicing helpers (`sliceVersionsBetween`) trust
+ *    the input order so a malformed CHANGELOG with shuffled
+ *    versions produces a deterministic — if surprising — diff
+ *    instead of silently swallowing entries.
+ *
+ *  - Semver comparison (`compareSemver`) handles the canonical
+ *    `MAJOR.MINOR.PATCH[-PRERELEASE]` shape. The pre-release tail
+ *    is compared lexicographically by dot-separated identifier per
+ *    semver §11. Unknown / malformed input compares lower than any
+ *    valid semver so an accidental `unknown` last-seen marker
+ *    never blocks the operator from seeing new notes.
+ */
+const SECTION_HEADER_RE = /^##\s+\[([^\]]+)\](?:\s*-\s*(.+))?\s*$/u;
+/**
+ * Parse the raw `CHANGELOG.md` text into ordered version sections.
+ *
+ * Returns sections in the same order they appear in the source. The
+ * Keep-a-Changelog convention is newest-first; the parser does not
+ * re-sort.
+ */
+export function parseChangelog(raw) {
+    const lines = raw.split(/\r?\n/u);
+    const sections = [];
+    let current = null;
+    const flush = () => {
+        if (!current)
+            return;
+        sections.push({
+            version: current.version,
+            date: current.date,
+            body: trimBlankEdges(current.lines).join('\n'),
+        });
+        current = null;
+    };
+    for (const line of lines) {
+        const match = SECTION_HEADER_RE.exec(line);
+        if (match) {
+            flush();
+            const version = (match[1] ?? '').trim();
+            const date = (match[2] ?? '').trim();
+            if (version.length === 0) {
+                // Malformed `## []` header — skip entirely instead of
+                // emitting a zero-version row that would corrupt the diff.
+                continue;
+            }
+            current = { version, date, lines: [] };
+            continue;
+        }
+        if (current) {
+            current.lines.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+/**
+ * Slice the section list к those strictly newer than `lastSeen` and
+ * up к (and including) `current`. Both bounds are matched on the
+ * verbatim version string — the comparator runs on every section к
+ * decide membership.
+ *
+ * Semantics:
+ *
+ *  - If `lastSeen` is null OR empty OR matches no section, every
+ *    section ≤ current is returned. This is the first-run path —
+ *    the operator has never run the command before, so the entire
+ *    bundled changelog is fair game.
+ *
+ *  - If `lastSeen` equals `current`, the empty array is returned.
+ *    The caller renders the "no new release notes" copy.
+ *
+ *  - If `lastSeen` is newer than `current`, the empty array is
+ *    returned. This is the dev-build path — operators running a
+ *    local build of `0.1.0-beta.30` against a registry that
+ *    publishes `0.1.0-beta.22` would otherwise see the stale
+ *    bundled notes; the caller still surfaces the same no-op copy.
+ *
+ *  - Otherwise: sections strictly newer than `lastSeen` and ≤
+ *    `current`, in the source order (newest-first by convention).
+ *
+ * The function is pure — no IO, no clock — so the spec can pin every
+ * branch with hand-rolled fixtures.
+ */
+export function sliceVersionsBetween(sections, lastSeen, current) {
+    if (sections.length === 0)
+        return [];
+    // Treat а blank / sentinel last-seen as "never seen".
+    const lastSeenValue = typeof lastSeen === 'string' && lastSeen.trim().length > 0 && lastSeen !== 'none'
+        ? lastSeen.trim()
+        : null;
+    // Dev-build path: operator's last-seen marker is strictly newer than
+    // the installed CLI version. This happens when running а local build
+    // older than the registry, or when the operator manually edited the
+    // marker. Either way, return the empty array — re-rendering the
+    // bundled notes would be misleading. The renderer surfaces the same
+    // "no new release notes" copy as the up-to-date branch.
+    if (lastSeenValue !== null && compareSemver(lastSeenValue, current) > 0) {
+        return [];
+    }
+    // Diff path: surface sections strictly newer than the marker and ≤
+    // current. The comparator drives every section — а marker that does
+    // not appear in the bundled changelog (operator on а stale build,
+    // hand-edited marker, version no longer published) still bisects
+    // correctly because every comparison runs against the marker value
+    // directly, not the matching-section guard.
+    const out = [];
+    for (const section of sections) {
+        // Anything newer than current is а future entry that should not
+        // surface until the operator actually upgrades — guards against а
+        // dev build of CHANGELOG.md leaking unreleased notes к а customer
+        // install.
+        if (compareSemver(section.version, current) > 0)
+            continue;
+        if (lastSeenValue !== null && compareSemver(section.version, lastSeenValue) <= 0) {
+            continue;
+        }
+        out.push(section);
+    }
+    return out;
+}
+/**
+ * Semver comparator. Returns a negative number when `a < b`, zero
+ * when equal, and a positive number when `a > b`. Pre-release tags
+ * compare lexicographically by dot-separated identifier per semver §11.
+ *
+ * Unknown / malformed input compares lower than any valid semver so
+ * an accidental sentinel like `unknown` or `none` never accidentally
+ * blocks the diff from surfacing newer entries.
+ */
+export function compareSemver(a, b) {
+    const left = parseSemver(a);
+    const right = parseSemver(b);
+    if (!left && !right)
+        return 0;
+    if (!left)
+        return -1;
+    if (!right)
+        return 1;
+    for (let i = 0; i < 3; i += 1) {
+        const cmp = (left.core[i] ?? 0) - (right.core[i] ?? 0);
+        if (cmp !== 0)
+            return cmp;
+    }
+    // A version without a pre-release tag is newer than the same core
+    // with a pre-release tag (per semver §11: 1.0.0 > 1.0.0-rc).
+    if (left.pre.length === 0 && right.pre.length === 0)
+        return 0;
+    if (left.pre.length === 0)
+        return 1;
+    if (right.pre.length === 0)
+        return -1;
+    const len = Math.max(left.pre.length, right.pre.length);
+    for (let i = 0; i < len; i += 1) {
+        const li = left.pre[i];
+        const ri = right.pre[i];
+        if (li === undefined)
+            return -1;
+        if (ri === undefined)
+            return 1;
+        const ln = Number.parseInt(li, 10);
+        const rn = Number.parseInt(ri, 10);
+        const liNumeric = Number.isFinite(ln) && String(ln) === li;
+        const riNumeric = Number.isFinite(rn) && String(rn) === ri;
+        if (liNumeric && riNumeric) {
+            if (ln !== rn)
+                return ln - rn;
+            continue;
+        }
+        if (liNumeric)
+            return -1; // numeric < alphanumeric per §11
+        if (riNumeric)
+            return 1;
+        if (li < ri)
+            return -1;
+        if (li > ri)
+            return 1;
+    }
+    return 0;
+}
+function parseSemver(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return null;
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/u.exec(trimmed);
+    if (!match)
+        return null;
+    const major = Number.parseInt(match[1] ?? '0', 10);
+    const minor = Number.parseInt(match[2] ?? '0', 10);
+    const patch = Number.parseInt(match[3] ?? '0', 10);
+    const pre = match[4] ? match[4].split('.') : [];
+    return { core: [major, minor, patch], pre };
+}
+function trimBlankEdges(lines) {
+    let start = 0;
+    let end = lines.length;
+    while (start < end && (lines[start] ?? '').trim().length === 0)
+        start += 1;
+    while (end > start && (lines[end - 1] ?? '').trim().length === 0)
+        end -= 1;
+    return lines.slice(start, end);
+}
+//# sourceMappingURL=parser.js.map

package/dist/core/release-notes/state.js

@@ -0,0 +1,116 @@
+/**
+ * `~/.pugi/.last-seen-version` state I/O — .
+ *
+ * The `pugi release-notes` command renders the diff between the
+ * version the operator last saw notes for and the currently
+ * installed CLI version. This module owns the on-disk marker that
+ * tracks the last-seen value.
+ *
+ * # Module contract
+ *
+ *  - File path: `<home>/.pugi/.last-seen-version`. The leading dot
+ *    keeps it out of casual `ls` output; the file is plain ASCII
+ *    (one line, the version string) so operators can edit it by
+ *    hand when reproducing scenarios. Missing parent dir is
+ *    created on write.
+ *
+ *  - Reads: missing file → null. Unreadable / blank file → null.
+ *    The caller treats null as "operator has never run the command"
+ *    and surfaces every bundled section. Read failures NEVER throw —
+ *    the command surface is informational and must keep working on
+ *    a read-only mount or a misconfigured permission bit.
+ *
+ *  - Writes: best-effort. EACCES / EROFS / ENOSPC log а warning к
+ *    the caller-supplied logger and return the failure code so the
+ *    command renderer can footer the output with "could not persist
+ *    last-seen — re-run will show the same notes". The command
+ *    itself stays exit 0 because the value of the render did not
+ *    depend on the write succeeding.
+ *
+ *  - The helpers are pure I/O wrappers — no clock, no random, no
+ *    env reads. Callers pass `home` explicitly so the spec can
+ *    pin a tmp dir without monkey-patching `os.homedir`.
+ */
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+/** Filename inside `<home>/.pugi/` that holds the last-seen marker. */
+export const LAST_SEEN_VERSION_FILE = '.last-seen-version';
+/**
+ * Resolve the absolute path of the last-seen marker file inside the
+ * passed home directory. Pure helper — no IO.
+ */
+export function lastSeenVersionPath(home) {
+    return resolve(home, '.pugi', LAST_SEEN_VERSION_FILE);
+}
+/**
+ * Read the last-seen marker. Returns null when the file is missing,
+ * unreadable, or empty. Never throws.
+ */
+export function readLastSeenVersion(home) {
+    const path = lastSeenVersionPath(home);
+    try {
+        if (!existsSync(path))
+            return null;
+        const raw = readFileSync(path, 'utf8').trim();
+        if (raw.length === 0)
+            return null;
+        return raw;
+    }
+    catch {
+        // Read-only mount, permission denied, race with another process
+        // unlinking the file — every read failure degrades к null so the
+        // command treats the operator as a first-time viewer instead of
+        // dropping out of the slash dispatcher with an unhandled error.
+        return null;
+    }
+}
+/**
+ * Persist the last-seen marker. Creates `<home>/.pugi/` if it does
+ * not exist. Returns a structured envelope describing success or the
+ * failure reason so the renderer can footer а warning when the write
+ * could not be made durable.
+ */
+export function writeLastSeenVersion(home, version) {
+    const path = lastSeenVersionPath(home);
+    try {
+        const dir = resolve(home, '.pugi');
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        // Trailing newline so `cat ~/.pugi/.last-seen-version` reads
+        // nicely in shells that do not auto-append one for the prompt.
+        writeFileSync(path, `${version}\n`, { encoding: 'utf8', mode: 0o600 });
+        return { status: 'ok', path };
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            path,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/**
+ * Clear the last-seen marker — used by `pugi release-notes --reset`
+ * so the operator can force the full bundled changelog к re-render.
+ * Returns `absent` when the marker did not exist, `cleared` on
+ * success, `failed` on permission errors.
+ */
+export function clearLastSeenVersion(home) {
+    const path = lastSeenVersionPath(home);
+    try {
+        if (!existsSync(path)) {
+            return { status: 'absent', path };
+        }
+        unlinkSync(path);
+        return { status: 'cleared', path };
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            path,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/core/repl/ask.js

@@ -1,23 +1,23 @@
 /**
- * Office-hours forcing questions + plan-review tag parser - Sprint α6.3.
+ * Office-hours forcing questions + plan-review tag parser - Sprint .
  *
- * Pugi's persona prompt teaches Mira to emit two structured XML envelopes
+ * Pugi's persona prompt teaches Pugi to emit two structured XML envelopes
  * when she would otherwise have to guess. Operator chat then pauses on a
  * modal until the operator answers, eliminating the "fabricate a default
- * silently" failure mode that Codex CLI, Claude Code, and Gemini CLI all
+ * silently" failure mode that peer CLI, the upstream tool, and Gemini CLI all
  * trip on with low-confidence intents.
  *
- *   <pugi-ask>
- *     <question>Which deployment target?</question>
- *     <option value="vercel"    label="Vercel"          desc="Static + edge"/>
- *     <option value="cloudflare" label="Cloudflare Pages" desc="Edge runtime"/>
- *   </pugi-ask>
+ *  <pugi-ask>
+ *    <question>Which deployment target?</question>
+ *    <option value="vercel"   label="Vercel"         desc="Static + edge"/>
+ *    <option value="cloudflare" label="Cloudflare Pages" desc="Edge runtime"/>
+ *  </pugi-ask>
  *
- *   <pugi-plan-review>
- *     <step>1. Edit src/foo.ts: add new export</step>
- *     <step>2. Write tests/foo.spec.ts: 8 test cases</step>
- *     <risk>Touches public API surface.</risk>
- *   </pugi-plan-review>
+ *  <pugi-plan-review>
+ *    <step>1. Edit src/foo.ts: add new export</step>
+ *    <step>2. Write tests/foo.spec.ts: 8 test cases</step>
+ *    <risk>Touches public API surface.</risk>
+ *  </pugi-plan-review>
  *
  * This module is a pure, framework-free parser. The session module imports
  * `extractAskTags()` / `extractPlanReviewTags()` and routes the typed
@@ -32,16 +32,16 @@
  * with a closed attribute set, so a bounded tokenizer is both safer and
  * smaller. Defence-in-depth choices:
  *
- *   - Reject raw `&` outside `&amp;` / `&lt;` / `&gt;` / `&quot;` /
- *     `&apos;` (entities are decoded; everything else is malformed).
- *   - Forbid nested ask-within-ask (would crash the modal stack).
- *   - Cap option count at 4 (Claude Code AskUserQuestion baseline).
- *   - Cap label / desc / question / step / risk at 80 chars (terminal
- *     rendering budget, also discourages prompt injection via huge
- *     payloads).
- *   - Reject CDATA, comments, processing instructions, DOCTYPE — none
- *     of those appear in the legal grammar.
- *   - Reject any attribute that is not in the per-tag allowlist.
+ *  - Reject raw `&` outside `&amp;` / `&lt;` / `&gt;` / `&quot;` /
+ *    `&apos;` (entities are decoded; everything else is malformed).
+ *  - Forbid nested ask-within-ask (would crash the modal stack).
+ *  - Cap option count at 4 (the upstream tool AskUserQuestion baseline).
+ *  - Cap label / desc / question / step / risk at 80 chars (terminal
+ *    rendering budget, also discourages prompt injection via huge
+ *    payloads).
+ *  - Reject CDATA, comments, processing instructions, DOCTYPE — none
+ *    of those appear in the legal grammar.
+ *  - Reject any attribute that is not in the per-tag allowlist.
  *
  * # Buffering across streaming chunks
  *
@@ -53,9 +53,9 @@
  * post-tag remainder. The same shape applies to `<pugi-plan-review>`.
  */
 /* ------------------------------------------------------------------ */
-/* Bounded constants                                                  */
+/* Bounded constants                                                 */
 /* ------------------------------------------------------------------ */
-/** Hard cap on options per `<pugi-ask>`. Claude Code AskUserQuestion uses 4. */
+/** Hard cap on options per `<pugi-ask>`. the upstream tool AskUserQuestion uses 4. */
 export const ASK_MAX_OPTIONS = 4;
 /** Hard cap on question / label / desc length. Terminal-row budget. */
 export const ASK_MAX_TEXT_LEN = 80;
@@ -68,7 +68,7 @@ export const PLAN_REVIEW_MAX_RISK_LEN = 240;
 /** Hard cap on the entire tag span. Long enough for 4 options + risk; defends against runaway payloads. */
 const TAG_MAX_SPAN_BYTES = 8 * 1024;
 /* ------------------------------------------------------------------ */
-/* Public extraction API                                              */
+/* Public extraction API                                             */
 /* ------------------------------------------------------------------ */
 /**
  * Find every well-formed `<pugi-ask>` in `body`. Malformed tags are
@@ -131,7 +131,7 @@ function extractTags(body, config) {
             // or completes mid-tag. The caller keeps the original buffer for
             // the next chunk merge via pendingOpenTag; if the turn ends with
             // the tag still open, the caller emits a system warning instead
-            // of surfacing the raw XML. Codex triple-review P2 (PR #375).
+            // of surfacing the raw XML. Codex triple-review P2 (PR).
             pendingOpenTag = true;
             cursor = body.length;
             break;
@@ -170,7 +170,7 @@ function extractTags(body, config) {
     };
 }
 /* ------------------------------------------------------------------ */
-/* `<pugi-ask>` inner parser                                          */
+/* `<pugi-ask>` inner parser                                         */
 /* ------------------------------------------------------------------ */
 function parseAskInner(inner, span) {
     // Reject CDATA, comments, processing instructions, DOCTYPE.
@@ -339,7 +339,7 @@ function parseAttrBlob(blob) {
     return result;
 }
 /* ------------------------------------------------------------------ */
-/* `<pugi-plan-review>` inner parser                                  */
+/* `<pugi-plan-review>` inner parser                                 */
 /* ------------------------------------------------------------------ */
 function parsePlanReviewInner(inner, span) {
     if (/<!--|<!\[|<\?|<!DOCTYPE/i.test(inner))
@@ -389,9 +389,9 @@ function extractStepTags(inner) {
 }
 /**
  * Optional single-child text. Returns:
- *   - `null` when the tag is absent (legal absence)
- *   - the trimmed body when exactly one occurrence is present
- *   - `undefined` to signal a malformed (rejected) state to the caller
+ *  - `null` when the tag is absent (legal absence)
+ *  - the trimmed body when exactly one occurrence is present
+ *  - `undefined` to signal a malformed (rejected) state to the caller
  */
 function extractOptionalChildText(inner, tagName, maxLen) {
     const open = `<${tagName}>`;
@@ -413,7 +413,7 @@ function extractOptionalChildText(inner, tagName, maxLen) {
     return decoded;
 }
 /* ------------------------------------------------------------------ */
-/* Entity decoding + amp safety                                       */
+/* Entity decoding + amp safety                                      */
 /* ------------------------------------------------------------------ */
 const ENTITY_MAP = Object.freeze({
     amp: '&',
@@ -437,7 +437,7 @@ function decodeEntities(input) {
  * Applied AFTER decodeEntities so an `&` escape cannot smuggle an ESC
  * byte through the entity layer.
  *
- * Claude triple-review P2 (PR #375).
+ * Claude triple-review P2 (PR).
  */
 function stripControlChars(input) {
     // eslint-disable-next-line no-control-regex -- deliberately matching control range
@@ -467,7 +467,7 @@ function containsRawAmpersand(input) {
     return false;
 }
 /* ------------------------------------------------------------------ */
-/* Signatures                                                         */
+/* Signatures                                                        */
 /* ------------------------------------------------------------------ */
 /**
  * Stable dedupe signature for an ask tag. The session keeps the most
@@ -488,7 +488,7 @@ function containsRawAmpersand(input) {
  * could share a signature with a local synthesiser even though the
  * computation diverged - dedupe would suppress the persona modal.
  *
- * Claude triple-review P1 (PR #375).
+ * Claude triple-review P1 (PR).
  */
 export function signatureForAsk(question, options) {
     const values = options.map((o) => o.value).sort().join('|');
@@ -501,7 +501,7 @@ export function signatureForAsk(question, options) {
  * `synthesiseLocalPlanReview` in cli.ts must produce identical
  * signatures to parser-extracted tags for the same logical input.
  *
- * Codex triple-review P2 (PR #375).
+ * Codex triple-review P2 (PR).
  */
 export function signatureForPlanReview(steps, risk) {
     const stepsJoined = steps.map((s) => s.text.trim()).join('|');

package/dist/core/repl/cancellation.js

@@ -1,38 +1,38 @@
 /**
- * Cancellation token — Sprint α6.9 Phase 1 (agent loop FSM + cancellation).
+ * Cancellation token — Sprint Phase 1 (agent loop FSM + cancellation).
  *
  * A pure-JS one-shot signal that fans out to N listeners. One token is
  * minted per dispatch turn (fresh on each operator brief); when the
  * operator hits Ctrl+C, the REPL calls `abort()` which:
  *
- *   1. Latches `aborted = true` so any future `isAborted` check returns
- *      true (a tool that observes the flag mid-execution can short-circuit
- *      its loop without waiting for an explicit signal-handler callback).
- *   2. Drains the listener set, firing each callback exactly once. The
- *      set is cleared after the drain so a late `onAbort` listener
- *      attached AFTER abort does NOT fire — that is the documented
- *      contract; late listeners are expected to check `isAborted`
- *      explicitly at registration time if they need to know whether the
- *      token already tripped.
+ *  1. Latches `aborted = true` so any future `isAborted` check returns
+ *     true (a tool that observes the flag mid-execution can short-circuit
+ *     its loop without waiting for an explicit signal-handler callback).
+ *  2. Drains the listener set, firing each callback exactly once. The
+ *     set is cleared after the drain so a late `onAbort` listener
+ *     attached AFTER abort does NOT fire — that is the documented
+ *     contract; late listeners are expected to check `isAborted`
+ *     explicitly at registration time if they need to know whether the
+ *     token already tripped.
  *
  * Design choices:
  *
- *   - No coupling to `AbortController` / `AbortSignal`. The session +
- *     tool path are wrapped around this token; where a Web platform
- *     primitive is needed (fetch signal, MCP call), the wrapper bridges
- *     `onAbort` → `controller.abort()` at the seam.
- *   - Idempotent `abort()`. Calling twice is safe and the second call is
- *     a no-op (the listener set is already empty). This matters because
- *     two code paths can race to cancel — the Ctrl+C handler and a
- *     downstream tool that observed `isAborted` and threw — and both
- *     end up calling `dispatch.cancel()` which transitively calls
- *     `token.abort()`.
- *   - Listener errors do NOT block the drain. A throwing listener
- *     stops itself but the next listener still fires. The error is
- *     swallowed because the cancellation path is best-effort and
- *     surfacing the error mid-drain would leak through the abort
- *     pathway into the REPL state (a UI rerender on a half-aborted
- *     session is worse than a silent listener crash).
+ *  - No coupling to `AbortController` / `AbortSignal`. The session +
+ *    tool path are wrapped around this token; where a Web platform
+ *    primitive is needed (fetch signal, MCP call), the wrapper bridges
+ *    `onAbort` → `controller.abort()` at the seam.
+ *  - Idempotent `abort()`. Calling twice is safe and the second call is
+ *    a no-op (the listener set is already empty). This matters because
+ *    two code paths can race to cancel — the Ctrl+C handler and a
+ *    downstream tool that observed `isAborted` and threw — and both
+ *    end up calling `dispatch.cancel()` which transitively calls
+ *    `token.abort()`.
+ *  - Listener errors do NOT block the drain. A throwing listener
+ *    stops itself but the next listener still fires. The error is
+ *    swallowed because the cancellation path is best-effort and
+ *    surfacing the error mid-drain would leak through the abort
+ *    pathway into the REPL state (a UI rerender on a half-aborted
+ *    session is worse than a silent listener crash).
  *
  * Brand voice: no forbidden words. ASCII only. No emoji.
  */

package/dist/core/repl/cap-warning.js

@@ -1,5 +1,5 @@
 /**
- * Client-side concurrent-subagent cap - Sprint α5.7 (ADR-0056
+ * Client-side concurrent-subagent cap - Sprint (
  * acceptance #6, Mac safety memo
  * `feedback_max_3_parallel_agents_mac_safety.md`).
  *
@@ -7,9 +7,9 @@
  * per workstation. The REPL has its own client-side gate that mirrors
  * the global rule for one workstation worth of dispatches:
  *
- *   - active count >= 3 → soft warning (operator may still dispatch).
- *   - active count >= 5 → hard block unless the operator opted in via
- *     PUGI_FORCE_PARALLEL=1.
+ *  - active count >= 3 → soft warning (operator may still dispatch).
+ *  - active count >= 5 → hard block unless the operator opted in via
+ *    PUGI_FORCE_PARALLEL=1.
  *
  * The gate is pure: callers pass the current active count and we return
  * a verdict. The REPL session module reads the dispatcher event stream,

package/dist/core/repl/clipboard-read.js

@@ -1,5 +1,5 @@
 /**
- * Best-effort clipboard READ helper - Sprint α6.14.
+ * Best-effort clipboard READ helper - Sprint .
  *
  * Mirror of the clipboard WRITE helper but for the opposite
  * direction. Powers Ctrl+V paste in the REPL input box: when the
@@ -8,15 +8,15 @@
  * insert the result at the cursor.
  *
  * Contract:
- *   - Returns `{ text }` when the helper exited 0 with non-empty
- *     stdout. Trailing single newline is stripped (clipboard
- *     contents authored by the operator rarely include the trailing
- *     LF the paste helpers append).
- *   - Returns `{ text: null }` on any failure: missing binary,
- *     non-zero exit, no $DISPLAY on headless Linux, EAGAIN.
- *   - Never throws. Caller falls back to "Ctrl+V not available -
- *     try right-click paste" hint.
- *   - Targets node >= 20.
+ *  - Returns `{ text }` when the helper exited 0 with non-empty
+ *    stdout. Trailing single newline is stripped (clipboard
+ *    contents authored by the operator rarely include the trailing
+ *    LF the paste helpers append).
+ *  - Returns `{ text: null }` on any failure: missing binary,
+ *    non-zero exit, no $DISPLAY on headless Linux, EAGAIN.
+ *  - Never throws. Caller falls back to "Ctrl+V not available -
+ *    try right-click paste" hint.
+ *  - Targets node >= 20.
  *
  * Implementation note: we do NOT optimistically run all three Linux
  * helpers in parallel - the cost of spawning xclip when wl-copy
@@ -126,7 +126,7 @@ function defaultSpawnRead(cmd, args) {
     });
 }
 /* ------------------------------------------------------------------ */
-/* Bracketed-paste mode helpers                                       */
+/* Bracketed-paste mode helpers                                      */
 /* ------------------------------------------------------------------ */
 /**
  * Modern terminals (iTerm2, Alacritty, GNOME Terminal, kitty,