klyro 1.0.8 → 1.0.10

package/READ.md

@@ -1,6 +1,6 @@
 # Klyro — Complete Build Documentation
 
-**For any coding agent:** This file is the single source of truth for what has been built till now (current version: see `package.json` — v1.0.8; Levels 1-9 complete, Level 10 largely complete incl. MCP/hooks/sub-agents, 34 built-in tools incl. `web_fetch`/`web_search`). The §20 ledger below is the historical record (v0.1.39→v0.1.61); version/test-count numbers inside it are point-in-time, not current. After reading, you have the complete picture.
+**For any coding agent:** This file is the single source of truth for what has been built till now (current version: see `package.json` — v1.0.9; Levels 1-9 complete, Level 10 largely complete incl. MCP/hooks/sub-agents, 34 built-in tools incl. `web_fetch`/`web_search`, cross-turn session memory in the TUI REPL). The section-20 ledger below is the historical record (v0.1.39→v0.1.61); version/test-count numbers inside it are point-in-time, not current. After reading, you have the complete picture.
 
 ---
 
@@ -27,8 +27,8 @@
 | Test | `vitest 4.1` `fileParallelism:false` `10s timeout` | `node` env, deterministic mocks |
 | Build | `tsc` (not `tsup`) | `tsc --noEmit` `typecheck`, `tsc` `build` |
 | Providers | Native `fetch` (Node 20) | No SDK lock-in, 3 adapters |
-| Workspace | `pnpm-workspace.yaml` `packages/*` | `shared` `KlyroError` |
-| CI | `.github/workflows/ci.yml` `ubuntu/macos/windows × 20/22` | `pnpm install` `typecheck` `test` `build` `pack` |
+| Workspace | `packages/shared` (private, legacy, unused) | Canonical npm + `package-lock.json`; `pnpm-workspace.yaml` ignored by npm |
+| CI | `.github/workflows/ci.yml` `ubuntu/macos/windows × 20/22` | `npm ci` `typecheck` `test` `build` gating smoke + `release-check` + `pack` |
 
 **No Docker, no MCP, no browser in MVP** — deferred to post-1.0.
 
