@pugi/cli 0.1.0-beta.87 → 0.1.0-beta.88

package/dist/runtime/sigint-guard.js

@@ -0,0 +1,272 @@
+/**
+ * Double-press Ctrl+C exit guard for the Pugi CLI top-level lifecycle.
+ *
+ * # Problem
+ *
+ * Operator dogfood reported a single Ctrl+C exits the REPL / headless
+ * loop. Operators expect a forgiving "press again to confirm" gesture
+ * — the same shell convention `^C ^C` already used by the per-engine
+ * task abort path in `runtime/cli.ts` (`runEngineTask`). Without the
+ * gesture at the top level, a stray Ctrl+C while typing a slash command
+ * or scrolling a transcript kills the session and any in-memory state
+ * the operator hasn't synced yet.
+ *
+ * # Behavior
+ *
+ *  1. **First Ctrl+C** — emit a one-line stderr prompt
+ *     "Press Ctrl+C again to exit (within 2s), or any key to continue."
+ *     Arm a 2-second window timer. Install a one-shot `stdin.once('data', …)`
+ *     so the FIRST keystroke after the prompt cancels the exit gesture.
+ *  2. **Second Ctrl+C inside window** — flush log streams, persist a
+ *     minimal session-state snapshot to `~/.pugi/session-state.json`,
+ *     and exit with code 0. The state file is best-effort: any write
+ *     error is swallowed so the operator's exit is never blocked on
+ *     a disk hiccup.
+ *  3. **Other key inside window** — clear the timer, drop the prompt,
+ *     emit "Exit cancelled." to stderr, and resume normally.
+ *  4. **Window expires** — clear `lastSigintTs`. A subsequent isolated
+ *     Ctrl+C is treated as a NEW first press, not a confirmation.
+ *  5. **Headless mode** — when `process.stdin.isTTY === false`, the
+ *     guard switches strategy: it closes stdin (so any `for await rl`
+ *     loop in `headless-repl.ts` unwinds naturally), emits a
+ *     `session-end` envelope to stdout (single JSON line, matches
+ *     the envelope schema), and exits 0. Stdin can't deliver "any
+ *     other key" when it's not a TTY, so the double-press dance is
+ *     skipped in this mode.
+ *
+ * # Coexistence with the per-engine-run handler
+ *
+ * `runEngineTask` in `runtime/cli.ts` installs its OWN
+ * `process.on('SIGINT', …)` for the duration of an engine dispatch
+ * (lines around 6233). That handler aborts the in-flight turn on the
+ * first press and exits 130 on a second press inside its OWN 2s
+ * window. Both handlers receive every SIGINT — Node delivers signals
+ * to every listener.
+ *
+ * To avoid a double prompt while an engine turn is running, this
+ * guard checks `process.listenerCount('SIGINT')` at the start of its
+ * handler: if any other listener is attached (i.e. an engine run owns
+ * the foreground), we step aside and let that handler drive the UX.
+ * The engine handler's "press again to exit" prompt already covers
+ * the abort-then-quit story for that window. When the engine run
+ * unwinds, it detaches its listener and the REPL-level guard regains
+ * control.
+ *
+ * # Why module-scope, not per-call closure
+ *
+ * The press-count state must survive between two distinct SIGINT
+ * deliveries. A closure-scoped flag would reset on the second SIGINT
+ * because Node invokes the handler in a fresh microtask each time.
+ * Module-scope `let` is the simplest store that gives us cross-press
+ * persistence without leaking to other files.
+ *
+ * # Testability
+ *
+ * `installSigintGuard()` takes an optional `SigintGuardOptions` bag
+ * so the spec can inject:
+ *   - a fake `stdin` (for "any key cancels"),
+ *   - a fake `stdout` / `stderr` sink,
+ *   - a `now()` clock seam,
+ *   - a `setTimeout` / `clearTimeout` pair,
+ *   - a `exit(code)` seam (the test never lets the real process exit),
+ *   - and a `persistSessionState(payload)` injection so the spec
+ *     observes the persisted snapshot without touching `~/`.
+ *
+ * In production all seams default to the real Node primitives.
+ */
+import { writeFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve as resolvePath, dirname } from 'node:path';
+/**
+ * Default double-press window. Matches the per-engine-run handler so
+ * operators see one consistent timing rule across the CLI.
+ */
+export const SIGINT_DOUBLE_PRESS_WINDOW_MS = 2000;
+/**
+ * Default location for the session-state snapshot the guard writes on
+ * a confirmed exit. Resolved at call time so `homedir()` is read late
+ * enough to honor a test override of the `HOME` env var.
+ */
+export function defaultSessionStatePath(home = homedir()) {
+    return resolvePath(home, '.pugi', 'session-state.json');
+}
+/**
+ * Default JSON-file persister. Best-effort: a failed write is logged
+ * to stderr (so the operator notices in debug runs) and then
+ * swallowed — the exit must not block on filesystem health.
+ */
+async function defaultPersist(snapshot) {
+    const filePath = defaultSessionStatePath();
+    try {
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile(filePath, JSON.stringify(snapshot, null, 2), {
+            mode: 0o600,
+            encoding: 'utf8',
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`pugi: session-state write failed: ${message}\n`);
+    }
+}
+/**
+ * Default SIGINT subscription wires the handler onto `process` and
+ * returns an unsubscribe closure that detaches it. We use `.on` (not
+ * `.once`) so the handler stays attached across multiple presses
+ * within the same process lifetime.
+ */
+function defaultOnSigint(handler) {
+    process.on('SIGINT', handler);
+    return () => {
+        process.off('SIGINT', handler);
+    };
+}
+/**
+ * Install the double-press Ctrl+C exit guard. Returns a handle whose
+ * `uninstall()` detaches the SIGINT listener and clears any pending
+ * window timer; production never calls it.
+ *
+ * This function is idempotent: calling it a second time installs a
+ * NEW guard alongside the old one, which would cause duplicate
+ * prompts. The caller (cli.ts main entry) MUST call it exactly once,
+ * at the very top of the run. Tests that need multiple installs are
+ * expected to `uninstall()` between scenarios.
+ */
+export function installSigintGuard(options = {}) {
+    const stdin = options.stdin ?? process.stdin;
+    const stderr = options.stderr ?? process.stderr;
+    const stdout = options.stdout ?? process.stdout;
+    const now = options.now ?? Date.now;
+    const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    const exit = options.exit ?? ((code) => process.exit(code));
+    const persist = options.persistSessionState ?? defaultPersist;
+    const subscribe = options.onSigint ?? defaultOnSigint;
+    const isHeadless = options.isHeadless ?? (() => stdin.isTTY !== true);
+    const windowMs = options.windowMs ?? SIGINT_DOUBLE_PRESS_WINDOW_MS;
+    // State scoped to THIS install. Each call to `installSigintGuard`
+    // gets a fresh closure so concurrent tests do not bleed into each
+    // other. Production calls the function once at the top of the run.
+    let lastSigintTs = null;
+    let pendingTimer = null;
+    let pendingDataListener = null;
+    const resetWindow = () => {
+        lastSigintTs = null;
+        if (pendingTimer !== null) {
+            clearTimer(pendingTimer);
+            pendingTimer = null;
+        }
+        if (pendingDataListener !== null) {
+            // Detach via the same instance we attached; never the typed
+            // overload that re-binds 'data' to all listeners.
+            stdin.removeListener('data', pendingDataListener);
+            pendingDataListener = null;
+        }
+    };
+    const performExit = (reason) => {
+        const snapshot = {
+            exitedAt: new Date(now()).toISOString(),
+            reason,
+            cwd: process.cwd(),
+            pid: process.pid,
+        };
+        // Fire-and-forget persistence: we attempt to flush, but do not
+        // block the exit on the result. The promise is observed only to
+        // suppress unhandled-rejection noise in the test runner.
+        void persist(snapshot).catch(() => {
+            /* defaultPersist already logged */
+        });
+        exit(0);
+    };
+    const handleHeadless = () => {
+        // In headless mode we never prompt — the operator (or harness)
+        // has no keyboard to confirm with. We emit one final
+        // session-end envelope so any line-buffered consumer sees a
+        // clean terminator, close stdin so the `for await rl` loop in
+        // headless-repl.ts unwinds, and exit 0.
+        const envelope = {
+            kind: 'session-end',
+            body: JSON.stringify({ reason: 'sigint' }),
+            ts: now(),
+        };
+        stdout.write(`${JSON.stringify(envelope)}\n`);
+        // Best-effort stdin close so any in-flight readline loop terminates.
+        // Some stream implementations (e.g. test doubles) lack `.destroy`;
+        // guard the call so we never throw out of a signal handler.
+        const stdinAsAny = stdin;
+        try {
+            if (typeof stdinAsAny.destroy === 'function') {
+                stdinAsAny.destroy();
+            }
+            else if (typeof stdinAsAny.pause === 'function') {
+                stdinAsAny.pause();
+            }
+        }
+        catch {
+            /* ignore — destroy/pause is opportunistic */
+        }
+        performExit('sigint-headless');
+    };
+    const handleInteractive = () => {
+        const ts = now();
+        if (lastSigintTs !== null && ts - lastSigintTs <= windowMs) {
+            // Confirmed double-press. Drop the prompt artifacts, persist
+            // state, exit clean. resetWindow() handles the listener
+            // cleanup so a stray `data` event after exit does not fire.
+            resetWindow();
+            stderr.write('\npugi: exiting (^C^C confirmed).\n');
+            performExit('sigint-double-press');
+            return;
+        }
+        // First press — arm the window.
+        lastSigintTs = ts;
+        stderr.write('\nPress Ctrl+C again to exit (within 2s), or any key to continue.\n');
+        // Schedule a window-expiry reset. When the timer fires the
+        // operator's prior press no longer "counts" — the next ^C is
+        // treated as a fresh first press.
+        pendingTimer = setTimer(() => {
+            lastSigintTs = null;
+            pendingTimer = null;
+            if (pendingDataListener !== null) {
+                stdin.removeListener('data', pendingDataListener);
+                pendingDataListener = null;
+            }
+        }, windowMs);
+        // Install a one-shot 'data' listener so any keystroke other than
+        // a follow-up SIGINT cancels the exit gesture. We use
+        // `removeListener` after firing rather than `.once` because we
+        // also detach the listener from `resetWindow()` (the timer or
+        // a second SIGINT can both kill it).
+        const onData = (_chunk) => {
+            resetWindow();
+            stderr.write('Exit cancelled.\n');
+        };
+        pendingDataListener = onData;
+        stdin.on('data', onData);
+    };
+    const handler = () => {
+        // Coexistence guard: if another SIGINT listener is registered
+        // (e.g. the per-engine-run handler in runEngineTask), step aside
+        // and let it drive the UX. We count `> 1` because OUR handler
+        // is also in the list.
+        if (process.listenerCount('SIGINT') > 1 && !options.onSigint) {
+            // Drop any state we'd accumulated so an interactive prompt
+            // after the engine run starts from a clean slate.
+            resetWindow();
+            return;
+        }
+        if (isHeadless()) {
+            handleHeadless();
+            return;
+        }
+        handleInteractive();
+    };
+    const unsubscribe = subscribe(handler);
+    return {
+        uninstall: () => {
+            resetWindow();
+            unsubscribe();
+        },
+    };
+}
+//# sourceMappingURL=sigint-guard.js.map

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.87');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.88');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/dist/skills/bundled/batch.js

