@pugi/cli 0.1.0-alpha.18 → 0.1.0-alpha.19

package/dist/core/repl/cancellation.js

@@ -0,0 +1,98 @@
+/**
+ * Cancellation token — Sprint α6.9 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.
+ *
+ * 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).
+ *
+ * Brand voice: no forbidden words. ASCII only. No emoji.
+ */
+export class CancellationToken {
+    aborted = false;
+    listeners = new Set();
+    /**
+     * Latch the token to aborted and fire every currently-attached
+     * listener exactly once. Subsequent `abort()` calls are no-ops
+     * (idempotent — the listener set was already cleared on first abort).
+     * Listener callbacks that throw are swallowed; the next listener
+     * still fires.
+     */
+    abort() {
+        if (this.aborted)
+            return;
+        this.aborted = true;
+        // Snapshot the listener set so a listener that mutates the set
+        // (e.g. detaches itself via the returned unsubscribe handle while
+        // its own callback is running) does not corrupt the iteration.
+        const snapshot = Array.from(this.listeners);
+        this.listeners.clear();
+        for (const listener of snapshot) {
+            try {
+                listener();
+            }
+            catch {
+                // Swallow listener errors — see header comment for rationale.
+            }
+        }
+    }
+    /**
+     * True after `abort()` has been called. Mutation observers and tool
+     * inner loops should read this BEFORE each potentially-expensive
+     * iteration so they can short-circuit on cancel.
+     */
+    get isAborted() {
+        return this.aborted;
+    }
+    /**
+     * Register a callback that fires on the FIRST `abort()` call. If the
+     * token has already aborted at registration time, the callback is
+     * NOT auto-fired — the caller is responsible for checking
+     * `isAborted` first.
+     *
+     * Returns an unsubscribe handle. Calling it before abort detaches the
+     * listener so it never fires; calling it after abort is a no-op (the
+     * set was already drained).
+     */
+    onAbort(listener) {
+        if (this.aborted) {
+            // Document the contract by returning a no-op unsubscribe handle.
+            // The listener does NOT fire — late subscribers must check
+            // isAborted at registration time.
+            return () => undefined;
+        }
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+}
+//# sourceMappingURL=cancellation.js.map

package/dist/core/repl/dispatch-fsm.js

@@ -0,0 +1,204 @@
+/**
+ * Dispatch FSM — Sprint α6.9 Phase 1 (agent loop FSM + cancellation).
+ *
+ * Tracks the lifecycle of a single operator-issued brief from the moment
+ * `POST /api/pugi/sessions/:id/brief` fires until the persona returns a
+ * final reply (or the operator aborts). The Ctrl+C handler and the
+ * status-bar surface both subscribe to state transitions so the UX is
+ * predictable: the operator can always tell where the dispatch is in
+ * its lifecycle and the abort signal lands at a deterministic seam.
+ *
+ * State graph:
+ *
+ *      idle
+ *       │ (brief posted)
+ *       ▼
+ *   awaiting_response ←──────────┐
+ *       │                        │ (next turn)
+ *       ▼                        │
+ *   tool_running ────────────────┘
+ *       │
+ *       ▼
+ *   completed
+ *
+ * Terminal states: `completed`, `failed`, `aborted`. The FSM does not
+ * transition out of a terminal state; a fresh brief mints a new FSM
+ * instance. `aborting` is transient — any non-terminal state can
+ * transition to `aborting`, which then transitions to `aborted` once
+ * the SSE stream + in-flight tool acknowledge the abort.
+ *
+ * Illegal transitions are rejected by throwing a typed error. This is
+ * load-bearing: a bug that tries to walk `completed → tool_running`
+ * would otherwise silently corrupt the agent tree. Throwing fails
+ * loud at the call site so the integration bug surfaces immediately.
+ *
+ * onEnter listeners fire AFTER the state transition is committed.
+ * Subscribers can call `transition()` from inside a listener; the FSM
+ * uses a small re-entrancy guard so nested transitions are processed
+ * in order (the inner transition fires its own listeners before the
+ * outer transition returns).
+ *
+ * Brand voice: no forbidden words. ASCII only. No emoji.
+ */
+/**
+ * Legal transitions per state. Building the matrix at module scope
+ * keeps the FSM declarative and exhaustive — adding a new state forces
+ * the matrix update at typecheck time.
+ *
+ * `idle` is the start state. Posting a brief moves to
+ * `awaiting_response`. The model's first turn either returns a final
+ * text (`completed`), requests tools (`tool_running`), or fails
+ * (`failed`). After tools execute the model gets another turn
+ * (`awaiting_response`); the cycle repeats until a final text or a
+ * terminal outcome.
+ *
+ * `aborting` is reachable from every non-terminal state. From
+ * `aborting` we always end at `aborted` (no rollback — once the
+ * operator aborts, the dispatch is dead). Terminal states have no
+ * outgoing transitions.
+ */
+const LEGAL_TRANSITIONS = {
+    idle: new Set(['awaiting_response', 'aborting']),
+    awaiting_response: new Set([
+        'tool_running',
+        'completed',
+        'failed',
+        'aborting',
+    ]),
+    tool_running: new Set([
+        'awaiting_response',
+        'completed',
+        'failed',
+        'aborting',
+    ]),
+    aborting: new Set(['aborted']),
+    aborted: new Set(),
+    completed: new Set(),
+    failed: new Set(),
+};
+/**
+ * Thrown when `transition()` is called with a state that is not in the
+ * current state's legal outgoing set. Carries enough context that a log
+ * line can be reconstructed at the call site.
+ */
+export class IllegalDispatchTransitionError extends Error {
+    from;
+    to;
+    constructor(from, to) {
+        super(`Illegal dispatch FSM transition: ${from} -> ${to}`);
+        this.name = 'IllegalDispatchTransitionError';
+        this.from = from;
+        this.to = to;
+    }
+}
+export class DispatchFSM {
+    state = 'idle';
+    listeners = new Map();
+    /**
+     * Re-entrancy guard. While `firing === true` we are draining the
+     * listener fan-out for an in-progress transition. A nested
+     * `transition()` call from inside a listener queues into `pending`
+     * instead of recursing, so the legality check + state mutation +
+     * listener drain happen sequentially in commit order. Without this,
+     * a listener that immediately fired another transition would mutate
+     * `this.state` mid-iteration of the outer listener snapshot, which
+     * (a) could turn a legal outer transition into a thrown illegal
+     * inner one (the legality check reads `this.state` already mutated),
+     * (b) could ship `onEnter(B)` reasons under state A's snapshot.
+     * Queueing keeps the transition log linear.
+     */
+    firing = false;
+    pending = [];
+    /**
+     * Current state. Read-only — mutate via `transition()`.
+     */
+    get current() {
+        return this.state;
+    }
+    /**
+     * True when the current state is one of `completed`, `failed`,
+     * `aborted`. Terminal states cannot transition further.
+     */
+    get isTerminal() {
+        return this.state === 'completed' || this.state === 'failed' || this.state === 'aborted';
+    }
+    /**
+     * Transition the FSM to `next`, optionally carrying a `reason` string
+     * that is forwarded to `onEnter` listeners. Throws
+     * `IllegalDispatchTransitionError` when the transition is not in the
+     * current state's legal outgoing set.
+     *
+     * Listener errors do NOT block the transition. A throwing listener
+     * stops itself but the transition is already committed; the next
+     * listener still fires.
+     *
+     * Re-entrant calls (a listener calls `transition()` again) are
+     * queued — the inner transition runs after the outer listener drain
+     * completes, in FIFO order. See `firing` field comment.
+     */
+    transition(next, reason) {
+        if (this.firing) {
+            this.pending.push({ next, reason });
+            return;
+        }
+        this.firing = true;
+        try {
+            this.commit(next, reason);
+            while (this.pending.length > 0) {
+                const queued = this.pending.shift();
+                if (!queued)
+                    break;
+                this.commit(queued.next, queued.reason);
+            }
+        }
+        finally {
+            this.firing = false;
+        }
+    }
+    /**
+     * Inner commit step — legality check + state mutation + listener
+     * drain. Called by `transition()` directly for the first move and
+     * for every queued nested move thereafter. Errors propagate to the
+     * outer `transition()` caller (illegal transitions still throw).
+     */
+    commit(next, reason) {
+        const legal = LEGAL_TRANSITIONS[this.state];
+        if (!legal.has(next)) {
+            throw new IllegalDispatchTransitionError(this.state, next);
+        }
+        this.state = next;
+        const set = this.listeners.get(next);
+        if (!set || set.size === 0)
+            return;
+        // Snapshot the listener set so a listener that detaches itself
+        // (via the returned unsubscribe handle) does not corrupt iteration.
+        const snapshot = Array.from(set);
+        for (const listener of snapshot) {
+            try {
+                listener(reason);
+            }
+            catch {
+                // Swallow listener errors — see header comment for rationale.
+            }
+        }
+    }
+    /**
+     * Register a listener that fires whenever the FSM ENTERS `state`. The
+     * listener does NOT fire if the FSM is already in `state` at
+     * registration time — onEnter is edge-triggered, not level-triggered.
+     *
+     * Returns an unsubscribe handle.
+     */
+    onEnter(state, listener) {
+        let set = this.listeners.get(state);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(state, set);
+        }
+        set.add(listener);
+        return () => {
+            set?.delete(listener);
+        };
+    }
+}
+//# sourceMappingURL=dispatch-fsm.js.map

