@pugi/cli 0.1.0-beta.29 → 0.1.0-beta.30

package/dist/core/memory/dual-write.js

@@ -0,0 +1,416 @@
+/**
+ * Pugi CLI dual-write client — Memory Phase 1 (2026-05-27, Wave 6).
+ *
+ * Promotes the per-session NDJSON event log (Memory Phase 0, PR #522)
+ * to a best-effort Prisma row store via the admin-api endpoint:
+ *
+ *   POST /api/pugi/sessions/:sessionId/events
+ *
+ * Design contract:
+ *
+ *   1. Local NDJSON is the SOURCE OF TRUTH. The dual-write client is
+ *      fire-and-forget — a network failure NEVER blocks the local
+ *      append path, and the operator never loses data because the
+ *      .pugi/sessions/<id>/events.<n>.jsonl file is always written
+ *      first by the SessionStore.
+ *
+ *   2. Async + debounced. Events are buffered in memory and flushed on
+ *      a timer (default 250 ms) or when the buffer crosses the batch
+ *      cap (default 50). The debounce + buffer keeps the network cost
+ *      proportional to operator activity, not per-event.
+ *
+ *   3. Retry with backoff. A failed flush retries up to 3 times with
+ *      exponential backoff (250 ms / 750 ms / 2250 ms). Failure beyond
+ *      that drops the batch; the next flush brings in the backlog from
+ *      the local NDJSON via the resume path.
+ *
+ *   4. Resume marker. The client tracks `lastSyncedSeq` per session in
+ *      `~/.pugi/memory-sync/<sessionId>.json`. On `flushBacklog()` it
+ *      reads any events from the local NDJSON whose seq > lastSyncedSeq
+ *      and posts them in order. The marker is updated only on a
+ *      successful POST so a crash mid-flush retries the unsent batch.
+ *
+ *   5. Kill switch. `PUGI_MEMORY_PHASE1_PRISMA_PERSIST_ENABLED=false`
+ *      shuts the dual-write off entirely (env var, no settings file
+ *      round-trip). The client is also a no-op when no credentials are
+ *      available — anon CLI sessions never POST.
+ *
+ *   6. Schema contract. The kinds mirror
+ *      `apps/admin-api/src/pugi-session-events/pugi-session-events.types.ts`
+ *      PUGI_SESSION_EVENT_KINDS. The CLI's broader NDJSON kind set
+ *      (`user`, `persona`, `rewind-marker`, etc.) is REMAPPED to the
+ *      Phase-1 closed set inside `eventToPhase1()` — adding a new
+ *      Phase-1 kind requires a coordinated CLI + server bump.
+ *
+ * The client carries no Nest / Prisma deps — pure node:fs + global
+ * fetch so it boots inside the CLI's REPL workflow without dragging in
+ * the admin-api graph.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { PUGI_SESSION_EVENT_KINDS, } from './phase1-kinds.js';
+/* ------------------------------------------------------------------ */
+/* Constants                                                           */
+/* ------------------------------------------------------------------ */
+export const DEFAULT_DEBOUNCE_MS = 250;
+export const DEFAULT_MAX_BATCH_SIZE = 50;
+export const DEFAULT_MAX_RETRIES = 3;
+/** Server-side hard ceiling (mirror of admin-api MAX_BATCH_EVENTS). */
+const SERVER_MAX_BATCH_EVENTS = 200;
+/** Env kill-switch. Unset / 'true' / '1' = enabled. 'false' / '0' = off. */
+export function isDualWriteEnabledFromEnv(env = process.env) {
+    const raw = env.PUGI_MEMORY_PHASE1_PRISMA_PERSIST_ENABLED;
+    if (raw === undefined || raw === '')
+        return true;
+    const v = raw.toLowerCase().trim();
+    return v !== 'false' && v !== '0' && v !== 'off' && v !== 'no';
+}
+/** Env override for debounce (ms). Falls back to DEFAULT_DEBOUNCE_MS. */
+export function debounceMsFromEnv(env = process.env) {
+    const raw = env.PUGI_MEMORY_DUAL_WRITE_DEBOUNCE_MS;
+    if (!raw)
+        return DEFAULT_DEBOUNCE_MS;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0 || n > 60_000)
+        return DEFAULT_DEBOUNCE_MS;
+    return n;
+}
+export function defaultStateDir(home = homedir()) {
+    return resolve(home, '.pugi', 'memory-sync');
+}
+export function syncStatePath(sessionId, stateDir) {
+    return resolve(stateDir, `${sessionId}.json`);
+}
+export function readSyncState(sessionId, stateDir = defaultStateDir()) {
+    const p = syncStatePath(sessionId, stateDir);
+    if (!existsSync(p))
+        return 0;
+    try {
+        const raw = readFileSync(p, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.schema === 1 &&
+            typeof parsed.lastSyncedSeq === 'number' &&
+            Number.isInteger(parsed.lastSyncedSeq) &&
+            parsed.lastSyncedSeq >= 0) {
+            return parsed.lastSyncedSeq;
+        }
+    }
+    catch {
+        // Best effort — a corrupt state file means "resync from zero".
+        return 0;
+    }
+    return 0;
+}
+export function writeSyncState(sessionId, lastSyncedSeq, stateDir = defaultStateDir()) {
+    if (!existsSync(stateDir)) {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    }
+    const p = syncStatePath(sessionId, stateDir);
+    const record = {
+        schema: 1,
+        sessionId,
+        lastSyncedSeq,
+        updatedAt: new Date().toISOString(),
+    };
+    // Atomic write: temp + rename so a crash mid-write leaves either the
+    // old contents or the new — never a partial JSON document.
+    const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(record), { encoding: 'utf-8', mode: 0o600 });
+    renameSync(tmp, p);
+}
+/* ------------------------------------------------------------------ */
+/* DualWriteClient                                                    */
+/* ------------------------------------------------------------------ */
+/**
+ * Compute the next backoff delay (ms). Exponential growth from the
+ * debounce base — 1× / 3× / 9× — keeps the retry storm bounded.
+ */
+export function nextBackoffMs(attempt, base) {
+    // attempt 1 -> base, attempt 2 -> 3×base, attempt 3 -> 9×base.
+    return base * Math.pow(3, Math.max(0, attempt - 1));
+}
+/**
+ * Tiny await-able sleeper. Public for tests that want a deterministic
+ * scheduler — production callers go through the internal debounce
+ * timer, not this helper.
+ */
+function sleep(ms, scheduler = setTimeout) {
+    return new Promise((res) => scheduler(res, Math.max(0, ms)));
+}
+/**
+ * Buffered, debounced, retry-capable dual-write client.
+ *
+ * One instance per active session. The CLI's SessionStore creates one
+ * at `openSession()` and disposes it at `archive()` / `process.exit()`.
+ * The instance retains its own buffer + flushing promise so concurrent
+ * `enqueue()` calls from multiple producers (REPL turn + subagent
+ * dispatcher) coalesce into the same batch.
+ */
+export class DualWriteClient {
+    cfg;
+    buffer = [];
+    flushTimer = null;
+    /**
+     * Active flush promise (null when idle). Re-using the in-flight
+     * promise lets `enqueue` callers tail-chain a pending flush instead
+     * of stacking N flushes when the CLI is in a hot loop.
+     */
+    flushing = null;
+    /** Disposed clients reject further enqueues quietly. */
+    disposed = false;
+    /** Track the highest server-acknowledged seq. */
+    highestSyncedSeq;
+    constructor(config) {
+        const stateDir = config.stateDir ?? defaultStateDir();
+        this.cfg = {
+            apiUrl: config.apiUrl.replace(/\/+$/, ''),
+            apiKey: config.apiKey,
+            sessionId: config.sessionId,
+            debounceMs: config.debounceMs ?? debounceMsFromEnv(),
+            maxBatchSize: Math.min(config.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE, SERVER_MAX_BATCH_EVENTS),
+            maxRetries: config.maxRetries ?? DEFAULT_MAX_RETRIES,
+            fetchImpl: config.fetchImpl ?? globalThis.fetch,
+            stateDir,
+        };
+        this.highestSyncedSeq = readSyncState(config.sessionId, stateDir);
+    }
+    /** Currently-known synced seq (read-through for callers). */
+    get lastSyncedSeq() {
+        return this.highestSyncedSeq;
+    }
+    /**
+     * Buffer an event for the next flush. Returns immediately — the
+     * actual POST happens on the debounce timer.
+     *
+     * The producer (SessionStore) is expected to have ALREADY written
+     * the local NDJSON line before calling this. The dual-write client
+     * never touches the NDJSON itself.
+     */
+    enqueue(event) {
+        if (this.disposed)
+            return;
+        if (!isValidPhase1Kind(event.kind)) {
+            // Quietly ignore events the Phase-1 schema cannot represent. The
+            // local NDJSON keeps them; a future Phase-1.1 may widen the kind
+            // set.
+            return;
+        }
+        if (!Number.isInteger(event.seq) || event.seq <= 0)
+            return;
+        this.buffer.push(event);
+        // Crossed the batch cap — flush eagerly to bound buffer growth.
+        if (this.buffer.length >= this.cfg.maxBatchSize) {
+            this.scheduleFlush(0);
+            return;
+        }
+        this.scheduleFlush(this.cfg.debounceMs);
+    }
+    /**
+     * Force any pending events out. Used at session archive / shutdown
+     * so the trailing batch lands before the process exits.
+     */
+    async flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        return this.doFlush();
+    }
+    /**
+     * Mark the client disposed. Subsequent enqueues are no-ops. Pending
+     * flush is awaited so the caller can `await client.dispose()` to
+     * fence completion.
+     */
+    async dispose() {
+        this.disposed = true;
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        if (this.flushing) {
+            try {
+                await this.flushing;
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    /**
+     * Backlog catch-up. The caller passes the local NDJSON's events
+     * (already filtered to the session) — the client posts any whose
+     * seq > lastSyncedSeq, in order, in batches of maxBatchSize.
+     *
+     * Returns the aggregate FlushResult across all batches (sums
+     * persisted + duplicate counts, lastSeq is the max).
+     */
+    async flushBacklog(allEvents) {
+        const pending = allEvents
+            .filter((e) => e.seq > this.highestSyncedSeq && isValidPhase1Kind(e.kind))
+            .sort((a, b) => a.seq - b.seq);
+        if (pending.length === 0) {
+            return {
+                persistedCount: 0,
+                duplicateCount: 0,
+                lastSeq: this.highestSyncedSeq,
+            };
+        }
+        let totalPersisted = 0;
+        let totalDuplicates = 0;
+        let maxLastSeq = this.highestSyncedSeq;
+        for (let i = 0; i < pending.length; i += this.cfg.maxBatchSize) {
+            const batch = pending.slice(i, i + this.cfg.maxBatchSize);
+            const result = await this.postBatchWithRetry(batch);
+            if (!result)
+                break; // surrender — backlog stays for next session
+            totalPersisted += result.persistedCount;
+            totalDuplicates += result.duplicateCount;
+            maxLastSeq = Math.max(maxLastSeq, result.lastSeq);
+        }
+        return {
+            persistedCount: totalPersisted,
+            duplicateCount: totalDuplicates,
+            lastSeq: maxLastSeq,
+        };
+    }
+    /* ---------------- internal ---------------- */
+    scheduleFlush(delay) {
+        if (this.flushTimer)
+            clearTimeout(this.flushTimer);
+        this.flushTimer = setTimeout(() => {
+            this.flushTimer = null;
+            // doFlush handles its own error swallowing; we drop the floating
+            // promise on the floor on purpose so the timer callback returns
+            // synchronously (Node requires that).
+            void this.doFlush();
+        }, delay);
+    }
+    async doFlush() {
+        if (this.flushing)
+            return this.flushing;
+        if (this.buffer.length === 0)
+            return null;
+        const drained = this.buffer.splice(0, this.buffer.length);
+        this.flushing = this.postBatchWithRetry(drained);
+        try {
+            return await this.flushing;
+        }
+        finally {
+            this.flushing = null;
+        }
+    }
+    async postBatchWithRetry(batch) {
+        if (batch.length === 0)
+            return null;
+        // Sort + within-batch dedup (defence in depth — the server also
+        // enforces monotonic seq + dedup, but enforcing here keeps the
+        // wire payload clean and avoids the 400 on a buggy producer).
+        const sorted = [...batch].sort((a, b) => a.seq - b.seq);
+        const deduped = [];
+        let prevSeq = -1;
+        for (const ev of sorted) {
+            if (ev.seq === prevSeq)
+                continue;
+            deduped.push(ev);
+            prevSeq = ev.seq;
+        }
+        for (let attempt = 1; attempt <= this.cfg.maxRetries; attempt++) {
+            try {
+                const result = await this.doPost(deduped);
+                // Persist the lastSyncedSeq marker so a crash before the next
+                // flush still rediscovers the high-water-mark on restart.
+                if (result.lastSeq > this.highestSyncedSeq) {
+                    this.highestSyncedSeq = result.lastSeq;
+                    try {
+                        writeSyncState(this.cfg.sessionId, this.highestSyncedSeq, this.cfg.stateDir);
+                    }
+                    catch {
+                        // Best effort — a marker write failure does not invalidate
+                        // the on-server data, only the resume hint.
+                    }
+                }
+                return result;
+            }
+            catch (err) {
+                if (attempt === this.cfg.maxRetries) {
+                    // Final surrender — drop the batch silently. Local NDJSON is
+                    // authoritative; the next session resume can replay the gap.
+                    return null;
+                }
+                await sleep(nextBackoffMs(attempt, this.cfg.debounceMs));
+            }
+        }
+        return null;
+    }
+    async doPost(events) {
+        const url = `${this.cfg.apiUrl}/api/pugi/sessions/${encodeURIComponent(this.cfg.sessionId)}/events`;
+        const res = await this.cfg.fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                authorization: `Bearer ${this.cfg.apiKey}`,
+                'content-type': 'application/json',
+                accept: 'application/json',
+            },
+            body: JSON.stringify({ events }),
+        });
+        if (!res.ok) {
+            throw new Error(`dual-write POST ${url} returned ${res.status} ${res.statusText}`);
+        }
+        const body = (await res.json());
+        return {
+            persistedCount: body.persistedCount ?? 0,
+            duplicateCount: body.duplicateCount ?? 0,
+            lastSeq: body.lastSeq ?? 0,
+        };
+    }
+}
+/** Validate a kind string against the Phase-1 closed set. */
+export function isValidPhase1Kind(value) {
+    return PUGI_SESSION_EVENT_KINDS.includes(value);
+}
+/* ------------------------------------------------------------------ */
+/* Kind remap (CLI broad set -> Phase-1 closed set)                   */
+/* ------------------------------------------------------------------ */
+/**
+ * Map the CLI's broader NDJSON kind set to the Phase-1 server-side set.
+ * Returns `null` when the kind has no Phase-1 representation — the
+ * caller should drop that event from the dual-write (the local NDJSON
+ * still carries it for offline analysis).
+ *
+ * The CLI's kind set lives in
+ * `apps/pugi-cli/src/core/repl/store/types.ts`:
+ *
+ *   'user'           -> 'turn.user'
+ *   'persona'        -> 'turn.assistant'
+ *   'system'         -> 'system'
+ *   'tool.start'     -> 'tool.call'
+ *   'tool.result'    -> 'tool.result'
+ *   'agent.spawned'  -> 'dispatch.start'
+ *   'agent.completed'-> 'dispatch.end'
+ *   'compaction'     -> 'compact.boundary'
+ *   'rewind-marker'  -> null  (Phase-1 has no analog yet)
+ */
+export function cliKindToPhase1(cliKind) {
+    switch (cliKind) {
+        case 'user':
+            return 'turn.user';
+        case 'persona':
+            return 'turn.assistant';
+        case 'system':
+            return 'system';
+        case 'tool.start':
+            return 'tool.call';
+        case 'tool.result':
+            return 'tool.result';
+        case 'agent.spawned':
+            return 'dispatch.start';
+        case 'agent.completed':
+            return 'dispatch.end';
+        case 'compaction':
+            return 'compact.boundary';
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=dual-write.js.map

package/dist/core/memory/dual-write.spec.js

@@ -0,0 +1,297 @@
+/**
+ * Pugi CLI dual-write client spec — Memory Phase 1 (2026-05-27).
+ *
+ * Covers:
+ *   1. happy path — single batch posts to /api/pugi/sessions/:id/events
+ *   2. debounce + batch coalesces multiple enqueues into one POST
+ *   3. retry on transient failure with exponential backoff
+ *   4. surrender after maxRetries — local NDJSON stays authoritative
+ *   5. lastSyncedSeq marker is written + persisted across instances
+ *   6. flushBacklog catches up rows with seq > lastSyncedSeq
+ *   7. env kill-switch turns dual-write off
+ *   8. cliKindToPhase1 remap covers every CLI kind
+ *   9. invalid Phase-1 kinds quietly dropped from enqueue
+ *  10. dispose awaits the pending flush
+ */
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import { DualWriteClient, cliKindToPhase1, debounceMsFromEnv, isDualWriteEnabledFromEnv, isValidPhase1Kind, nextBackoffMs, readSyncState, writeSyncState, } from './dual-write.js';
+import { PUGI_SESSION_EVENT_KINDS, } from './phase1-kinds.js';
+let tmpDir = '';
+beforeEach(() => {
+    tmpDir = mkdtempSync(resolve(tmpdir(), 'pugi-dual-write-'));
+});
+afterEach(() => {
+    try {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+    catch {
+        /* ignore */
+    }
+});
+function makeStubFetch(responses) {
+    const calls = [];
+    let i = 0;
+    const fetchImpl = async (input, init) => {
+        const url = typeof input === 'string' ? input : input.toString();
+        const headers = {};
+        if (init?.headers) {
+            const h = init.headers;
+            for (const k of Object.keys(h))
+                headers[k.toLowerCase()] = h[k];
+        }
+        const bodyRaw = typeof init?.body === 'string' ? init.body : '';
+        let body = null;
+        try {
+            body = bodyRaw ? JSON.parse(bodyRaw) : null;
+        }
+        catch {
+            body = bodyRaw;
+        }
+        calls.push({ url, body, headers });
+        const spec = responses[i++] ?? responses[responses.length - 1] ?? { ok: true };
+        if (spec.throw)
+            throw spec.throw;
+        return {
+            ok: spec.ok,
+            status: spec.status ?? (spec.ok ? 200 : 500),
+            statusText: spec.ok ? 'OK' : 'Internal Server Error',
+            json: async () => spec.body ?? {
+                persistedCount: 0,
+                duplicateCount: 0,
+                lastSeq: 0,
+            },
+        };
+    };
+    return { fetchImpl, calls };
+}
+/* --------------------------------------------------------------- */
+/* Pure helpers                                                    */
+/* --------------------------------------------------------------- */
+describe('dual-write: env helpers', () => {
+    it('isDualWriteEnabledFromEnv: defaults to ON', () => {
+        assert.equal(isDualWriteEnabledFromEnv({}), true);
+        assert.equal(isDualWriteEnabledFromEnv({ PUGI_MEMORY_PHASE1_PRISMA_PERSIST_ENABLED: 'true' }), true);
+    });
+    it('isDualWriteEnabledFromEnv: OFF on common false-ish values', () => {
+        assert.equal(isDualWriteEnabledFromEnv({ PUGI_MEMORY_PHASE1_PRISMA_PERSIST_ENABLED: 'false' }), false);
+        assert.equal(isDualWriteEnabledFromEnv({ PUGI_MEMORY_PHASE1_PRISMA_PERSIST_ENABLED: '0' }), false);
+        assert.equal(isDualWriteEnabledFromEnv({ PUGI_MEMORY_PHASE1_PRISMA_PERSIST_ENABLED: 'off' }), false);
+    });
+    it('debounceMsFromEnv: parses + clamps + falls back', () => {
+        assert.equal(debounceMsFromEnv({}), 250);
+        assert.equal(debounceMsFromEnv({ PUGI_MEMORY_DUAL_WRITE_DEBOUNCE_MS: '500' }), 500);
+        // Bogus -> default.
+        assert.equal(debounceMsFromEnv({ PUGI_MEMORY_DUAL_WRITE_DEBOUNCE_MS: 'abc' }), 250);
+        // Negative -> default.
+        assert.equal(debounceMsFromEnv({ PUGI_MEMORY_DUAL_WRITE_DEBOUNCE_MS: '-5' }), 250);
+        // Too large -> default.
+        assert.equal(debounceMsFromEnv({ PUGI_MEMORY_DUAL_WRITE_DEBOUNCE_MS: '120000' }), 250);
+    });
+    it('nextBackoffMs: 1x / 3x / 9x growth', () => {
+        assert.equal(nextBackoffMs(1, 100), 100);
+        assert.equal(nextBackoffMs(2, 100), 300);
+        assert.equal(nextBackoffMs(3, 100), 900);
+    });
+    it('cliKindToPhase1: covers every CLI kind we know about', () => {
+        assert.equal(cliKindToPhase1('user'), 'turn.user');
+        assert.equal(cliKindToPhase1('persona'), 'turn.assistant');
+        assert.equal(cliKindToPhase1('system'), 'system');
+        assert.equal(cliKindToPhase1('tool.start'), 'tool.call');
+        assert.equal(cliKindToPhase1('tool.result'), 'tool.result');
+        assert.equal(cliKindToPhase1('agent.spawned'), 'dispatch.start');
+        assert.equal(cliKindToPhase1('agent.completed'), 'dispatch.end');
+        assert.equal(cliKindToPhase1('compaction'), 'compact.boundary');
+        // rewind-marker and any other -> null (the CLI keeps these in NDJSON only).
+        assert.equal(cliKindToPhase1('rewind-marker'), null);
+        assert.equal(cliKindToPhase1('totally-unknown'), null);
+    });
+    it('isValidPhase1Kind matches the closed set', () => {
+        for (const k of PUGI_SESSION_EVENT_KINDS) {
+            assert.equal(isValidPhase1Kind(k), true);
+        }
+        assert.equal(isValidPhase1Kind('user'), false); // CLI kind, not Phase-1
+        assert.equal(isValidPhase1Kind('nope'), false);
+    });
+});
+/* --------------------------------------------------------------- */
+/* lastSyncedSeq marker                                            */
+/* --------------------------------------------------------------- */
+describe('dual-write: sync state marker', () => {
+    it('reads 0 when no marker on disk', () => {
+        assert.equal(readSyncState('sess-1', tmpDir), 0);
+    });
+    it('writes + reads back monotonic seq', () => {
+        writeSyncState('sess-1', 42, tmpDir);
+        assert.equal(readSyncState('sess-1', tmpDir), 42);
+        writeSyncState('sess-1', 100, tmpDir);
+        assert.equal(readSyncState('sess-1', tmpDir), 100);
+    });
+    it('isolates per-session', () => {
+        writeSyncState('sess-a', 5, tmpDir);
+        writeSyncState('sess-b', 10, tmpDir);
+        assert.equal(readSyncState('sess-a', tmpDir), 5);
+        assert.equal(readSyncState('sess-b', tmpDir), 10);
+    });
+});
+/* --------------------------------------------------------------- */
+/* DualWriteClient end-to-end                                       */
+/* --------------------------------------------------------------- */
+describe('DualWriteClient', () => {
+    it('flushes a single batch on demand', async () => {
+        const { fetchImpl, calls } = makeStubFetch([
+            { ok: true, body: { persistedCount: 2, duplicateCount: 0, lastSeq: 2 } },
+        ]);
+        const client = new DualWriteClient({
+            apiUrl: 'http://localhost',
+            apiKey: 'test-key',
+            sessionId: 'sess-1',
+            fetchImpl,
+            debounceMs: 5,
+            stateDir: tmpDir,
+        });
+        client.enqueue({ seq: 1, kind: 'turn.user', payload: { text: 'hi' } });
+        client.enqueue({ seq: 2, kind: 'turn.assistant', payload: { text: 'hello' } });
+        const result = await client.flush();
+        await client.dispose();
+        assert.equal(calls.length, 1);
+        assert.equal(calls[0].headers['authorization'], 'Bearer test-key');
+        const sentBody = calls[0].body;
+        assert.equal(sentBody.events.length, 2);
+        assert.equal(sentBody.events[0].seq, 1);
+        assert.equal(sentBody.events[1].kind, 'turn.assistant');
+        assert.equal(result?.persistedCount, 2);
+        assert.equal(result?.lastSeq, 2);
+        // Marker persisted.
+        assert.equal(readSyncState('sess-1', tmpDir), 2);
+    });
+    it('retries on transient failure with exponential backoff', async () => {
+        const { fetchImpl, calls } = makeStubFetch([
+            { ok: false, status: 503, body: {} },
+            { ok: false, status: 503, body: {} },
+            { ok: true, body: { persistedCount: 1, duplicateCount: 0, lastSeq: 5 } },
+        ]);
+        const client = new DualWriteClient({
+            apiUrl: 'http://localhost',
+            apiKey: 'k',
+            sessionId: 'sess-r',
+            fetchImpl,
+            debounceMs: 1, // base for backoff -> 1ms / 3ms / 9ms; fast test
+            maxRetries: 3,
+            stateDir: tmpDir,
+        });
+        client.enqueue({ seq: 5, kind: 'turn.user', payload: {} });
+        const result = await client.flush();
+        await client.dispose();
+        assert.equal(calls.length, 3);
+        assert.equal(result?.lastSeq, 5);
+        assert.equal(readSyncState('sess-r', tmpDir), 5);
+    });
+    it('surrenders after maxRetries — local NDJSON stays the truth', async () => {
+        const { fetchImpl, calls } = makeStubFetch([
+            { ok: false, status: 500, body: {} },
+            { ok: false, status: 500, body: {} },
+            { ok: false, status: 500, body: {} },
+        ]);
+        const client = new DualWriteClient({
+            apiUrl: 'http://localhost',
+            apiKey: 'k',
+            sessionId: 'sess-fail',
+            fetchImpl,
+            debounceMs: 1,
+            maxRetries: 3,
+            stateDir: tmpDir,
+        });
+        client.enqueue({ seq: 1, kind: 'turn.user', payload: {} });
+        const result = await client.flush();
+        await client.dispose();
+        assert.equal(calls.length, 3);
+        assert.equal(result, null); // surrender
+        // Marker NOT written — next session retries from zero.
+        assert.equal(readSyncState('sess-fail', tmpDir), 0);
+    });
+    it('drops events whose kind is not in the Phase-1 set', async () => {
+        const { fetchImpl, calls } = makeStubFetch([
+            { ok: true, body: { persistedCount: 1, duplicateCount: 0, lastSeq: 1 } },
+        ]);
+        const client = new DualWriteClient({
+            apiUrl: 'http://localhost',
+            apiKey: 'k',
+            sessionId: 'sess-d',
+            fetchImpl,
+            debounceMs: 5,
+            stateDir: tmpDir,
+        });
+        // The string is broader than Phase-1 — the client filters silently.
+        client.enqueue({ seq: 1, kind: 'rewind-marker', payload: {} });
+        client.enqueue({ seq: 2, kind: 'turn.user', payload: {} });
+        await client.flush();
+        await client.dispose();
+        const sent = calls[0].body;
+        assert.equal(sent.events.length, 1);
+        assert.equal(sent.events[0].seq, 2);
+    });
+    it('flushBacklog skips events <= lastSyncedSeq and posts the rest', async () => {
+        const { fetchImpl, calls } = makeStubFetch([
+            { ok: true, body: { persistedCount: 2, duplicateCount: 0, lastSeq: 10 } },
+        ]);
+        // Seed a marker: last synced was seq=5.
+        writeSyncState('sess-bk', 5, tmpDir);
+        const client = new DualWriteClient({
+            apiUrl: 'http://localhost',
+            apiKey: 'k',
+            sessionId: 'sess-bk',
+            fetchImpl,
+            stateDir: tmpDir,
+        });
+        const allEvents = [
+            { seq: 1, kind: 'turn.user', payload: {} }, // skip
+            { seq: 5, kind: 'turn.assistant', payload: {} }, // skip (<=5)
+            { seq: 7, kind: 'turn.user', payload: {} }, // POST
+            { seq: 10, kind: 'turn.assistant', payload: {} }, // POST
+        ];
+        const result = await client.flushBacklog(allEvents);
+        assert.equal(calls.length, 1);
+        const sent = calls[0].body;
+        assert.equal(sent.events.length, 2);
+        assert.equal(sent.events[0].seq, 7);
+        assert.equal(sent.events[1].seq, 10);
+        assert.equal(result.persistedCount, 2);
+        assert.equal(result.lastSeq, 10);
+        assert.equal(readSyncState('sess-bk', tmpDir), 10);
+        await client.dispose();
+    });
+    it('dispose awaits the in-flight flush', async () => {
+        // Use a fetch that resolves after a tiny delay so the dispose has to
+        // wait.
+        let resolved = false;
+        const fetchImpl = async () => {
+            await new Promise((r) => setTimeout(r, 10));
+            resolved = true;
+            return {
+                ok: true,
+                status: 200,
+                statusText: 'OK',
+                json: async () => ({ persistedCount: 1, duplicateCount: 0, lastSeq: 1 }),
+            };
+        };
+        const client = new DualWriteClient({
+            apiUrl: 'http://localhost',
+            apiKey: 'k',
+            sessionId: 'sess-disp',
+            fetchImpl,
+            debounceMs: 1,
+            stateDir: tmpDir,
+        });
+        client.enqueue({ seq: 1, kind: 'turn.user', payload: {} });
+        // Schedule a flush + immediately dispose; dispose must wait.
+        const flushPromise = client.flush();
+        await client.dispose();
+        await flushPromise;
+        assert.equal(resolved, true);
+    });
+});
+//# sourceMappingURL=dual-write.spec.js.map

package/dist/core/memory/phase1-kinds.js

@@ -0,0 +1,20 @@
+/**
+ * Phase-1 event kind closed set — mirror of
+ * `apps/admin-api/src/pugi-session-events/pugi-session-events.types.ts`
+ * PUGI_SESSION_EVENT_KINDS.
+ *
+ * Kept as a separate file so the CLI does not import from admin-api
+ * (would drag the whole Nest graph). The TWO lists must stay in
+ * lockstep — a new kind requires editing both files.
+ */
+export const PUGI_SESSION_EVENT_KINDS = [
+    'turn.user',
+    'turn.assistant',
+    'tool.call',
+    'tool.result',
+    'dispatch.start',
+    'dispatch.end',
+    'compact.boundary',
+    'system',
+];
+//# sourceMappingURL=phase1-kinds.js.map

package/dist/core/repl/session.js

@@ -580,6 +580,73 @@ export class ReplSession {
     getDispatchState() {
         return this.fsm.current;
     }
+    /**
+     * Wave 6 BT 8 (Claude Code parity): Esc-Esc walkback. Trim the last
+     * operator/persona turn pair from the in-memory transcript so the
+     * model's next call sees the conversation as if the most recent
+     * turn never happened. The local SessionStore still has the events
+     * on disk (append-only); the in-memory mask is advisory and the next
+     * `/compact` boundary will fold them naturally.
+     *
+     * Refusal modes:
+     *   - `'no-turn'`     - transcript has no operator/persona row to pop.
+     *   - `'in-flight'`   - dispatch is mid-flight; popping would race with
+     *                       the streaming persona row. The operator must
+     *                       cancel (Ctrl+C) before walking back.
+     *
+     * Success mode:
+     *   - `'walked-back'` - the trailing persona row + the operator row
+     *                       that triggered it are gone from the transcript.
+     *                       A `↩ walked back 1 turn` status row is appended
+     *                       so the operator sees the state change without
+     *                       guessing.
+     *
+     * The mask is in-memory only on purpose. Disk-side rewind already has
+     * a separate first-class command (`/rewind`) with checkpoint
+     * semantics — the Esc-Esc shortcut is a one-tap "oops, undo that" for
+     * the live transcript, NOT a transactional rollback.
+     */
+    walkbackLastTurn() {
+        // Refuse while a dispatch is running. Popping the operator row that
+        // is currently driving the model's response would leave the persona
+        // line orphaned on the next streamed chunk; the FSM also lacks a
+        // clean teardown path here. The operator gets a one-line refusal
+        // and can Ctrl+C first if they really want to walk back.
+        const current = this.fsm.current;
+        if (current !== 'idle' && current !== 'completed'
+            && current !== 'aborted' && current !== 'failed') {
+            this.appendSystemLine('Walkback refused: dispatch in flight. Cancel with Ctrl+C, then Esc-Esc again.');
+            return 'in-flight';
+        }
+        // Find the trailing operator row. Walking backwards because the
+        // transcript is append-only and the most recent operator turn is
+        // by definition the last `source === 'operator'` row.
+        const transcript = this.state.transcript;
+        let operatorIdx = -1;
+        for (let i = transcript.length - 1; i >= 0; i -= 1) {
+            const row = transcript[i];
+            if (row.source === 'operator') {
+                operatorIdx = i;
+                break;
+            }
+        }
+        if (operatorIdx === -1) {
+            // No operator turn to pop. Quiet refusal — surfacing a "nothing
+            // to undo" line on every accidental double-Esc would be noisy.
+            return 'no-turn';
+        }
+        // Trim everything from the operator row onward (its echo + any
+        // persona/system rows that landed in response). The slice keeps
+        // every row BEFORE the operator turn, which is the conversation
+        // exactly as it stood right before the operator pressed Enter.
+        const trimmed = transcript.slice(0, operatorIdx);
+        this.patch({ transcript: trimmed });
+        // Status row so the operator sees the state change without
+        // guessing. Brand voice: single ASCII line, return-arrow glyph
+        // (U+21A9) which renders across every modern terminal.
+        this.appendSystemLine('↩ walked back 1 turn');
+        return 'walked-back';
+    }
     /**
      * Current cancellation token. Returned for the tool execution path
      * (file-tools.ts) so it can pass the token down into a ToolContext
@@ -1089,7 +1156,38 @@ export class ReplSession {
                 // single-sourced. The session module owns the in-memory
                 // transcript echo (system line + banner row) so the operator
                 // sees the marker land without a fresh REPL bootstrap.
-                await this.dispatchCompact('manual');
+                //
+                // Wave 6 BT 8 (Claude Code parity): `--force` bypasses the
+                // noop-empty guard so the operator can compact even short
+                // sessions (useful before a manual checkpoint).
+                await this.dispatchCompact('manual', { force: verdict.force });
+                return verdict;
+            }
+            case 'model': {
+                // Wave 6 BT 8 (Claude Code parity): /model lists OR selects the
+                // active model. Slash + top-level CLI share `runModelCommand`.
+                // The session module forwards writeOutput → appendSystemLine so
+                // the menu + the confirmation line land inline in the
+                // transcript. Tier override is undefined at the slash surface;
+                // the runner defaults to 'team' so unauthenticated operators
+                // see every model. Server-side calls enforce the real tier cap.
+                try {
+                    const { runModelCommand } = await import('../../runtime/commands/model.js');
+                    await runModelCommand({ slug: verdict.slug }, {
+                        workspaceRoot: process.cwd(),
+                        writeOutput: (line) => {
+                            const trimmed = line.replace(/\n+$/u, '');
+                            if (trimmed.length > 0)
+                                this.appendSystemLine(trimmed);
+                            else
+                                this.appendSystemLine('');
+                        },
+                    });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.appendSystemLine(`/model failed: ${message}`);
+                }
                 return verdict;
             }
             case 'rewind': {
@@ -1442,7 +1540,7 @@ export class ReplSession {
      * `trigger='auto'` for the threshold gate. The runner records the
      * trigger in the marker payload so the banner can distinguish them.
      */
-    async dispatchCompact(trigger) {
+    async dispatchCompact(trigger, options = {}) {
         if (!this.store || !this.localSessionId) {
             this.appendSystemLine('Local session store is disabled — /compact is unavailable.');
             return;
@@ -1454,6 +1552,7 @@ export class ReplSession {
                 sessionId: this.localSessionId,
                 store: this.store,
                 trigger,
+                force: options.force === true,
                 writeOutput: (_payload, text) => {
                     if (text.length > 0)
                         this.appendSystemLine(text);

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

@@ -65,7 +65,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'clear', args: '', gloss: 'Clear conversation pane', group: 'Session' },
     { name: 'resume', args: '', gloss: 'Pick a stored session to restore', group: 'Session' },
     { name: 'context', args: '', gloss: 'Show three-tier context summary (Tier 0 skeleton + Tier 1 working set)', group: 'Session' },
-    { name: 'compact', args: '', gloss: 'Summarise older turns into a boundary marker (leak L8)', group: 'Session' },
+    { name: 'compact', args: '[--force]', gloss: 'Summarise older turns into a boundary marker (leak L8). --force bypasses the noop-empty guard', group: 'Session' },
     { name: 'rewind', args: '[N | --to <id>]', gloss: 'Roll the conversation back to a checkpoint (leak L9)', group: 'Session' },
     { name: 'memory', args: '', gloss: 'Session memory editor  (α6.5b)', group: 'Session', stub: true },
     { name: 'init', args: '', gloss: 'Scaffold .pugi/ in the current workspace (β1 Sl11)', group: 'Session' },
@@ -82,6 +82,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'privacy', args: '', gloss: 'Show privacy mode + contract', group: 'Settings' },
     { name: 'permissions', args: '[mode] [--persist]', gloss: 'Show or flip permission mode (plan / ask / allow / bypass)  (also: /plan)', group: 'Settings' },
     { name: 'plan', args: '[--back | --persist] [<prompt>]', gloss: 'Switch to plan mode (read-only). Same as /permissions plan, slicker UX.', group: 'Settings' },
+    { name: 'model', args: '[<slug>]', gloss: 'Show or select the active model. Bare /model lists tier-gated options', group: 'Settings' },
     { name: 'budget', args: '', gloss: 'Show usage budget', group: 'Settings', stub: true },
     { name: 'mcp', args: '[sub]', gloss: 'MCP servers — list / trust / deny / install / serve / perms', group: 'Settings' },
     { name: 'style', args: '[name] [--persist|--reset|--list]', gloss: 'Output-style preset (default / terse / explanatory / russian-formal / casual)', group: 'Settings' },
@@ -379,6 +380,27 @@ export function parseSlashCommand(input) {
             }
             return { kind: 'plan', back, persist, autoBack, prompt };
         }
+        case 'model': {
+            // Wave 6 BT 8 (Claude Code parity): `/model [<slug>]`. Bare form
+            // prints the tier-gated model menu + current selection; with a
+            // slug it flips workspace selection. Slug grammar (loose): alnum
+            // + dash + dot + slash. Anything outside that range becomes an
+            // error verdict so the operator sees a clear message instead of a
+            // silent no-op. Whitespace inside the tail = multiple tokens = we
+            // take the first; the help gloss documents single-slug usage.
+            const trimmedTail = tail.trim();
+            if (trimmedTail.length === 0) {
+                return { kind: 'model', slug: undefined };
+            }
+            const firstToken = trimmedTail.split(/\s+/)[0] ?? '';
+            if (!/^[A-Za-z0-9][A-Za-z0-9._\-\/]{0,63}$/.test(firstToken)) {
+                return {
+                    kind: 'error',
+                    message: `/model: invalid slug '${firstToken}'. Use letters / digits / '-' / '.' / '/' only.`,
+                };
+            }
+            return { kind: 'model', slug: firstToken };
+        }
         case 'mcp': {
             // β4 Sl7: tokenize the tail. Empty tail -> `list` (matches CLI).
             // Quoting / shell-escapes are NOT supported — the slash surface is
@@ -453,11 +475,14 @@ export function parseSlashCommand(input) {
         }
         case 'compact': {
             // Leak L8 (2026-05-27): graduated from stub. The session module
-            // owns the summariser round-trip; tail args are ignored today
-            // because the surface is parameterless. Operators wanting a
+            // owns the summariser round-trip. Wave 6 BT 8: `--force` overrides
+            // the noop-empty guard. Unknown flags fall through silently per
+            // the existing tail-tolerance behaviour (operators wanting a
             // per-session compact run `pugi compact --session <id>` from a
-            // fresh shell.
-            return { kind: 'compact' };
+            // fresh shell).
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            const force = tokens.some((t) => t === '--force' || t === '-f');
+            return { kind: 'compact', force };
         }
         case 'rewind': {
             // Leak L9 (2026-05-27): `/rewind [N | --to <id>]`. Tokenize the

package/dist/runtime/cli.js

@@ -644,9 +644,14 @@ async function dispatchUndo(args, flags, session) {
  * sourced.
  */
 async function dispatchCompact(args, flags, _session) {
+    // Wave 6 BT 8 (Claude Code parity): parse `--force` / `-f` so the
+    // operator can produce a marker against a short session. Auto-trigger
+    // paths never pass this flag — only the explicit CLI / slash invocation.
+    const force = args.some((t) => t === '--force' || t === '-f');
     const result = await runCompactCommand(args, {
         workspaceRoot: process.cwd(),
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        force,
     });
     if (result.status === 'failed_no_session'
         || result.status === 'failed_transport'

package/dist/runtime/commands/compact.js

@@ -88,13 +88,14 @@ export async function runCompactCommand(_args, ctx) {
             reason: `Could not load events: ${errMsg(error)}`,
         });
     }
-    if (events.length < MIN_EVENTS_TO_COMPACT) {
+    if (events.length < MIN_EVENTS_TO_COMPACT && ctx.force !== true) {
         return emit(ctx, {
             command: 'compact',
             status: 'noop_empty',
             sessionId,
             trigger,
-            reason: `Only ${events.length} events on disk; need at least ${MIN_EVENTS_TO_COMPACT}.`,
+            reason: `Only ${events.length} events on disk; need at least ${MIN_EVENTS_TO_COMPACT}. `
+                + 'Pass --force to compact anyway.',
         });
     }
     // Locate the source slice: everything strictly after the latest

package/dist/runtime/commands/model.js

@@ -0,0 +1,237 @@
+/**
+ * `/model` / `pugi model` — Wave 6 BT 8 (Claude Code parity).
+ *
+ * Lists OR selects the active model. The MVP uses a hardcoded
+ * tier-aware registry mirrored from the per-model price ladder in
+ * `core/repl/model-pricing.ts` so the operator sees the same models
+ * the cost meter understands. A future iteration can swap the static
+ * registry for an admin-api `GET /api/pugi/models` round-trip — the
+ * runner contract (`MODEL_REGISTRY` + `runModelCommand`) is the right
+ * shape for that swap because the renderer + writer paths are
+ * decoupled from the source.
+ *
+ * Persistence lands at `<workspaceRoot>/.pugi/settings.json` under a
+ * top-level `model.slug` key. We extend the file directly with a
+ * round-trip read-merge-write so we do not invalidate the existing
+ * Zod schema in `core/settings.ts` — the schema there reads only the
+ * keys it knows about, leaving `model.*` as a forward-compatible
+ * passthrough.
+ *
+ * Tier gating mirrors the four-tier pricing (Free / Founder $20 /
+ * Builder $99 / Team $199). The slugs here are the same ones the
+ * cost meter renders, so the operator can always swap to a cheaper
+ * fallback if they hit a quota wall.
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+/**
+ * Tier rank for comparing "user tier >= model.minTier". The order is
+ * Free < Founder < Builder < Team. The cabinet's pricing module owns
+ * the canonical pricing copy; the CLI just needs the rank to filter
+ * the menu.
+ */
+export const TIER_RANK = Object.freeze({
+    free: 0,
+    founder: 1,
+    builder: 2,
+    team: 3,
+});
+/**
+ * Static model registry. Sources:
+ *   - Anthropic Claude family (claude-opus, claude-sonnet, claude-haiku):
+ *     2026-05-26 list prices.
+ *   - OpenAI (gpt-4o, gpt-4o-mini, o3, o3-mini): 2026-05-26 list prices.
+ *   - Mistral (mistral-large, mistral-small): 2026-05-26 list prices.
+ *
+ * Family fallbacks (`claude-opus-4-7` falling back onto the
+ * `claude-opus-` family entry in `model-pricing.ts`) live in the price
+ * ladder, not here — the registry is the canonical selectable surface.
+ */
+export const MODEL_REGISTRY = Object.freeze([
+    // Free tier — cheap defaults so the meter never blanks on a fresh signup.
+    {
+        slug: 'claude-haiku-4-5',
+        label: 'Claude Haiku 4.5',
+        minTier: 'free',
+        inputUsdPerM: 0.8,
+        outputUsdPerM: 4.0,
+        summary: 'Fast + cheap. Default for quick dispatches and the free tier.',
+    },
+    {
+        slug: 'gpt-4o-mini',
+        label: 'GPT-4o mini',
+        minTier: 'free',
+        inputUsdPerM: 0.15,
+        outputUsdPerM: 0.6,
+        summary: 'Cheapest mainstream model. Good for short turns.',
+    },
+    // Founder ($20) — mid-tier mainstream models.
+    {
+        slug: 'claude-sonnet-4-6',
+        label: 'Claude Sonnet 4.6',
+        minTier: 'founder',
+        inputUsdPerM: 3.0,
+        outputUsdPerM: 15.0,
+        summary: 'Balanced for code dispatch. Strong tool use.',
+    },
+    {
+        slug: 'gpt-4o',
+        label: 'GPT-4o',
+        minTier: 'founder',
+        inputUsdPerM: 2.5,
+        outputUsdPerM: 10.0,
+        summary: 'Multimodal-capable. Good general-purpose flagship.',
+    },
+    // Builder ($99) — mid-strong reasoning + Mistral options.
+    {
+        slug: 'o3-mini',
+        label: 'OpenAI o3-mini',
+        minTier: 'builder',
+        inputUsdPerM: 1.1,
+        outputUsdPerM: 4.4,
+        summary: 'Cheaper reasoning. Good for plan/review turns.',
+    },
+    {
+        slug: 'mistral-large',
+        label: 'Mistral Large',
+        minTier: 'builder',
+        inputUsdPerM: 2.0,
+        outputUsdPerM: 6.0,
+        summary: 'Strong open-weight reasoning. EU-hosted option.',
+    },
+    // Team ($199) — top-tier reasoning.
+    {
+        slug: 'claude-opus-4-7',
+        label: 'Claude Opus 4.7',
+        minTier: 'team',
+        inputUsdPerM: 15.0,
+        outputUsdPerM: 75.0,
+        summary: 'Flagship reasoning. Best for hard refactors + multi-file edits.',
+    },
+    {
+        slug: 'o3',
+        label: 'OpenAI o3',
+        minTier: 'team',
+        inputUsdPerM: 10.0,
+        outputUsdPerM: 40.0,
+        summary: 'Strong reasoning + deliberation. Good for plan/critique loops.',
+    },
+]);
+/** Returns the registry filtered to models the operator's tier can use. */
+export function modelsForTier(tier) {
+    const rank = TIER_RANK[tier];
+    return MODEL_REGISTRY.filter((m) => TIER_RANK[m.minTier] <= rank);
+}
+/** Looks up a descriptor by slug. */
+export function lookupModel(slug) {
+    return MODEL_REGISTRY.find((m) => m.slug === slug);
+}
+/**
+ * Entry point for the slash + the top-level CLI. Side effects:
+ *   - command.slug undefined: prints the tier-gated menu + current row.
+ *   - command.slug set + unknown: prints a one-line error.
+ *   - command.slug set + above tier: prints a tier-lock message.
+ *   - command.slug set + valid + reachable: merges `model.slug` into
+ *     <workspaceRoot>/.pugi/settings.json and prints a confirmation.
+ *
+ * The function never throws on a missing settings file — it creates
+ * `.pugi/` + writes a fresh object. Read failures (malformed JSON) are
+ * surfaced as a system line + the runner refuses to write so the
+ * operator can recover by hand.
+ */
+export async function runModelCommand(command, ctx) {
+    const tier = ctx.tier ?? 'team';
+    const fs = ctx.fs ?? defaultFs(ctx.workspaceRoot);
+    if (command.slug === undefined) {
+        return renderMenu(ctx, fs, tier);
+    }
+    const descriptor = lookupModel(command.slug);
+    if (!descriptor) {
+        ctx.writeOutput(`/model: unknown slug '${command.slug}'. Run /model to see the menu.`);
+        return { command: 'model', status: 'unknown_slug', reason: command.slug };
+    }
+    if (TIER_RANK[descriptor.minTier] > TIER_RANK[tier]) {
+        ctx.writeOutput(`/model: '${descriptor.slug}' requires the ${descriptor.minTier} tier. `
+            + `You are on '${tier}'. Run /model to see available options.`);
+        return { command: 'model', status: 'tier_locked', slug: descriptor.slug };
+    }
+    // Merge + persist. Any IO error becomes a one-line warning; the
+    // session continues without crashing.
+    try {
+        const current = fs.readSettings() ?? {};
+        const nextSettings = {
+            ...current,
+            model: {
+                ...(typeof current.model === 'object' && current.model !== null
+                    ? current.model
+                    : {}),
+                slug: descriptor.slug,
+            },
+        };
+        fs.writeSettings(nextSettings);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.writeOutput(`/model: persist failed — ${message}. Selection is session-only.`);
+    }
+    ctx.writeOutput(`Model set to '${descriptor.label}' (${descriptor.slug}). ` +
+        `Cost: $${descriptor.inputUsdPerM.toFixed(2)}/M in, $${descriptor.outputUsdPerM.toFixed(2)}/M out.`);
+    return { command: 'model', status: 'selected', slug: descriptor.slug };
+}
+function renderMenu(ctx, fs, tier) {
+    const current = readCurrentSlug(fs);
+    const visible = modelsForTier(tier);
+    ctx.writeOutput(`Current model: ${current ?? '(unset, default)'}.  Your tier: ${tier}.`);
+    ctx.writeOutput('');
+    ctx.writeOutput('Available models:');
+    for (const m of visible) {
+        const mark = current === m.slug ? '*' : ' ';
+        const price = `$${m.inputUsdPerM.toFixed(2)}/M in, $${m.outputUsdPerM.toFixed(2)}/M out`;
+        ctx.writeOutput(`  ${mark} ${m.slug.padEnd(22)}  ${m.label.padEnd(22)}  ${price}`);
+        ctx.writeOutput(`    ${m.summary}`);
+    }
+    const locked = MODEL_REGISTRY.filter((m) => TIER_RANK[m.minTier] > TIER_RANK[tier]);
+    if (locked.length > 0) {
+        ctx.writeOutput('');
+        ctx.writeOutput(`Higher-tier models (upgrade required):`);
+        for (const m of locked) {
+            ctx.writeOutput(`  - ${m.slug} (${m.minTier})`);
+        }
+    }
+    ctx.writeOutput('');
+    ctx.writeOutput('Switch with `/model <slug>`. The choice persists to .pugi/settings.json.');
+    return { command: 'model', status: 'listed', slug: current ?? undefined };
+}
+function readCurrentSlug(fs) {
+    try {
+        const data = fs.readSettings();
+        if (!data || typeof data !== 'object')
+            return null;
+        const model = data.model;
+        if (!model || typeof model !== 'object')
+            return null;
+        const slug = model.slug;
+        return typeof slug === 'string' && slug.length > 0 ? slug : null;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultFs(workspaceRoot) {
+    const path = resolve(workspaceRoot, '.pugi/settings.json');
+    return {
+        readSettings: () => {
+            if (!existsSync(path))
+                return null;
+            const raw = readFileSync(path, 'utf8');
+            if (raw.trim().length === 0)
+                return null;
+            return JSON.parse(raw);
+        },
+        writeSettings: (next) => {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, JSON.stringify(next, null, 2) + '\n', 'utf8');
+        },
+    };
+}
+//# sourceMappingURL=model.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.29');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.30');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/dist/tui/input-box.js

@@ -33,6 +33,14 @@ import { SlashPalette, completePalette, filterPalette, } from './slash-palette.j
 import { EMPTY_KILL_RING, killToLineEnd, killToLineStart, killWordBackward, yankAtCursor, } from '../core/repl/kill-ring.js';
 import { readClipboard } from '../core/repl/clipboard-read.js';
 const CTRL_C_DOUBLE_TAP_MS = 1_000;
+/**
+ * Wave 6 BT 8 (Claude Code parity): Esc-Esc walks the conversation back
+ * one turn. 500ms is tight enough that an operator clearing the buffer +
+ * later changing their mind does NOT accidentally pop a turn, while
+ * still feeling like one motion. Matches Claude Code's documented
+ * double-Esc window.
+ */
+const ESCAPE_DOUBLE_TAP_MS = 500;
 /** Width subtracted from the terminal width so the border + padding fit. */
 const FRAME_OVERHEAD_COLUMNS = 4;
 /** Fallback width when ink cannot read stdout (e.g. test harness). */
@@ -75,6 +83,11 @@ export function InputBox(props) {
     const [history, setHistory] = useState(seededHistory);
     const [historyIndex, setHistoryIndex] = useState(-1);
     const [lastCtrlCAt, setLastCtrlCAt] = useState(undefined);
+    // Wave 6 BT 8: Esc-Esc walkback double-tap window. Tracks the epoch
+    // ms of the most recent Esc press so the next Esc within
+    // ESCAPE_DOUBLE_TAP_MS triggers the walkback handler instead of
+    // re-clearing the buffer.
+    const [lastEscapeAt, setLastEscapeAt] = useState(undefined);
     const [cursorVisible, setCursorVisible] = useState(true);
     // Ctrl+R / Ctrl+S reverse-search mode. Undefined when idle, a
     // HistorySearchState while the operator is searching.
@@ -375,10 +388,41 @@ export function InputBox(props) {
         if (key.escape) {
             if (paletteOpen) {
                 // Close the palette without clearing the buffer so the operator
-                // can still send `/help` as plain text if they want.
+                // can still send `/help` as plain text if they want. Palette
+                // takes precedence over walkback because the operator's mental
+                // model is "Esc closes the visible overlay first".
                 setPaletteSuppressed(true);
+                setLastEscapeAt(undefined);
+                return;
+            }
+            // Wave 6 BT 8: Esc-Esc walkback. Two presses within
+            // ESCAPE_DOUBLE_TAP_MS step the conversation back by one turn.
+            // First press still clears the buffer (legacy behaviour for the
+            // single-Esc cancel UX); the second press calls the host's
+            // walkback handler. Buffer-clear on the first press is what makes
+            // the double-tap feel "free" - the operator did not have to
+            // memorise a new chord; they just have to keep pressing.
+            const tEsc = now();
+            const withinEscapeWindow = typeof lastEscapeAt === 'number'
+                && tEsc - lastEscapeAt <= ESCAPE_DOUBLE_TAP_MS;
+            if (withinEscapeWindow && props.onWalkback) {
+                // Second tap inside the window. Buffer was already cleared on
+                // the first press, so the host sees a clean input box AND the
+                // walkback result. We clear the window so a third tap restarts
+                // the cycle (no run-on walkbacks from a stuck Esc key).
+                const verdict = props.onWalkback();
+                setLastEscapeAt(undefined);
+                if (verdict !== 'walked-back') {
+                    // Host refused (dispatch in flight, no turns to pop). The
+                    // host owns the refusal copy via its own writeOutput path;
+                    // we do not double-message here.
+                    return;
+                }
                 return;
             }
+            // First Esc (or no walkback wired). Arm the window + clear the
+            // buffer per the long-standing single-Esc cancel contract.
+            setLastEscapeAt(tEsc);
             setLine('');
             setCursor(0);
             setHistoryIndex(-1);

package/dist/tui/repl.js

@@ -184,6 +184,18 @@ export function Repl(props) {
             return undefined;
         return props.session.cancel();
     }, [props.session, modalActive]);
+    // Wave 6 BT 8 (Claude Code parity): Esc-Esc walkback. Forwards to
+    // ReplSession.walkbackLastTurn which trims the trailing operator
+    // turn + its persona response from the in-memory transcript. Returns
+    // `'walked-back'` so the input box knows the host did the work;
+    // `'nothing'` covers both the empty-transcript and dispatch-in-flight
+    // refusals (the session module owns the refusal copy in both cases).
+    const handleWalkback = useCallback(() => {
+        if (modalActive)
+            return 'nothing';
+        const verdict = props.session.walkbackLastTurn();
+        return verdict === 'walked-back' ? 'walked-back' : 'nothing';
+    }, [props.session, modalActive]);
     // α6.14.5 CEO dogfood 2026-05-25 (parity with Claude Code): input
     // box pinned to alt-screen BOTTOM, conversation grows above it.
     // Beta.3's height={rows} fix broke keystroke focus - raw echo at
@@ -192,7 +204,7 @@ export function Repl(props) {
     // input, and the input stays the sole focusable surface adjacent
     // to the cursor row, so all keystrokes route through it.
     const altScreenRows = process.stdout.rows ?? 24;
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, minHeight: altScreenRows, children: [props.updateBanner ? _jsx(UpdateBanner, { result: props.updateBanner }) : null, splashVisible ? (_jsx(ReplSplash, { cliVersion: state.cliVersion, workspaceLabel: state.workspaceLabel, plan: props.splashPlan, model: props.splashModel, tenant: props.splashTenant, onDismiss: dismissSplash, mascotPrePrinted: props.mascotPrePrinted === true })) : null, _jsx(Header, { state: state }), _jsx(Box, { flexDirection: "column", marginTop: 1, flexGrow: 1, justifyContent: "flex-end", children: overlay === 'help' ? (_jsx(HelpOverlay, {})) : overlay === 'roster' ? (_jsx(RosterOverlay, {})) : overlay === 'farewell' ? (_jsx(FarewellOverlay, {})) : (_jsx(MainArea, { state: state, personaNames: personaNames, nowEpochMs: tickNow, hideToolStream: props.hideToolStream === true, toolStreamCollapsed: toolStreamCollapsed })) }), state.pendingAsk ? (_jsx(Box, { marginTop: 1, children: _jsx(AskModal, { tag: state.pendingAsk, onResolve: handleAskResolve }) })) : null, state.pendingPlanReview ? (_jsx(Box, { marginTop: 1, children: _jsx(PlanReviewModal, { tag: state.pendingPlanReview, onResolve: handlePlanReviewResolve }) })) : null, _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [overlay === 'farewell' || modalActive ? null : (_jsx(InputBox, { onSubmit: handleSubmit, onExit: handleExit, onCancel: handleCancel, now: props.now, 
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, minHeight: altScreenRows, children: [props.updateBanner ? _jsx(UpdateBanner, { result: props.updateBanner }) : null, splashVisible ? (_jsx(ReplSplash, { cliVersion: state.cliVersion, workspaceLabel: state.workspaceLabel, plan: props.splashPlan, model: props.splashModel, tenant: props.splashTenant, onDismiss: dismissSplash, mascotPrePrinted: props.mascotPrePrinted === true })) : null, _jsx(Header, { state: state }), _jsx(Box, { flexDirection: "column", marginTop: 1, flexGrow: 1, justifyContent: "flex-end", children: overlay === 'help' ? (_jsx(HelpOverlay, {})) : overlay === 'roster' ? (_jsx(RosterOverlay, {})) : overlay === 'farewell' ? (_jsx(FarewellOverlay, {})) : (_jsx(MainArea, { state: state, personaNames: personaNames, nowEpochMs: tickNow, hideToolStream: props.hideToolStream === true, toolStreamCollapsed: toolStreamCollapsed })) }), state.pendingAsk ? (_jsx(Box, { marginTop: 1, children: _jsx(AskModal, { tag: state.pendingAsk, onResolve: handleAskResolve }) })) : null, state.pendingPlanReview ? (_jsx(Box, { marginTop: 1, children: _jsx(PlanReviewModal, { tag: state.pendingPlanReview, onResolve: handlePlanReviewResolve }) })) : null, _jsxs(Box, { flexDirection: "column", marginTop: 1, children: [overlay === 'farewell' || modalActive ? null : (_jsx(InputBox, { onSubmit: handleSubmit, onExit: handleExit, onCancel: handleCancel, onWalkback: handleWalkback, now: props.now, 
                         // Slug from process.cwd() (full path) so two workspaces with
                         // the same basename do not share history. state.workspaceLabel
                         // is the basename only. Codex review P2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-beta.29",
+  "version": "0.1.0-beta.30",
   "description": "Pugi CLI - terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -54,7 +54,7 @@
     "undici": "^8.3.0",
     "zod": "^3.23.0",
     "@pugi/personas": "0.1.2",
-    "@pugi/sdk": "0.1.0-beta.29"
+    "@pugi/sdk": "0.1.0-beta.30"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",