@@ -41,8 +41,8 @@
  *
  * # Provenance
  *
- * Inspired by the Nuekkis bundled-skills pattern (intel from
- * leak-research memos, clean-room TS). No upstream code reused.
+ * Inspired by the external bundled-skills pattern (intel from
+ * leak-research memos, independent implementation TS). No upstream code reused.
  */
 import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';

package/dist/skills/bundled/index.js

@@ -9,7 +9,7 @@
  *    - `pugi simplify` — local 3-agent parallel review + auto-fix.
  *    - `pugi remember` — proposal-first memory curator.
  *
- *  - Batch 2 (`#169`, Nuekkis clean-room):
+ *  - Batch 2 (`#169`, external independent implementation):
  *    - `pugi batch`   — fan-out multi-task parallel execution scaffold.
  *    - `pugi verify`  — post-execution claim verification.
  *    - `pugi loop`    — drive a prompt against the engine to a stop condition.
@@ -19,8 +19,8 @@
  * in `runtime/cli.ts` (and any future REPL slash wrapper) imports
  * through one barrel. New batches append to the union types here.
  *
- * Inspired by the upstream tool / Nuekkis bundled-skills patterns (intel from
- * leak-research memos, clean-room TS).
+ * Inspired by the upstream tool / external bundled-skills patterns (intel from
+ * leak-research memos, independent implementation TS).
  */
 export { runStuckCommand, classifyPeers, classifyChildren, readDebugTail, captureSampleStack, postSnapshotToWebhook, readProcessTable, } from './stuck.js';
 export { runSimplifyCommand, aggregateReviewerResults, parseReviewerFindings, defaultCaptureDiff, } from './simplify.js';