@@ -163,8 +163,7 @@ Eval: FileFixture {dir, task.md, check.sh, meta.json} loadFileFixture() src/eval
 
 ```
 klyro/
-├── package.json                 # klyro 0.1.15, bin klyro/ky, files [dist], commander/ink/zod
-├── pnpm-workspace.yaml          # packages/*
+├── package.json                 # klyro 0.1.15, bin klyro/ky, files [dist], commander/ink/zod (canonical npm + package-lock.json; legacy pnpm workspace removed)
 ├── tsconfig.json                # ES2022, NodeNext, strict, noUncheckedIndexedAccess
 ├── vitest.config.ts             # include src/**/*.test, fileParallelism:false
 ├── .github/workflows/ci.yml     # ubuntu/macos/windows × 20/22 → typecheck/test/build/eval smoke

package/dist/agent/runtime.js

@@ -287,6 +287,12 @@ export async function run(opts, deps) {
     // 5.2 — stuck detection state
     const callHistory = [];
     const fileEditCounts = new Map();
+    // Exactly-once: a provider transport retry (or a resume replay) must never
+    // re-execute a tool call whose side effect already completed. Completed
+    // call ids map to their recorded observations; a repeated id re-commits
+    // the cached observation without touching tools, hooks, or the audit log
+    // a second time.
+    const completedToolCalls = new Map();
     let stuckTriggers = 0;
     let stuckAbort = false;
     // Steerable stop: a stop hook's `{"continue":true}` verdict carries one
@@ -1081,7 +1087,7 @@ export async function run(opts, deps) {
         };
         // Commit phase: fold one execution result into the transcript, in original
         // call order. The only writer — call sequentially, never concurrently.
-        const commitResult = async (call, obs, latencyMs, hookContext = []) => {
+        const commitResult = async (call, obs, latencyMs, hookContext = [], replay = false) => {
             const output = obs.ok ? redactOutput(obs.value) : redactOutput({ error: obs.error });
             const toolMsg = {
                 role: 'tool',
@@ -1089,6 +1095,14 @@ export async function run(opts, deps) {
             };
             transcript.push(toolMsg);
             await checkpoint(toolMsg, { toolCallId: call.id, toolName: call.name, input: call.input, output, isError: !obs.ok });
+            if (replay) {
+                // Replay of an already-completed id (transport retry / resume):
+                // transcript continuity only. No telemetry, audit, snapshots, stuck
+                // accounting, or hooks — the side effect happened exactly once.
+                emitKlyro({ type: 'tool.result', ts: Date.now(), sessionId: sessionId ?? 'ephemeral', callId: call.id, name: call.name, output, isError: !obs.ok, latencyMs });
+                emit?.({ kind: 'tool_result', id: call.id, name: call.name, output, isError: !obs.ok, latencyMs });
+                return;
+            }
             // Hook-injected context rides as its own user message right after the
             // tool result (uniform across output shapes — no result surgery).
             if (hookContext.length > 0) {
@@ -1177,9 +1191,18 @@ export async function run(opts, deps) {
                     }
                 }
             }
+            // Exactly-once record: a later turn repeating this id (transport retry
+            // replay or resume) re-commits the cached observation instead of
+            // re-executing.
+            completedToolCalls.set(call.id, { obs, latencyMs });
         };
         // Sequential path: gate → execute → commit per call, in order.
         const runOne = async (call) => {
+            const cached = completedToolCalls.get(call.id);
+            if (cached) {
+                await commitResult(call, cached.obs, cached.latencyMs, [], true);
+                return;
+            }
             if (!(await gateCall(call)))
                 return;
             const { obs, latencyMs, hookContext } = await execTool(call);
@@ -1194,6 +1217,12 @@ export async function run(opts, deps) {
             const approved = [];
             for (const call of finalizedCalls) {
                 toolCallCount++;
+                // Exactly-once: replay cached observation without gate/hooks/exec.
+                const cached = completedToolCalls.get(call.id);
+                if (cached) {
+                    await commitResult(call, cached.obs, cached.latencyMs, [], true);
+                    continue;
+                }
                 if (await gateCall(call))
                     approved.push(call);
                 if (opts.signal?.aborted)

package/dist/chat.d.ts

@@ -1,4 +1,12 @@
 /**
+ * COMPATIBILITY-ONLY legacy one-shot chat. Prefer `klyro run` / `klyro tui`.
+ *
+ * Security contract (shared with all current paths — do NOT diverge):
+ *   base-URL validation via assertSafeBaseURL, error-body caps via
+ *   MAX_ERROR_BODY_BYTES, and credential handling owned by providers.ts.
+ *   Covered by src/providers/contract.test.ts; any change here must update
+ *   the contract tests first.
+ *
  * One-shot chat. POSTs to an OpenAI-compatible /v1/chat/completions endpoint
  * and streams the response to stdout.
  *

package/dist/chat.js

@@ -1,4 +1,12 @@
 /**
+ * COMPATIBILITY-ONLY legacy one-shot chat. Prefer `klyro run` / `klyro tui`.
+ *
+ * Security contract (shared with all current paths — do NOT diverge):
+ *   base-URL validation via assertSafeBaseURL, error-body caps via
+ *   MAX_ERROR_BODY_BYTES, and credential handling owned by providers.ts.
+ *   Covered by src/providers/contract.test.ts; any change here must update
+ *   the contract tests first.
+ *
  * One-shot chat. POSTs to an OpenAI-compatible /v1/chat/completions endpoint
  * and streams the response to stdout.
  *

package/dist/checkpoints/store.js

@@ -86,12 +86,21 @@ export async function snapshot(cwd, files) {
                 missing.push(f);
         }
     }
-    // Save meta (fsync before the checkpoint is visible — mirrors the
-    // SessionStore.writeIndex atomic pattern).
+    // Save meta (tmp + fsync + rename before the checkpoint is visible —
+    // mirrors the SessionStore.writeIndex atomic pattern so a crash never
+    // leaves a truncated .meta.json that undo() then trusts).
     const metaPath = path.join(dest, '.meta.json');
-    await fs.writeFile(metaPath, JSON.stringify({ id, files: kept, missing, ts: Date.now() }, null, 2));
-    lockDown(metaPath, 0o600);
-    await fsyncFile(metaPath);
+    const metaTmp = `${metaPath}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    await fs.writeFile(metaTmp, JSON.stringify({ id, files: kept, missing, ts: Date.now() }, null, 2));
+    lockDown(metaTmp, 0o600);
+    await fsyncFile(metaTmp);
+    try {
+        await fs.rename(metaTmp, metaPath);
+    }
+    catch {
+        await fs.unlink(metaTmp).catch(() => undefined);
+        throw new Error(`Failed to write checkpoint meta ${id}`);
+    }
     // Best-effort last.diff for the repair guard (guardRepair reads it).
     try {
         const { spawn } = await import('node:child_process');
@@ -130,11 +139,21 @@ export async function snapshot(cwd, files) {
             });
         });
         if (diffText) {
-            await fs.writeFile(path.join(dir, 'last.diff'), diffText, 'utf-8');
+            const atomicWrite = async (p, data) => {
+                const tmp = `${p}.tmp-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+                await fs.writeFile(tmp, data, 'utf-8');
+                try {
+                    await fs.rename(tmp, p);
+                }
+                catch {
+                    await fs.unlink(tmp).catch(() => undefined);
+                }
+            };
+            await atomicWrite(path.join(dir, 'last.diff'), diffText);
             // Per-checkpoint diff file (best-effort); the repair guard keeps
             // reading last.diff, so its behavior is unchanged.
             try {
-                await fs.writeFile(path.join(dir, `${id}.diff`), diffText, 'utf-8');
+                await atomicWrite(path.join(dir, `${id}.diff`), diffText);
             }
             catch { /* best-effort only */ }
         }

package/dist/cli/args.d.ts

@@ -0,0 +1 @@
+export declare function parsePositiveInt(name: string, v: string): number;

package/dist/cli/args.js

@@ -0,0 +1,14 @@
+/**
+ * Shared CLI argument coercions (extracted from src/index.ts).
+ *
+ * Single source of truth for Commander option parsing so command modules
+ * registered from src/cli/* behave identically to the entrypoint.
+ */
+import { InvalidArgumentError } from 'commander';
+export function parsePositiveInt(name, v) {
+    const n = Number(v);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new InvalidArgumentError(`invalid ${name}: ${v}`);
+    }
+    return n;
+}

package/dist/cli/repl.js

@@ -29,6 +29,7 @@ import { MouseFilter, MOUSE_ENABLE, MOUSE_DISABLE, PASTE_ENABLE, PASTE_DISABLE,
 import { inferProviderFromBaseURL } from '../agent/registry.js';
 import { getDefaultSessionStore } from '../persistence/session.js';
 import { buildSystemPrompt, parseImageInput } from '../context/system-prompt.js';
+import { shouldUseSimpleChat, userMessage, appendTurn, adoptTranscript, summaryAnchor } from './session-history.js';
 import { memoryBlock } from '../context/memory.js';
 import { estimateCost } from '../providers/model-info.js';
 import { ContextTrust } from '../context/trust.js';
@@ -543,6 +544,11 @@ export async function startRepl(opts = {}) {
     let fastMode = false;
     let displayMode = 'default';
     let lastAssistantText = '';
+    // Cross-turn conversation memory: prior turns are fed back as
+    // initialTranscript (full runs) or message history (simple chat) so
+    // follow-ups ("what models are there") resolve against earlier turns.
+    // Bounded by session-history.ts caps; reset by /clear, /new, /compact.
+    let sessionMessages = [];
     // P2 state (commands.md Priority 2)
     let activeAgent = 'default';
     let verboseMode = false;
@@ -792,7 +798,10 @@ export async function startRepl(opts = {}) {
         const { text: cleanText, images } = parseImageInput(text);
         let taskText = images.length > 0 ? `${cleanText}\n\n[images: ${images.join(', ')}]` : cleanText;
         // Only create session for non-trivial tasks (with tools/verify) — plain chat like "hello" is not a persisted session
-        const isSimpleChat = taskText.trim().split(/\s+/).length <= 5 && !taskText.toLowerCase().includes('fix') && !taskText.toLowerCase().includes('add') && !taskText.toLowerCase().includes('create');
+        // Cross-turn memory lives here: every prompt (simple or full) sees prior
+        // turns via sessionMessages. shouldUseSimpleChat keeps short chit-chat
+        // tool-free but forces URL-bearing prompts into the full loop (web_fetch).
+        const isSimpleChat = shouldUseSimpleChat(taskText);
         let sessionId;
         if (!isSimpleChat) {
             try {
@@ -816,7 +825,7 @@ export async function startRepl(opts = {}) {
                     model,
                     // Legacy chat path (no modes): plain string system, untouched by the split.
                     system: resolveSystemPrompt(systemPromptFn, { cwd, telemetry: '' }).system,
-                    messages: [{ role: 'user', content: [{ kind: 'text', text: taskText }] }],
+                    messages: [...sessionMessages, userMessage(taskText)],
                     tools: [],
                     signal: ac.signal,
                 };
@@ -832,6 +841,7 @@ export async function startRepl(opts = {}) {
                         throw new Error(ev.message);
                 }
                 lastAssistantText = simpleText;
+                sessionMessages = appendTurn(sessionMessages, taskText, simpleText);
                 clearThinking();
                 queuedStatus({ status: 'done' });
                 return;
@@ -850,6 +860,7 @@ export async function startRepl(opts = {}) {
         try {
             const result = await run({
                 task: taskText,
+                initialTranscript: sessionMessages.length > 0 ? [...sessionMessages] : undefined,
                 cwd,
                 model,
                 maxSteps: currentMaxSteps,
@@ -979,6 +990,9 @@ export async function startRepl(opts = {}) {
             });
             if (result.finalText)
                 lastAssistantText = result.finalText;
+            // Adopt the run's full transcript (prior history + this task, tools
+            // included) so the next turn resolves references against this one.
+            sessionMessages = adoptTranscript(result.transcript);
             runEndStatus = result.status;
             if (result.verification) {
                 const v = result.verification;
@@ -1037,6 +1051,7 @@ export async function startRepl(opts = {}) {
                 return;
             case 'clear':
                 queuedClear();
+                sessionMessages = [];
                 queuedAppend({ id: `sep-${Date.now()}`, kind: 'text', text: '--- cleared ---', role: 'assistant' });
                 return;
             case 'help': {
@@ -1345,6 +1360,7 @@ export async function startRepl(opts = {}) {
                 const focus = cmd.focus?.trim();
                 const compactFallback = () => {
                     queuedClear();
+                    sessionMessages = [];
                     queuedAppend({
                         id: `compact-${Date.now()}`,
                         kind: 'text',
@@ -1379,6 +1395,7 @@ export async function startRepl(opts = {}) {
                         return;
                     }
                     queuedClear();
+                    sessionMessages = summaryAnchor(summary.slice(0, 4000));
                     queuedAppend({
                         id: `compact-done-${Date.now()}`,
                         kind: 'text',
@@ -1520,6 +1537,7 @@ export async function startRepl(opts = {}) {
             }
             case 'new': {
                 queuedClear();
+                sessionMessages = [];
                 sessionLabel = '';
                 currentBranch = '';
                 try {

package/dist/cli/session-commands.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+/**
+ * Session command namespace (extracted from src/index.ts entrypoint).
+ *
+ * `session` and `sessions` accept the SAME subcommands
+ * (list/show/resume/export/import/fork/delete); `resume` is an alias for
+ * `session resume`. Handlers live here once and all groups delegate.
+ */
+export declare function registerSessionCommands(program: Command): void;

package/dist/cli/session-commands.js

@@ -0,0 +1,262 @@
+import { runOnce } from './run.js';
+import { parsePositiveInt } from './args.js';
+/**
+ * Session command namespace (extracted from src/index.ts entrypoint).
+ *
+ * `session` and `sessions` accept the SAME subcommands
+ * (list/show/resume/export/import/fork/delete); `resume` is an alias for
+ * `session resume`. Handlers live here once and all groups delegate.
+ */
+export function registerSessionCommands(program) {
+    // Level 9 — Session management.
+    // One namespace: `session` and `sessions` accept the SAME subcommands
+    // (list/show/resume/export/import/fork/delete). Handlers live here once
+    // and both command groups delegate to them.
+    async function sessionList(opts) {
+        const { getDefaultSessionStore, formatSession } = await import('../persistence/session.js');
+        const store = getDefaultSessionStore();
+        const all = await store.list(opts.status ? { status: opts.status } : undefined);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify(all, null, 2) + '\n');
+        }
+        else {
+            if (all.length === 0) {
+                process.stdout.write('No sessions\n');
+            }
+            else {
+                for (const r of all.sort((a, b) => b.updatedAt - a.updatedAt)) {
+                    process.stdout.write(formatSession(r) + '\n');
+                }
+            }
+        }
+    }
+    async function resolveOrExit(id) {
+        const { getDefaultSessionStore, resolveSessionId, matchSessionIds } = await import('../persistence/session.js');
+        const store = getDefaultSessionStore();
+        const full = await resolveSessionId(store, id);
+        if (full)
+            return full;
+        const matches = await matchSessionIds(store, id);
+        if (matches.length > 1) {
+            process.stderr.write(`ambiguous id "${id}" matches:\n${matches.map((r) => `  ${r.id.slice(0, 8)}  ${r.task.slice(0, 50)}`).join('\n')}\n`);
+        }
+        else {
+            process.stderr.write(`session not found: ${id}\n`);
+        }
+        process.exit(2);
+    }
+    async function sessionShow(id, opts) {
+        const { getDefaultSessionStore } = await import('../persistence/session.js');
+        const store = getDefaultSessionStore();
+        const full = await resolveOrExit(id);
+        const rec = await store.get(full);
+        const msgs = await store.loadMessages(full);
+        const obs = await store.loadObservations(full);
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ record: rec, messages: msgs, observations: obs }, null, 2) + '\n');
+        }
+        else {
+            process.stdout.write(`Session ${rec?.id}\n  task: ${rec?.task}\n  status: ${rec?.status}\n  cwd: ${rec?.cwd}\n  created: ${new Date(rec?.createdAt ?? 0).toISOString()}\n`);
+            process.stdout.write(`\nMessages (${msgs.length}):\n`);
+            for (const m of msgs)
+                process.stdout.write(`  [${m.role}] ${JSON.stringify(m.content).slice(0, 200)}\n`);
+            process.stdout.write(`\nObservations (${obs.length}):\n`);
+            for (const o of obs)
+                process.stdout.write(`  ${o.toolName} -> ${o.isError ? 'ERR' : 'ok'} ${JSON.stringify(o.output).slice(0, 120)}\n`);
+        }
+    }
+    async function sessionResume(id, opts) {
+        const { getDefaultSessionStore } = await import('../persistence/session.js');
+        const store = getDefaultSessionStore();
+        const full = await resolveOrExit(id);
+        const rec = await store.get(full);
+        if (!rec) {
+            process.stderr.write(`session not found: ${id}\n`);
+            process.exit(2);
+        }
+        // Resume precondition (review §9): the session is bound to the cwd /
+        // worktree it was created in. Resuming from a different directory
+        // continues in the ORIGINAL cwd (authoritative) but warns loudly so a
+        // moved checkout or wrong terminal cannot silently continue elsewhere.
+        if (rec.cwd !== process.cwd()) {
+            process.stderr.write(`klyro: warning: session created in ${rec.cwd}, resuming there (current dir is ${process.cwd()})\n`);
+        }
+        const model = opts.model ?? rec.config.model ?? process.env.KLYRO_MODEL;
+        if (!model) {
+            process.stderr.write('klyro: KLYRO_MODEL is not set (or pass --model)\n');
+            process.exit(2);
+        }
+        const code = await runOnce({
+            task: rec.task,
+            cwd: rec.cwd,
+            model,
+            maxSteps: opts.maxSteps ?? rec.config.maxSteps,
+            sessionId: full,
+            verify: opts.verify,
+            verifyCommand: opts.verifyCommand,
+        });
+        process.exit(code);
+    }
+    async function sessionExport(id, file) {
+        const { getDefaultSessionStore } = await import('../persistence/session.js');
+        const store = getDefaultSessionStore();
+        const full = await resolveOrExit(id);
+        const rec = await store.get(full);
+        const msgs = await store.loadMessages(full);
+        const obs = await store.loadObservations(full);
+        const out = file ?? `${full}.export.json`;
+        await (await import('node:fs/promises')).writeFile(out, JSON.stringify({ record: rec, messages: msgs, observations: obs }, null, 2));
+        process.stdout.write(`exported ${full} → ${out}\n`);
+    }
+    async function sessionImport(file) {
+        let data;
+        try {
+            data = JSON.parse(await (await import('node:fs/promises')).readFile(file, 'utf-8'));
+        }
+        catch (err) {
+            process.stderr.write(`klyro: cannot import ${file}: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(2);
+        }
+        const rec = data.record ?? {};
+        const { getDefaultSessionStore } = await import('../persistence/session.js');
+        const store = getDefaultSessionStore();
+        // Validate config shape (model string, bounded maxSteps) — an imported
+        // file is untrusted input and must not inject arbitrary session config.
+        const rawCfg = (rec.config && typeof rec.config === 'object' ? rec.config : { model: 'imported', maxSteps: 30 });
+        const cfg = {
+            model: typeof rawCfg.model === 'string' && rawCfg.model.length > 0 && rawCfg.model.length <= 200 ? rawCfg.model : 'imported',
+            maxSteps: typeof rawCfg.maxSteps === 'number' && Number.isFinite(rawCfg.maxSteps) && rawCfg.maxSteps > 0 && rawCfg.maxSteps <= 500 ? Math.floor(rawCfg.maxSteps) : 30,
+        };
+        const taskStr = typeof rec.task === 'string' ? rec.task.slice(0, 20_000) : 'imported';
+        const created = await store.create({ cwd: typeof rec.cwd === 'string' ? rec.cwd : process.cwd(), task: taskStr, config: cfg });
+        // Restore the transcript — previously this was silently dropped (lossy
+        // import). Messages/observations go through append* so at-rest redaction
+        // still applies. Malformed entries fail loudly instead of half-importing.
+        // Caps: at most 5000 messages / 2000 observations — an import file is
+        // untrusted and must not exhaust memory or disk.
+        const d = data;
+        let restored = 0;
+        if (d.messages !== undefined) {
+            if (!Array.isArray(d.messages)) {
+                process.stderr.write(`klyro: import failed: "messages" is not an array in ${file}\n`);
+                process.exit(2);
+            }
+            if (d.messages.length > 5000) {
+                process.stderr.write(`klyro: import failed: too many messages (${d.messages.length} > 5000) in ${file}\n`);
+                process.exit(2);
+            }
+            for (const m of d.messages) {
+                const role = m?.role;
+                if (!m || typeof m !== 'object' || (role !== 'user' && role !== 'assistant' && role !== 'tool' && role !== 'system') || !('content' in m)) {
+                    process.stderr.write(`klyro: import failed: malformed message entry in ${file}\n`);
+                    process.exit(2);
+                }
+                await store.appendMessage(created.id, m);
+                restored++;
+            }
+        }
+        if (d.observations !== undefined) {
+            if (!Array.isArray(d.observations)) {
+                process.stderr.write(`klyro: import failed: "observations" is not an array in ${file}\n`);
+                process.exit(2);
+            }
+            if (d.observations.length > 2000) {
+                process.stderr.write(`klyro: import failed: too many observations (${d.observations.length} > 2000) in ${file}\n`);
+                process.exit(2);
+            }
+            for (const o of d.observations) {
+                if (!o || typeof o !== 'object') {
+                    process.stderr.write(`klyro: import failed: malformed observation entry in ${file}\n`);
+                    process.exit(2);
+                }
+                await store.appendObservation(created.id, o);
+            }
+        }
+        process.stdout.write(`imported → ${created.id} (${restored} messages restored)\n`);
+    }
+    async function sessionFork(id) {
+        const { getDefaultSessionStore, matchSessionIds } = await import('../persistence/session.js');
+        const store = getDefaultSessionStore();
+        const matches = await matchSessionIds(store, id);
+        if (matches.length === 0) {
+            process.stderr.write(`session not found: ${id}\n`);
+            process.exit(2);
+        }
+        if (matches.length > 1) {
+            process.stderr.write(`ambiguous id "${id}" matches:\n${matches.map((r) => `  ${r.id.slice(0, 8)}  ${r.task.slice(0, 50)}`).join('\n')}\n`);
+            process.exit(2);
+        }
+        const full = matches[0].id;
+        const forked = await store.fork(full);
+        const msgs = await store.loadMessages(forked.id);
+        process.stdout.write(`forked ${full.slice(0, 8)} → ${forked.id.slice(0, 8)} (${msgs.length} messages carried over)\n`);
+    }
+    async function sessionDelete(id) {
+        const { getDefaultSessionStore, matchSessionIds } = await import('../persistence/session.js');
+        const store = getDefaultSessionStore();
+        const matches = await matchSessionIds(store, id);
+        if (matches.length === 0) {
+            process.stderr.write(`session not found: ${id}\n`);
+            process.exit(2);
+        }
+        if (matches.length > 1) {
+            process.stderr.write(`ambiguous id "${id}" matches:\n${matches.map((r) => `  ${r.id.slice(0, 8)}  ${r.task.slice(0, 50)}`).join('\n')}\n`);
+            process.exit(2);
+        }
+        const full = matches[0].id;
+        await store.delete(full);
+        process.stdout.write(`deleted ${full.slice(0, 8)}\n`);
+    }
+    const session = program.command('session').description('Session persistence (Level 9)');
+    session
+        .command('list')
+        .description('List persisted sessions')
+        .option('--status <s>', 'Filter by status: open|complete|verify_failed|aborted|max_steps')
+        .option('--json', 'Output JSON')
+        .action(async (opts) => { await sessionList(opts); });
+    session
+        .command('show <id>')
+        .description('Show session transcript and observations')
+        .option('--json', 'Output JSON')
+        .action(async (id, opts) => { await sessionShow(id, opts); });
+    session
+        .command('resume <id>')
+        .description('Resume a persisted session (requires KLYRO_MODEL etc.)')
+        .option('-m, --model <id>', 'Model (default: from session or env)')
+        .option('--max-steps <n>', 'Max steps (default 30)', (v) => parsePositiveInt('--max-steps', v))
+        .option('--verify-command <cmd>', 'Override verification command')
+        .option('--verify', 'Enable verification (default: enabled)')
+        .action(async (id, opts) => { await sessionResume(id, opts); });
+    session
+        .command('export <id> [file]')
+        .description('Export session to file (9.4)')
+        .action(async (id, file) => { await sessionExport(id, file); });
+    session
+        .command('import <file>')
+        .description('Import session from file (restores record + messages + observations)')
+        .action(async (file) => { await sessionImport(file); });
+    session
+        .command('fork <id>')
+        .description('Fork session with full context (9.4)')
+        .action(async (id) => { await sessionFork(id); });
+    session
+        .command('delete <id>')
+        .description('Delete a session and its artifacts')
+        .action(async (id) => { await sessionDelete(id); });
+    // Alias: klyro resume <id> → klyro session resume <id>
+    program
+        .command('resume <id>')
+        .description('Alias for `klyro session resume <id>`')
+        .option('-m, --model <id>', 'Model')
+        .option('--max-steps <n>', 'Max steps', (v) => parsePositiveInt('--max-steps', v))
+        .action(async (id, opts) => { await sessionResume(id, opts); });
+    // 9.4 — same namespace as `session`: every subcommand works under both.
+    const sessions = program.command('sessions').description('Alias for session (same subcommands)');
+    sessions.command('list').description('List persisted sessions').option('--status <s>', 'Filter by status').option('--json', 'Output JSON').action(async (opts) => { await sessionList(opts); });
+    sessions.command('show <id>').description('Show session transcript and observations').option('--json', 'Output JSON').action(async (id, opts) => { await sessionShow(id, opts); });
+    sessions.command('resume <id>').description('Resume a persisted session').option('-m, --model <id>', 'Model').option('--max-steps <n>', 'Max steps', (v) => parsePositiveInt('--max-steps', v)).option('--verify-command <cmd>', 'Override verification command').option('--verify', 'Enable verification (default: enabled)').action(async (id, opts) => { await sessionResume(id, opts); });
+    sessions.command('export <id> [file]').description('Export session to file (9.4)').action(async (id, file) => { await sessionExport(id, file); });
+    sessions.command('import <file>').description('Import session from file (restores record + messages + observations)').action(async (file) => { await sessionImport(file); });
+    sessions.command('fork <id>').description('Fork session with full context (9.4)').action(async (id) => { await sessionFork(id); });
+    sessions.command('delete <id>').description('Delete a session and its artifacts').action(async (id) => { await sessionDelete(id); });
+}