package/dist/core/repl/privacy-banner.js

@@ -1,14 +1,14 @@
 /**
- * Privacy mode REPL surface — α6.13 (Phase 1).
+ * Privacy mode REPL surface - alpha 6.13 (Phase 1).
  *
  * Two surfaces:
  *
- *   1. `renderPrivacyBanner(mode)` — one-line banner shown on REPL
+ *   1. `renderPrivacyBanner(mode)` - one-line banner shown on REPL
  *      bootstrap (mirrors `apps/admin-api/src/privacy/privacy-mode.ts`
- *      `PRIVACY_MODE_BANNER` verbatim — keep in sync, the unit spec
+ *      `PRIVACY_MODE_BANNER` verbatim - keep in sync, the unit spec
  *      asserts they match).
  *
- *   2. `renderPrivacyContractDoc(mode)` — multi-line contract doc the
+ *   2. `renderPrivacyContractDoc(mode)` - multi-line contract doc the
  *      `/privacy` slash command prints. Shows the active mode header
  *      + the full 3-mode contract so the operator can compare their
  *      current posture to the alternatives without leaving the REPL.

package/dist/core/repl/session.js

@@ -134,6 +134,22 @@ export class ReplSession {
      * with `[store]` errors on every keystroke.
      */
     storeErrorEmitted = false;