package/dist/skills/bundled/loop.js

@@ -29,8 +29,8 @@
  *
  * # Provenance
  *
- * Inspired by the Nuekkis bundled-skills pattern (intel from
- * leak-research memos, clean-room TS). No upstream code reused.
+ * Inspired by the external bundled-skills pattern (intel from
+ * leak-research memos, independent implementation TS). No upstream code reused.
  * Multi-provider council mode inside loop is backlog; today the
  * skill is single-engine.
  */

package/dist/skills/bundled/remember.js

@@ -45,7 +45,7 @@
  * # Provenance
  *
  * Inspired by the the upstream tool bundled-skills pattern (intel from
- * leak-research memos, clean-room TS). No upstream code reused.
+ * leak-research memos, independent implementation TS). No upstream code reused.
  */
 import { readFileSync } from 'node:fs';
 import { PERSONA_MEMORY_KINDS, enqueueMemoryOp, } from '../../core/memory-sync/queue.js';

package/dist/skills/bundled/simplify.js

@@ -43,7 +43,7 @@
  * # Provenance
  *
  * Inspired by the the upstream tool bundled-skills pattern (intel from
- * leak-research memos, clean-room TS). No upstream code reused.
+ * leak-research memos, independent implementation TS). No upstream code reused.
  */
 import { execFileSync } from 'node:child_process';
 const DEFAULT_BASE_REF = 'origin/main';