package/dist/cli/session-history.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Cross-turn conversation memory for the interactive TUI REPL.
+ *
+ * Root cause it fixes: every TUI prompt previously started a brand-new
+ * `run()` with only the current message, so "what models are there" asked
+ * after pasting a URL could never resolve what "models" referred to.
+ * These helpers keep a bounded `Message[]` across turns and feed it back
+ * as `initialTranscript` (full runs) or message history (simple chat).
+ *
+ * Bounds keep cost predictable: at most MAX_HISTORY_MESSAGES messages and
+ * MAX_HISTORY_CHARS of content. Trimming cuts only at user-message
+ * boundaries and never orphans a `tool_result` from its `tool_use`
+ * (providers reject dangling tool blocks).
+ */
+import type { Message } from '../agent/message.js';
+export declare const MAX_HISTORY_MESSAGES = 60;
+export declare const MAX_HISTORY_CHARS = 60000;
+/** True when the text references a web URL (needs tools — never simple chat). */
+export declare function looksLikeUrl(text: string): boolean;
+/**
+ * Fast-path gate: short chit-chat skips tools. Extracted (was inline in
+ * repl.ts) so the URL carve-out is unit-tested: any URL forces the full
+ * agent loop where web_fetch + approval can engage.
+ */
+export declare function shouldUseSimpleChat(text: string): boolean;
+export declare function userMessage(text: string): Message;
+export declare function assistantMessage(text: string): Message;
+/** Plain-text projection of a message (tool blocks count JSON-encoded). */
+export declare function messageText(m: Message): string;
+/**
+ * Trim to budget, cutting only at user-message boundaries with no orphaned
+ * tool_result. Falls back to the last user/assistant text pair when no
+ * valid cut fits (e.g. one giant tool result).
+ */
+export declare function trimHistory(history: Message[]): Message[];
+/** Record a completed simple-chat turn. */
+export declare function appendTurn(history: Message[], userText: string, assistantText: string): Message[];
+/** Adopt a full run's transcript (already includes prior history + task). */
+export declare function adoptTranscript(transcript: Message[]): Message[];
+/**
+ * Seed history after /compact: earlier turns are replaced by the retained
+ * summary so follow-ups still resolve ("the models we discussed").
+ */
+export declare function summaryAnchor(summary: string): Message[];