+    /**
+     * Privacy mode fetched on bootstrap from /api/admin/privacy/mode and
+     * surfaced via `renderPrivacyBanner` (one-line system message after
+     * splash). Cached on the session so the in-REPL `/privacy` slash
+     * command can render the live mode without a second round-trip on
+     * the input box's thread. Null means "not yet fetched" (still
+     * connecting) OR "fetch failed" (offline / unauthenticated). The
+     * `/privacy` slash falls back to the contract doc with an "unknown"
+     * banner when null.
+     *
+     * Triple-review P1 fix (2026-05-25): the prior build defined
+     * `renderPrivacyBanner` but never called it, and `/privacy` always
+     * rendered with `null` mode. The contract was advertised but the
+     * operator had no mode visibility.
+     */
+    privacyMode = null;
     /**
      * α6.5 Tier 0 / Tier 1 / chokidar wiring. The bootstrap builds the
      * skeleton + working set + watcher once and hands them to the
@@ -270,12 +286,58 @@ export class ReplSession {
             });
             this.patch({ sessionId, connection: 'connecting' });
             this.openStream();
+            // alpha 6.13 privacy banner. Fire-and-forget - never blocks the
+            // input box on the network round-trip. The banner is a single
+            // system-line so the operator sees the active mode under the
+            // splash without an extra slash command. Mode is cached on the
+            // session so `/privacy` later renders the live value without a
+            // second fetch. Failure to fetch (offline, unauthenticated,
+            // admin-api down) is silent - the operator can still type
+            // `/privacy` to see the contract.
+            void this.fetchAndAnnouncePrivacyMode().catch(() => undefined);
         }
         catch (error) {
             this.appendSystemLine(`Could not open Pugi session: ${this.errorMessage(error)}`);
             this.patch({ connection: 'offline' });
         }
     }
+    /**
+     * Fetch the tenant's current privacy mode from
+     * `GET /api/admin/privacy/mode`, cache it on the session, and emit
+     * a one-line system banner so the operator sees their active mode
+     * right under the bootstrap splash. Failure is silent - missing
+     * banner is preferable to a noisy "could not fetch privacy mode"
+     * line on every login.
+     *
+     * Triple-review P1 fix (2026-05-25): without this call,
+     * `renderPrivacyBanner` was defined but never reached the wire, and
+     * `/privacy` always rendered with `null` mode.
+     */
+    async fetchAndAnnouncePrivacyMode() {
+        const { renderPrivacyBanner, isPrivacyMode } = await import('./privacy-banner.js');
+        try {
+            const url = `${this.options.apiUrl.replace(/\/+$/, '')}/api/admin/privacy/mode`;
+            const res = await fetch(url, {
+                headers: {
+                    authorization: `Bearer ${this.options.apiKey}`,
+                    accept: 'application/json',
+                },
+            });
+            if (!res.ok) {
+                // Silent fail - banner is decoration, not a blocking surface.
+                return;
+            }
+            const payload = (await res.json());
+            const mode = payload.mode;
+            if (typeof mode === 'string' && isPrivacyMode(mode)) {
+                this.privacyMode = mode;
+                this.appendSystemLine(renderPrivacyBanner(mode));
+            }
+        }
+        catch {
+            // Silent fail - offline / DNS / unauth all collapse to no banner.
+        }
+    }
     /**
      * Tear down the SSE stream and stop the reconnect timer. The session
      * id stays valid server-side; `pugi resume <id>` reopens later.
@@ -396,12 +458,40 @@ export class ReplSession {
                 this.patch({ pendingAsk: askTag, pendingAskSource: 'local' });
                 return verdict;
             }
+            case 'privacy': {
+                // alpha 6.13: print the full mode contract + current banner
+                // inline. The current mode is resolved lazily by the helper -
+                // when unauthenticated or offline the banner falls back to
+                // "(unknown - mode lookup pending)" and the contract doc still
+                // renders so the operator can read the alternatives.
+                await this.dispatchPrivacy();
+                return verdict;
+            }
             case 'stub': {
                 this.appendSystemLine(verdict.message);
                 return verdict;
             }
         }
     }
+    /**
+     * In-REPL `/privacy` - alpha 6.13. Prints the full 3-mode contract
+     * doc + the current mode banner inline. The current mode is fetched
+     * via the admin-api /api/admin/privacy/mode endpoint when the
+     * operator is authenticated; otherwise the banner falls back to
+     * "(unknown)" and the contract doc still renders so the operator
+     * can compare modes without leaving the REPL.
+     */
+    async dispatchPrivacy() {
+        const { renderPrivacyContractDoc } = await import('./privacy-banner.js');
+        // Triple-review P1 fix (2026-05-25): use the bootstrap-cached mode
+        // so the operator sees the LIVE current mode in the banner header
+        // instead of "(unknown)". The fetch happens once on session start;
+        // if it failed (offline / unauth) the cache stays null and the
+        // banner falls back to "(unknown)" - same UX as before, just with
+        // the happy path actually delivering the mode.
+        const doc = renderPrivacyContractDoc(this.privacyMode);
+        this.appendSystemLine(doc);
+    }
     /**
      * In-REPL `/resume` - α6.4. Lists the 10 most recent sessions from
      * the local SessionStore and prints them as a numbered system menu.

package/dist/core/repl/slash-commands.js

@@ -41,7 +41,9 @@ export const SLASH_STUB_MESSAGES = Object.freeze({
     compact: 'Manual context compaction lands in α6.5b.',
     memory: 'Session memory editor lands in α6.5b.',
     config: 'Run `pugi config list` from a fresh shell for the full surface; in-REPL editor lands in α6.5.',
-    privacy: 'Run `pugi privacy show` from a fresh shell; in-REPL toggle lands in α6.5.',
+    // alpha 6.13: /privacy graduated from stub; nothing reads this at
+    // runtime but the type record stays exhaustive.
+    privacy: '',
     budget: 'Run `pugi budget` from a fresh shell; in-REPL summary lands in α6.5.',
     mcp: 'Run `pugi config mcp list` from a fresh shell; in-REPL palette lands in α6.5.',
     undo: 'Run `pugi undo` from a fresh shell; in-REPL undo lands in α6.5.',
@@ -67,7 +69,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'consensus', args: '[ref]', gloss: '3-model consensus review (codex · claude · deepseek)', group: 'Pugi tools' },
     // Settings
     { name: 'config', args: '', gloss: 'Show config', group: 'Settings', stub: true },
-    { name: 'privacy', args: '', gloss: 'Show privacy mode', group: 'Settings', stub: true },
+    { name: 'privacy', args: '', gloss: 'Show privacy mode + contract', group: 'Settings' },
     { name: 'budget', args: '', gloss: 'Show usage budget', group: 'Settings', stub: true },
     { name: 'mcp', args: '', gloss: 'List MCP servers', group: 'Settings', stub: true },
     { name: 'undo', args: '', gloss: 'Undo last write', group: 'Settings', stub: true },
@@ -205,10 +207,17 @@ export function parseSlashCommand(input) {
             // skeleton size + working-set utilisation at a glance.
             return { kind: 'context' };
         }
+        case 'privacy': {
+            // alpha 6.13: real handler - the session module prints the
+            // contract doc + the current mode banner. Tail is ignored (no
+            // sub-commands today; mode flips go through
+            // `pugi config set privacy=<mode>` from a fresh shell so the
+            // device flow + audit identity are wired correctly).
+            return { kind: 'privacy' };
+        }
         case 'compact':
         case 'memory':
         case 'config':
-        case 'privacy':
         case 'budget':
         case 'mcp':
         case 'undo': {