package/dist/skills/bundled/skillify.js

@@ -29,8 +29,8 @@
  *
  * # Provenance
  *
- * Inspired by the Nuekkis bundled-skills pattern (intel from
- * leak-research memos, clean-room TS). No upstream code reused.
+ * Inspired by the external bundled-skills pattern (intel from
+ * leak-research memos, independent implementation TS). No upstream code reused.
  */
 import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import { dirname, join } from 'node:path';

package/dist/skills/bundled/stuck.js

@@ -34,7 +34,7 @@
  * # Provenance
  *
  * Inspired by the the upstream tool bundled-skills pattern (intel from
- * leak-research memos, clean-room TS). No upstream code reused.
+ * leak-research memos, independent implementation TS). No upstream code reused.
  */
 import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';

package/dist/skills/bundled/verify.js

@@ -39,8 +39,8 @@
  *
  * # Provenance
  *
- * Inspired by the Nuekkis bundled-skills pattern (intel from
- * leak-research memos, clean-room TS). No upstream code reused.
+ * Inspired by the external bundled-skills pattern (intel from
+ * leak-research memos, independent implementation TS). No upstream code reused.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';

package/dist/testing/vcr.js

@@ -1,7 +1,7 @@
 /**
  * VCR — Pugi CLI test helper that records `fetch` interactions to a JSON
- * cassette and replays them deterministically. Clean-room re-implementation
- * of the Nuekkis `vcr.ts` pattern; Node built-ins only (`node:fs`,
+ * cassette and replays them deterministically. independent implementation re-implementation
+ * of the external `vcr.ts` pattern; Node built-ins only (`node:fs`,
  * `node:crypto`, `node:path`), no new dependencies.
  *
  * # Why this exists

package/dist/tools/ask-user-question.js

@@ -48,6 +48,22 @@ export const ASK_USER_QUESTION_OPTION_DESC_MAX = 200;
 /** Option count: 2-4 strict. UI adds "Other" automatically. */
 export const ASK_USER_QUESTION_OPTIONS_MIN = 2;
 export const ASK_USER_QUESTION_OPTIONS_MAX = 4;
