klyro 1.0.9 → 1.0.10

package/READ.md

@@ -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/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/index.js

@@ -16,6 +16,8 @@ import { chat } from './chat.js';
 import { repl } from './repl.js';
 import { startRepl } from './cli/repl.js';
 import { runOnce } from './cli/run.js';
+import { registerSessionCommands } from './cli/session-commands.js';
+import { parsePositiveInt } from './cli/args.js';
 import { runEval } from './cli/eval.js';
 import { runConfig } from './cli/config.js';
 import { runDoctor } from './cli/doctor.js';
@@ -25,13 +27,6 @@ import { runLogin, runLogout } from './cli/auth.js';
 import { readVersion } from './version.js';
 import { verifyAuditChain } from './persistence/audit.js';
 const VERSION = readVersion();
-function parsePositiveInt(name, v) {
-    const n = Number(v);
-    if (!Number.isFinite(n) || n <= 0) {
-        throw new InvalidArgumentError(`invalid ${name}: ${v}`);
-    }
-    return n;
-}
 function parseTemperature(v) {
     const n = Number(v);
     if (!Number.isFinite(n) || n < 0 || n > 2) {
@@ -420,237 +415,13 @@ async function main() {
         process.stdout.write(out + '\n');
         process.exit(0);
     });
-    // 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);
-        }
-        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();
-        const cfg = (rec.config && typeof rec.config === 'object' ? rec.config : { model: 'imported', maxSteps: 30 });
-        const created = await store.create({ cwd: typeof rec.cwd === 'string' ? rec.cwd : process.cwd(), task: typeof rec.task === 'string' ? rec.task : 'imported', 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.
-        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);
-            }
-            for (const m of d.messages) {
-                if (!m || typeof m !== 'object' || typeof m.role !== 'string' || !('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);
-            }
-            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); });
+    // Session namespace lives in src/cli/session-commands.ts (entrypoint stays registration-only).
+    registerSessionCommands(program);
     program.command('scan').description('Scan project (7.1) — languages, frameworks, commands, 300ms cached').option('--json', 'JSON output').action(async (opts) => { const { runScan } = await import('./cli/scan.js'); process.exit(await runScan({ cwd: process.cwd(), json: !!opts.json })); });
     program.command('project').description('Alias for scan').option('--json', 'JSON output').action(async (opts) => { const { runProject } = await import('./cli/scan.js'); process.exit(await runProject({ cwd: process.cwd(), json: !!opts.json })); });
     // 9.2 — Continue / resume top-level flags (also handled via session resume)
     program.option('-c, --continue', 'Continue most recent session in cwd (9.2)');
     program.option('-r, --resume [id]', 'Resume session by id or pick most recent');
-    // 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); });
     // 10.1 — MCP
     const mcp = program.command('mcp').description('MCP client/server (10.1)');
     mcp.command('list').description('List MCP servers').action(async () => {

package/dist/mcp/trust.js

@@ -55,7 +55,21 @@ export class McpTrust {
     save() {
         try {
             fs.mkdirSync(path.dirname(this.storePath), { recursive: true });
-            fs.writeFileSync(this.storePath, JSON.stringify(this.store, null, 2), 'utf-8');
+            // Atomic trust write (tmp + rename) so a crash never leaves a
+            // truncated mcp-trust.json that auto-approves the wrong spec.
+            const tmp = `${this.storePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+            fs.writeFileSync(tmp, JSON.stringify(this.store, null, 2), 'utf-8');
+            try {
+                const fh = fs.openSync(tmp, 'r+');
+                try {
+                    fs.fsyncSync(fh);
+                }
+                finally {
+                    fs.closeSync(fh);
+                }
+            }
+            catch { /* ignore on Windows */ }
+            fs.renameSync(tmp, this.storePath);
         }
         catch {
             /* best-effort — trust stays in memory for the session */

package/dist/persistence/store.d.ts

@@ -10,6 +10,9 @@
  * SessionStore interface.
  */
 export type SessionStatus = 'open' | 'complete' | 'verify_failed' | 'aborted' | 'max_steps' | 'stuck';
+/** Persisted session schema version. Bump when SessionRecord changes shape;
+ * readers migrate older records forward (missing version ⇒ v0). */
+export declare const SESSION_SCHEMA_VERSION = 1;
 export interface SessionConfig {
     model: string;
     maxSteps: number;
@@ -24,7 +27,12 @@ export interface SessionRecord {
     updatedAt: number;
     config: SessionConfig;
     finalText?: string;
+    /** Schema version for migrations; absent on pre-v1 records (treated as v0). */
+    schemaVersion?: number;
 }
+/** Migrate a persisted record forward. Unknown future versions pass through
+ * untouched so a newer CLI's sessions stay readable (forward-compatible). */
+export declare function migrateSessionRecord(raw: SessionRecord): SessionRecord;
 export interface StoredMessage {
     role: 'user' | 'assistant' | 'tool' | 'system';
     content: unknown;

package/dist/persistence/store.js

@@ -14,6 +14,17 @@ import * as fsSync from 'node:fs';
 import * as path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { redact } from '../policy/secret-redactor.js';
+/** Persisted session schema version. Bump when SessionRecord changes shape;
+ * readers migrate older records forward (missing version ⇒ v0). */
+export const SESSION_SCHEMA_VERSION = 1;
+/** Migrate a persisted record forward. Unknown future versions pass through
+ * untouched so a newer CLI's sessions stay readable (forward-compatible). */
+export function migrateSessionRecord(raw) {
+    const version = typeof raw.schemaVersion === 'number' ? raw.schemaVersion : 0;
+    if (version >= SESSION_SCHEMA_VERSION)
+        return raw;
+    return { ...raw, schemaVersion: SESSION_SCHEMA_VERSION };
+}
 export class SessionStore {
     dir;
     indexPath;
@@ -133,9 +144,31 @@ export class SessionStore {
                 createdAt: now,
                 updatedAt: now,
                 config: opts.config,
+                schemaVersion: SESSION_SCHEMA_VERSION,
             };
             record.title = this.titleFor(task);
-            await fs.writeFile(path.join(this.dir, `${id}.json`), JSON.stringify({ record, messages: [], observations: [] }, null, 2));
+            // Atomic session create (tmp + fsync + rename) so a crash can never
+            // leave a truncated `${id}.json` that resume/import then trusts.
+            const target = path.join(this.dir, `${id}.json`);
+            const tmpCreate = `${target}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+            await fs.writeFile(tmpCreate, JSON.stringify({ record, messages: [], observations: [] }, null, 2));
+            try {
+                const fh = await fs.open(tmpCreate, 'r+');
+                try {
+                    await fh.sync();
+                }
+                finally {
+                    await fh.close();
+                }
+            }
+            catch { /* ignore on Windows */ }
+            try {
+                await fs.rename(tmpCreate, target);
+            }
+            catch {
+                await fs.unlink(tmpCreate).catch(() => undefined);
+                throw new Error(`Failed to write session ${id}`);
+            }
             await this.appendJsonl(id, { type: 'session.create', record, ts: now });
             const idx = await this.readIndex();
             idx[id] = record;
@@ -238,7 +271,9 @@ export class SessionStore {
     }
     async readSession(id) {
         const raw = await fs.readFile(path.join(this.dir, `${id}.json`), 'utf-8');
-        return JSON.parse(raw);
+        const parsed = JSON.parse(raw);
+        parsed.record = migrateSessionRecord(parsed.record);
+        return parsed;
     }
     async writeSession(id, data) {
         data.record.updatedAt = Date.now();
@@ -339,12 +374,13 @@ export class SessionStore {
     }
     async list(filter) {
         const idx = await this.readIndex();
-        const all = Object.values(idx);
+        const all = Object.values(idx).map(migrateSessionRecord);
         return filter?.status ? all.filter((s) => s.status === filter.status) : all;
     }
     async get(id) {
         const idx = await this.readIndex();
-        return idx[id] ?? null;
+        const rec = idx[id];
+        return rec ? migrateSessionRecord(rec) : null;
     }
     /** Atomic append + fsync — survives crashes; suitable for audit log. */
     static async appendJsonl(filePath, entry) {

package/dist/renderers/terminal.js

@@ -3,32 +3,33 @@
  * No direct writes in core — this is the only place that writes to stdout/stderr for human.
  */
 import { renderMarkdown } from '../cli/markdown.js';
+import { sanitizeTerminalText } from '../shared/sanitize.js';
 export class TerminalRenderer {
     handle(ev) {
         switch (ev.type) {
             case 'stream.delta':
-                process.stdout.write(ev.text);
+                process.stdout.write(sanitizeTerminalText(ev.text));
                 break;
             case 'tool.call':
-                process.stderr.write(`\n[tool] ${ev.name} ${JSON.stringify(ev.input).slice(0, 200)}\n`);
+                process.stderr.write(`\n[tool] ${sanitizeTerminalText(ev.name)} ${sanitizeTerminalText(JSON.stringify(ev.input).slice(0, 200))}\n`);
                 break;
             case 'tool.result':
                 process.stderr.write(`  -> ${ev.isError ? 'ERR' : 'ok'} (${ev.latencyMs}ms)\n`);
                 break;
             case 'file.changed':
-                process.stderr.write(`  ✎ ${ev.path} (${ev.op})\n`);
+                process.stderr.write(`  ✎ ${sanitizeTerminalText(ev.path)} (${ev.op})\n`);
                 break;
             case 'phase.changed':
-                process.stderr.write(`\n[phase] ${ev.phase}\n`);
+                process.stderr.write(`\n[phase] ${sanitizeTerminalText(ev.phase)}\n`);
                 break;
             case 'verification.started':
-                process.stderr.write(`[verify] ${ev.command}\n`);
+                process.stderr.write(`[verify] ${sanitizeTerminalText(ev.command)}\n`);
                 break;
             case 'verification.failed':
-                process.stderr.write(`[verify] failed: ${ev.reason.slice(0, 200)}\n`);
+                process.stderr.write(`[verify] failed: ${sanitizeTerminalText(ev.reason.slice(0, 200))}\n`);
                 break;
             case 'error':
-                process.stderr.write(`✖ ${ev.message}\n`);
+                process.stderr.write(`✖ ${sanitizeTerminalText(ev.message)}\n`);
                 break;
             default:
                 break;
@@ -36,6 +37,6 @@ export class TerminalRenderer {
     }
     renderMarkdown(text) {
         const out = renderMarkdown(text, { isTTY: !!process.stdout.isTTY });
-        process.stdout.write(out);
+        process.stdout.write(sanitizeTerminalText(out));
     }
 }

package/dist/repl.d.ts

@@ -1,4 +1,11 @@
 /**
+ * COMPATIBILITY-ONLY legacy interactive REPL. Prefer `klyro tui`.
+ *
+ * Shares the provider contract with chat.ts/providers.ts (assertSafeBaseURL,
+ * normalizeBaseURL) — covered by src/providers/contract.test.ts.
+ * History here is in-memory only; cross-turn persistence lives in the TUI
+ * REPL path (src/cli/repl.ts + session-history).
+ *
  * Interactive REPL. Reads prompts from stdin one line at a time.
  *
  * Conversation history lives in memory only; each new prompt is sent with the

package/dist/repl.js

@@ -1,4 +1,11 @@
 /**
+ * COMPATIBILITY-ONLY legacy interactive REPL. Prefer `klyro tui`.
+ *
+ * Shares the provider contract with chat.ts/providers.ts (assertSafeBaseURL,
+ * normalizeBaseURL) — covered by src/providers/contract.test.ts.
+ * History here is in-memory only; cross-turn persistence lives in the TUI
+ * REPL path (src/cli/repl.ts + session-history).
+ *
  * Interactive REPL. Reads prompts from stdin one line at a time.
  *
  * Conversation history lives in memory only; each new prompt is sent with the

package/dist/shared/index.d.ts

@@ -1,2 +1,3 @@
 export * from './errors.js';
 export * from './types.js';
+export * from './sanitize.js';

package/dist/shared/index.js

@@ -1,2 +1,3 @@
 export * from './errors.js';
 export * from './types.js';
+export * from './sanitize.js';

package/dist/shared/sanitize.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Terminal output sanitization (review section 11).
+ *
+ * Model and tool output is untrusted: it must never emit raw terminal
+ * control sequences (OSC hyperlinks, CSI cursor/reporting, C0/C1 controls)
+ * that could rewrite the display or smuggle approval-like text. The
+ * human-mode TerminalRenderer writes directly to stdout/stderr, so all
+ * human output is passed through `sanitizeTerminalText` first.
+ *
+ * Strips OSC + CSI sequences and C0/C1 controls (except newline/tab);
+ * preserves printable Unicode, wide chars, and emoji.
+ */
+export declare function sanitizeTerminalText(input: string): string;

package/dist/shared/sanitize.js

@@ -0,0 +1,49 @@
+/**
+ * Terminal output sanitization (review section 11).
+ *
+ * Model and tool output is untrusted: it must never emit raw terminal
+ * control sequences (OSC hyperlinks, CSI cursor/reporting, C0/C1 controls)
+ * that could rewrite the display or smuggle approval-like text. The
+ * human-mode TerminalRenderer writes directly to stdout/stderr, so all
+ * human output is passed through `sanitizeTerminalText` first.
+ *
+ * Strips OSC + CSI sequences and C0/C1 controls (except newline/tab);
+ * preserves printable Unicode, wide chars, and emoji.
+ */
+export function sanitizeTerminalText(input) {
+    const ESC = String.fromCharCode(27);
+    const BEL = String.fromCharCode(7);
+    const out = input;
+    let cleaned = '';
+    let i = 0;
+    while (i < out.length) {
+        const ch = out[i];
+        const code = out.charCodeAt(i);
+        if (ch === ESC) {
+            const next = out[i + 1];
+            if (next === '[') {
+                let j = i + 2;
+                while (j < out.length && !/[@-~]/.test(out[j]))
+                    j++;
+                i = j + 1;
+                continue;
+            }
+            if (next === ']') {
+                let j = i + 2;
+                while (j < out.length && out[j] !== BEL && !(out[j] === ESC && out[j + 1] === '\\'))
+                    j++;
+                i = out[j] === BEL ? j + 1 : j + 2;
+                continue;
+            }
+            i += 1;
+            continue;
+        }
+        if ((code < 0x20 && code !== 0x0a && code !== 0x09) || (code >= 0x7f && code <= 0x9f)) {
+            i += 1;
+            continue;
+        }
+        cleaned += ch;
+        i += 1;
+    }
+    return cleaned;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klyro",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Klyro — autonomous coding harness CLI that streams from any OpenAI-compatible or Anthropic LLM endpoint.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,6 +27,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "release:check": "node scripts/release-check.mjs",
     "pack:dry": "npm pack --dry-run",
     "publish:public": "npm publish --access public"
   },