+/** PUGI-480 short-format chip rules: ≤ 5 words / option label, ≤ 3 questions / call. */
+export const ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX = 5;
+export const ASK_USER_QUESTION_CHIPS_MAX = 3;
+/**
+ * Reusable validator for option labels rendered в chip mode.
+ * Counts whitespace-delimited words. Throws с a clear message that
+ * names the offending question + option so the model can self-correct.
+ */
+export function assertChipLabelWordCap(questionHeader, optionLabel) {
+    const words = optionLabel.trim().split(/\s+/u).filter((w) => w.length > 0);
+    if (words.length > ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX) {
+        throw new Error(`ask_user_question chip "${questionHeader}" option "${optionLabel}" ` +
+            `exceeds the ${ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX}-word label cap ` +
+            `(saw ${words.length} words). Shorten the label before dispatch.`);
+    }
+}
 /**
  * Structured option. `label` is the display text; `description` is the
  * implication line shown dim below it. Both are required — the model
@@ -100,6 +116,56 @@ export const askUserQuestionSchema = z.strictObject({
         .default(false)
         .describe('Allow multiple selections. Default false.'),
 });
+/**
+ * PUGI-480 multi-question chip payload — a bundle of up to 3 short-format
+ * chip questions rendered side-by-side. Schema is intentionally narrow:
+ * the chip renderer relies on the ≤ 5-word label invariant и will
+ * truncate с "…" if the model ever bypasses Zod. The 3-question cap
+ * forecloses paragraph-wall prompts at the schema level — the model
+ * cannot legally ask "10 quick questions" in one shot.
+ */
+export const askUserQuestionChipsQuestionSchema = z.strictObject({
+    header: z
+        .string()
+        .min(ASK_USER_QUESTION_HEADER_MIN)
+        .max(ASK_USER_QUESTION_HEADER_MAX)
+        .describe('Short chip label (max 12 chars). E.g. "Stack".'),
+    question: z
+        .string()
+        .min(ASK_USER_QUESTION_MIN)
+        .max(ASK_USER_QUESTION_MAX)
+        .optional()
+        .describe('Optional full-prose question (shown in non-TTY fallback only).'),
+    options: z
+        .array(askUserQuestionOptionSchema)
+        .min(ASK_USER_QUESTION_OPTIONS_MIN)
+        .max(ASK_USER_QUESTION_OPTIONS_MAX + 1)
+        .superRefine((opts, ctx) => {
+        // Enforce ≤ 5-word label cap on every option. Schema-level so
+        // the model gets immediate feedback on overflow rather than a
+        // silent truncation at render time.
+        for (const opt of opts) {
+            const words = opt.label
+                .trim()
+                .split(/\s+/u)
+                .filter((w) => w.length > 0);
+            if (words.length > ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: `option "${opt.label}" has ${words.length} words; chip labels must be ≤ ${ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX} words`,
+                });
+            }
+        }
+    })
+        .describe('2-5 mutually-exclusive options. Each label ≤ 5 words. UI inserts "Skip — use defaults" as a final option when defaults are present.'),
+});
+export const askUserQuestionChipsSchema = z.strictObject({
+    questions: z
+        .array(askUserQuestionChipsQuestionSchema)
+        .min(1)
+        .max(ASK_USER_QUESTION_CHIPS_MAX)
+        .describe('Bundle of 1-3 short clarifier questions rendered side-by-side as chips.'),
+});
 /**
  * Dispatch the structured tool: validate args via Zod, then route
  * through the shared `askUser` primitive so abort/timeout/non-TTY

package/dist/tools/bash.js

@@ -23,7 +23,7 @@
  *     `jobId`. `listJobs()` and `killJob(jobId)` are exported.
  *  5. 60s default timeout. SIGTERM at deadline, SIGKILL 5s later.
  *     Emit `bash.timeout`.
- *  6. POSIX-only (`/bin/sh`). The non-goal in ADR-0056 explicitly
+ *  6. POSIX-only (`/bin/sh`). The non-goal in  explicitly
  *     drops Windows shell support for M1.
  */
 import { randomUUID } from 'node:crypto';
@@ -191,7 +191,7 @@ export async function bashTool(input, ctx) {
             };
         }
     }
-    // POSIX-only `/bin/sh -c <cmd>`. The ADR-0056 non-goals explicitly
+    // POSIX-only `/bin/sh -c <cmd>`. The  non-goals explicitly
     // exclude Windows for M1.
     //
     // stdio layout:

package/dist/tools/powershell.js

@@ -6,7 +6,7 @@
  * на cross-platform PowerShell 7+ binary so Windows-first workflows are
  * first-class на Pugi.
  *
- * Clean-room re-implementation. Surface mirrors bashTool's permission
+ * independent implementation re-implementation. Surface mirrors bashTool's permission
  * gate, env sanitiser, output cap, timeout, and exit-code propagation;
  * the only difference is the shell binary selection. Per-platform
  * resolution: