talos-code 0.0.1 → 0.2.0

package/dist/commands/system-cli.js

@@ -0,0 +1,405 @@
+import { access, mkdir, open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { spawn, spawnSync } from 'node:child_process';
+import { assertNoUnknownOptions, takeFlag, takeOption, writeValue } from "./context.js";
+import { doctorVerdict, runDoctor, turnReadiness } from "../diagnostics/doctor.js";
+import { createPathPseudonymizer, redactObject, secretValuesFromEnvironment } from "../diagnostics/redact.js";
+import { writeStoredZip } from "../diagnostics/zip.js";
+import { loadEffectiveConfig } from "../config/load.js";
+import { CLI_VERSION } from "../version.js";
+import { performUpdateCheck, downloadVerifiedUpdate, discoverGitHubReleaseManifest } from "../update/run.js";
+import { checkNpmRegistry, installedWithNpm } from "../update/npm.js";
+import { describeKeyringProbeFailure, describeKeyringProblem, diagnoseKeyringProbe, systemKeyringModuleLoads } from "../provider/system-keyring.js";
+import { credentialStoreName, credentialStoreSourceText, isTestProfile, openCredentialStore } from "../provider/store.js";
+import { MODELS_DEV_CACHE_HOURS, MODELS_DEV_URL, modelsDevSwitch } from "../runtime/model-profile.js";
+import { providerOfModel } from "../provider/environment-keys.js";
+import { t } from "../i18n/index.js";
+import { hasActiveRuns } from "../runtime/active-run.js";
+import { importTalosModule } from "../runtime/repo.js";
+import { detectTerminalCapabilities } from "../tui/terminal-capabilities.js";
+import { createTerminalSessionPlan } from "../tui/terminal-session.js";
+import { shellDimensions } from "../tui/shell-layout.js";
+import { currentProcessPerformanceSnapshot } from "../tui/metrics.js";
+import { createTrustAuthority } from "../security/trust-authority.js";
+import { createProcessTreeEvidenceStore } from "../security/process-tree-evidence-store.js";
+import * as updateCheck from "../update/check.js";
+export async function pathAccessible(p, { writable = true, accessImpl = access } = {}) { try {
+    await accessImpl(p, writable ? constants.R_OK | constants.W_OK : constants.R_OK);
+    return true;
+}
+catch {
+    return false;
+} }
+function doctorStore(ctx, config, deps) {
+    try {
+        return { opened: openCredentialStore({ repoRoot: ctx.repoRoot, scope: ctx.paths.dataRoot, env: process.env, config, ...(deps ? { loader: deps } : {}) }), refusal: null };
+    }
+    catch (error) {
+        return { opened: null, refusal: error };
+    }
+}
+async function keyringAvailable(store) {
+    if (!store.opened)
+        throw store.refusal;
+    if (store.opened.problem)
+        throw new Error(describeKeyringProblem(store.opened.problem));
+    const outcome = await diagnoseKeyringProbe(store.opened.keyring);
+    if (!outcome.ok)
+        throw new Error(describeKeyringProbeFailure(outcome));
+    return true;
+}
+/** R2 (gate E13, Q-R2-9: wording only, `ok` stays R4's): which store is active, and whether this doctor run loaded the native module. */
+function credentialsSection(store, loadsBefore) {
+    const nativeModuleLoaded = systemKeyringModuleLoads() > loadsBefore;
+    if (!store.opened) {
+        const error = store.refusal;
+        return { state: 'unavailable', store: error?.details?.store ?? null, source: error?.details?.source ?? null, nativeModuleLoaded, code: String(error?.code ?? 'CREDENTIAL_STORE_UNAVAILABLE'), detail: error instanceof Error ? error.message : String(error) };
+    }
+    const { kind, source, problem } = store.opened;
+    return problem ? { state: 'unavailable', store: kind, source, nativeModuleLoaded, detail: describeKeyringProblem(problem) } : { state: 'healthy', store: kind, source, nativeModuleLoaded };
+}
+/* R4 Q-R4-15 (a): the system store is one per operating-system user, so every TALOS of that user reads the same keys; the line
+   says so. The JSON section is unchanged (R2 E13 pins it). */
+/* R5b: whether models.dev is used, why not, and how to change it (the one outbound request for sizes and prices, gate E7). */
+export function catalogLine(section) {
+    if (section?.state === 'on')
+        return t('firstrun.doctor.catalogOn', { source: String(section.source ?? ''), hours: Number(section.cacheHours ?? 0) });
+    return t(section?.reason === 'environment' ? 'firstrun.doctor.catalogOffEnvironment' : section?.reason === 'test' ? 'firstrun.doctor.catalogOffTest' : 'firstrun.doctor.catalogOffConfig');
+}
+export function credentialsLine(section, platform = process.platform) {
+    if (section?.state !== 'healthy' && section?.detail)
+        return t('store.refused.line', { message: String(section.detail) });
+    const memory = section?.store === 'memory';
+    const line = t('store.line', { store: credentialStoreName(memory ? 'memory' : 'system', platform), source: credentialStoreSourceText({ source: section?.source }) });
+    return memory ? line : `${line} — ${t(platform === 'win32' ? 'store.shared.win32' : platform === 'darwin' ? 'store.shared.darwin' : 'store.shared.other')}`;
+}
+/** The readiness of the provider of the model a run would use: the one sentence a person acts on (E8 for a missing key). */
+function activeModelReadiness(control, model) {
+    const provider = model ? providerOfModel(model) : null;
+    if (!provider || typeof control?.readiness !== 'function')
+        return null;
+    try {
+        const decision = control.readiness(provider);
+        return { model, provider, ready: decision?.ready === true, code: decision?.ready ? null : String(decision?.code ?? ''), message: decision?.ready ? null : String(decision?.message ?? '') };
+    }
+    catch {
+        return null;
+    }
+}
+function platformId() { return `${process.platform}-${process.arch}`; }
+function providerView(row) { return { id: String(row?.id ?? ''), label: String(row?.label ?? row?.id ?? ''), auth: { required: row?.auth?.required === true, source: String(row?.auth?.source ?? 'missing'), configured: row?.auth?.configured === true, usable: row?.auth?.usable === true }, endpoint: { host: typeof row?.endpoint?.host === 'string' ? row.endpoint.host : null, configured: row?.endpoint?.configured === true, valid: row?.endpoint?.valid === true }, runtimeConfigured: row?.runtimeConfigured !== false, local: row?.local === true, cooldown: { active: row?.cooldown?.active === true, cause: typeof row?.cooldown?.cause === 'string' ? row.cooldown.cause : null, until: Number.isFinite(row?.cooldown?.until) ? Number(row.cooldown.until) : null }, lastHealth: { state: String(row?.lastHealth?.state ?? 'unknown'), latencyMs: Number.isFinite(row?.lastHealth?.latencyMs) ? Number(row.lastHealth.latencyMs) : null, observedAt: Number.isFinite(row?.lastHealth?.observedAt) ? Number(row.lastHealth.observedAt) : null, httpStatus: Number.isFinite(row?.lastHealth?.httpStatus) ? Number(row.lastHealth.httpStatus) : null }, ready: row?.ready === true }; }
+async function doctorData(ctx, deps = {}, options = {}) {
+    const profile = options.profile === true;
+    const loadsBefore = systemKeyringModuleLoads();
+    let config = null;
+    try {
+        config = (await loadEffectiveConfig({ paths: ctx.paths, projectRoot: ctx.projectRoot })).value;
+    }
+    catch {
+        config = null;
+    }
+    const store = doctorStore(ctx, config, deps.keyring);
+    const activeModel = ctx.invocation.model ?? (typeof config?.model === 'string' ? config.model : null);
+    const base = await runDoctor({
+        paths: ctx.paths,
+        fsAccess: (p) => pathAccessible(p, { writable: true }),
+        gitProbe: async () => spawnSync('git', ['--version'], { stdio: 'ignore' }).status === 0,
+        keyringProbe: () => keyringAvailable(store),
+        credentialsProbe: async () => credentialsSection(store, loadsBefore),
+        catalogProbe: async () => { const decided = modelsDevSwitch({ env: process.env, config, testProfile: isTestProfile(process.env) }); return { state: decided.enabled ? 'on' : 'off', reason: decided.reason, source: MODELS_DEV_URL, cacheHours: MODELS_DEV_CACHE_HOURS }; },
+        profile,
+        terminalProbe: async () => {
+            const color = typeof process.stdout.hasColors === 'function' ? Boolean(process.stdout.hasColors()) : ctx.io.stdoutIsTTY;
+            const capabilities = detectTerminalCapabilities({ stdinIsTTY: ctx.io.stdinIsTTY, stdoutIsTTY: ctx.io.stdoutIsTTY, color, env: process.env });
+            const session = createTerminalSessionPlan({ capabilities, env: process.env, supportsAlternateScreen: true });
+            const terminalRows = Number(process.stdout.rows ?? 30), terminalColumns = Number(process.stdout.columns ?? 100);
+            return { state: 'healthy', capabilities, session, layout: shellDimensions(terminalRows, terminalColumns), terminal: { rows: terminalRows, columns: terminalColumns, term: process.env.TERM ?? null } };
+        },
+        runtimeProbe: async () => {
+            const runtimeFile = join(ctx.repoRoot, 'harness-ui', 'src', 'session-registry.mjs');
+            const layout = { runtimeReadable: await pathAccessible(runtimeFile, { writable: false }), projectWritable: await pathAccessible(ctx.projectRoot, { writable: true }), sessionsRoot: await pathAccessible(ctx.paths.sessionsRoot, { writable: true }), configRoot: await pathAccessible(ctx.paths.configRoot, { writable: true }), cacheRoot: await pathAccessible(ctx.paths.cacheRoot, { writable: true }) };
+            return { state: Object.values(layout).every(Boolean) ? 'healthy' : 'degraded', layout, roots: { project: ctx.projectRoot, repo: ctx.repoRoot, sessions: ctx.paths.sessionsRoot, config: ctx.paths.configRoot, cache: ctx.paths.cacheRoot } };
+        },
+        trustProbe: async () => {
+            try {
+                const snapshot = await createTrustAuthority({ projectRoot: ctx.projectRoot, trustRoot: ctx.paths.trust.projects }).inspect();
+                return { state: snapshot.trusted ? 'healthy' : 'degraded', trusted: snapshot.trusted === true, reason: String(snapshot.reason ?? 'UNKNOWN'), storeSchema: snapshot.storeSchema ?? null, resources: Array.isArray(snapshot.resources) ? snapshot.resources.length : 0, nestedRepositories: Array.isArray(snapshot.nestedRepositories) ? snapshot.nestedRepositories.length : 0, rollbackAvailable: snapshot.rollbackAvailable === true };
+            }
+            catch (error) {
+                return { state: 'unavailable', trusted: false, reason: error instanceof Error ? error.message : String(error) };
+            }
+        },
+        providerProbe: async ({ active }) => {
+            let runtimeContext = null;
+            try {
+                runtimeContext = await ctx.createRuntimeContext({ projectRoot: ctx.projectRoot, paths: ctx.paths, repoRoot: ctx.repoRoot, model: ctx.invocation.model ?? 'openai:gpt-5-mini', environmentKeys: 'consent' });
+                const control = runtimeContext?.providerControlPlane;
+                /* R4 Q-R4-14: whether a turn could run now, asked the way a send asks it; the chosen local engine must answer. */
+                const turn = await turnReadiness({ catalog: runtimeContext?.tuiCatalog, control, model: activeModel });
+                if (!control || typeof control.list !== 'function')
+                    return { state: 'unavailable', profiles: [], turn };
+                const rows = control.list().slice(0, 16);
+                const profiles = [];
+                let activeCount = 0;
+                for (const row of rows) {
+                    let current = row;
+                    const eligible = row?.runtimeConfigured !== false && (row?.auth?.required !== true || row?.auth?.usable === true);
+                    if (active && eligible && activeCount < 8 && typeof control.probe === 'function') {
+                        activeCount++;
+                        try {
+                            current = await control.probe(String(row.id));
+                        }
+                        catch (error) {
+                            current = { ...row, lastHealth: { state: 'error', detail: error instanceof Error ? error.message : String(error), latencyMs: null, observedAt: Date.now(), httpStatus: null } };
+                        }
+                    }
+                    profiles.push(providerView(current));
+                }
+                const readiness = activeModelReadiness(control, activeModel);
+                return { state: active ? 'healthy' : 'unknown', active, profiles, ...(readiness ? { activeModel: readiness } : {}), turn };
+            }
+            catch (error) {
+                return { state: 'unavailable', active, profiles: [], detail: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                try {
+                    await runtimeContext?.runtime?.close?.();
+                }
+                catch { }
+            }
+        },
+        brokerProbe: async () => {
+            const result = await createProcessTreeEvidenceStore({ cacheRoot: ctx.paths.cacheRoot }).read();
+            if (!result)
+                return { state: 'absent', processTree: { verified: false, source: 'none' } };
+            return { state: result.verified ? 'verified' : 'unverified', processTree: { verified: result.verified === true, source: 'cached-host-bound', reason: typeof result.reason === 'string' ? result.reason : null, scope: result.evidence?.scope ?? null, observedAtMs: Number.isFinite(result.evidence?.observedAtMs) ? Number(result.evidence.observedAtMs) : null, durationMs: Number.isFinite(result.evidence?.durationMs) ? Number(result.evidence.durationMs) : null, signals: result.evidence?.signals ?? null } };
+        },
+        contextProbe: async () => {
+            const database = join(ctx.paths.dataRoot, 'context', 'context.sqlite');
+            try {
+                const info = await stat(database);
+                if (!info.isFile())
+                    return { state: 'degraded', database: 'not-file', format: 'unknown', bytes: info.size };
+                const handle = await open(database, 'r');
+                const header = Buffer.alloc(16);
+                let bytesRead = 0;
+                try {
+                    ({ bytesRead } = await handle.read(header, 0, 16, 0));
+                }
+                finally {
+                    await handle.close();
+                }
+                const sqlite = bytesRead === 16 && header.toString('utf8') === 'SQLite format 3\u0000';
+                return { state: sqlite ? 'healthy' : 'degraded', database: 'present', format: sqlite ? 'sqlite3' : 'unknown', bytes: info.size };
+            }
+            catch (error) {
+                if (error?.code === 'ENOENT')
+                    return { state: 'absent', database: 'absent', format: null, bytes: 0 };
+                return { state: 'unavailable', database: 'unreadable', format: null, bytes: null, detail: error instanceof Error ? error.message : String(error) };
+            }
+        },
+        sessionProbe: async () => {
+            const mod = await importTalosModule(ctx.repoRoot, 'session-store.mjs');
+            const ids = await mod.elencaSessioniPersistite({ cartellaStore: ctx.paths.sessionsRoot });
+            const limit = 64, maxFileBytes = 2 * 1024 * 1024, maxTotalBytes = 8 * 1024 * 1024;
+            let readable = 0, corrupt = 0, skipped = 0, totalBytes = 0;
+            for (const id of ids.slice(0, limit)) {
+                const file = join(ctx.paths.sessionsRoot, String(id) + '.jsonl');
+                let info;
+                try {
+                    info = await stat(file);
+                }
+                catch {
+                    skipped++;
+                    continue;
+                }
+                if (!info.isFile() || info.size > maxFileBytes || totalBytes + info.size > maxTotalBytes) {
+                    skipped++;
+                    continue;
+                }
+                totalBytes += info.size;
+                try {
+                    const row = await mod.leggiRegistro({ cartellaStore: ctx.paths.sessionsRoot, sessionId: id });
+                    if (row === null)
+                        skipped++;
+                    else
+                        readable++;
+                }
+                catch {
+                    corrupt++;
+                }
+            }
+            skipped += Math.max(0, ids.length - limit);
+            return { state: corrupt ? 'degraded' : 'healthy', persisted: ids.length, readable, corrupt, skipped, capped: ids.length > limit || skipped > 0, inspectedBytes: totalBytes };
+        },
+        updateProbe: async () => ({ state: typeof updateCheck.verifyReleaseManifestSignature === 'function' ? 'unknown' : 'degraded', manifestSchema: 'talos.cli.release.v1', checksum: typeof updateCheck.verifyDownloadedAsset === 'function' ? 'sha256' : 'unavailable', signature: typeof updateCheck.verifyReleaseManifestSignature === 'function' ? 'available' : 'unavailable' }),
+        performanceProbe: async () => currentProcessPerformanceSnapshot(),
+    });
+    const extra = [];
+    for (const [id, file] of [['talos-runtime', join(ctx.repoRoot, 'harness-ui', 'src', 'session-registry.mjs')], ['project', ctx.projectRoot]]) {
+        extra.push({ id, ok: await pathAccessible(file, { writable: id === 'project' }) });
+    }
+    for (const [id, file] of [['mcp', join(ctx.projectRoot, '.harness-ui-mcp.json')], ['hooks', join(ctx.projectRoot, '.harness-ui-hooks.json')]]) {
+        try {
+            await stat(file);
+            JSON.parse(await readFile(file, 'utf8'));
+            extra.push({ id, ok: true });
+        }
+        catch (e) {
+            extra.push({ id, ok: e?.code === 'ENOENT', detail: e?.code === 'ENOENT' ? 'not configured' : 'invalid JSON' });
+        }
+    }
+    const checks = [...base.checks, ...extra];
+    const ok = checks.every((x) => x.ok);
+    /* R4 Q-R4-14 (a): `ok` keeps its meaning; `ready`, `status` and `reasons` are added. */
+    const turn = base.sections?.providers?.turn ?? { ready: false, reasons: [{ code: 'RUNTIME_NOT_AVAILABLE', message: t('firstrun.doctor.unknown') }] };
+    const verdict = doctorVerdict({ ok, checks, turn });
+    return { ...base, ok, ready: verdict.ready, status: verdict.status, reasons: verdict.reasons, checks, version: CLI_VERSION, platform: platformId(), telemetry: false };
+}
+const MAX_LOG_FILES = 8, MAX_LOG_TAIL_BYTES = 32 * 1024, MAX_LOG_LINE_CHARS = 4096;
+function boundedLine(value) { return value.length <= MAX_LOG_LINE_CHARS ? value : value.slice(0, MAX_LOG_LINE_CHARS - 1) + '…'; }
+async function readLogs(root, tail, bounded = false) {
+    let files = [];
+    try {
+        files = (await readdir(root)).filter(f => f.endsWith('.log')).sort();
+    }
+    catch {
+        return [];
+    }
+    if (bounded)
+        files = files.slice(-MAX_LOG_FILES);
+    const rows = [];
+    for (const file of files) {
+        const target = join(root, file);
+        try {
+            if (!bounded) {
+                const text = await readFile(target, 'utf8');
+                const lines = text.split(/\r?\n/u).filter(Boolean).slice(-tail);
+                rows.push({ file, lines });
+                continue;
+            }
+            const info = await stat(target);
+            if (!info.isFile())
+                continue;
+            const bytes = Math.min(info.size, MAX_LOG_TAIL_BYTES), start = Math.max(0, info.size - bytes), buffer = Buffer.alloc(bytes), handle = await open(target, 'r');
+            try {
+                await handle.read(buffer, 0, bytes, start);
+            }
+            finally {
+                await handle.close();
+            }
+            let text = buffer.toString('utf8');
+            if (start > 0) {
+                const cut = text.indexOf('\n');
+                text = cut >= 0 ? text.slice(cut + 1) : '';
+            }
+            const lines = text.split(/\r?\n/u).filter(Boolean).slice(-tail).map(boundedLine);
+            rows.push({ file, lines, truncated: start > 0 });
+        }
+        catch {
+            continue;
+        }
+    }
+    return rows;
+}
+async function diagnosticBundle(ctx, args, deps = {}) {
+    const out = takeOption(args, '--out');
+    if (!out)
+        throw new Error('DIAGNOSTIC_OUT_REQUIRED');
+    if (takeFlag(args, '--include-content'))
+        throw new Error('DIAGNOSTIC_CONTENT_EXPORT_DISABLED');
+    assertNoUnknownOptions(args);
+    const doctor = await doctorData(ctx, deps, { profile: false });
+    const config = await loadEffectiveConfig({ paths: ctx.paths, projectRoot: ctx.projectRoot });
+    const logs = await readLogs(ctx.paths.logsRoot, 200, true);
+    const secrets = secretValuesFromEnvironment(process.env);
+    const pseudonymizer = createPathPseudonymizer([homedir(), process.cwd(), ctx.projectRoot, ctx.repoRoot, ctx.paths.configRoot, ctx.paths.dataRoot, ctx.paths.cacheRoot, ctx.paths.sessionsRoot, ctx.paths.logsRoot]);
+    const safe = (value) => pseudonymizer.value(redactObject(value, secrets));
+    const entries = [
+        { name: 'manifest.json', data: JSON.stringify({ schema: 'talos.cli.diagnostic.v1', createdAt: new Date().toISOString(), version: CLI_VERSION, platform: platformId(), includesContent: false, pathPseudonymized: true, logLimits: { files: MAX_LOG_FILES, tailBytesPerFile: MAX_LOG_TAIL_BYTES, lineChars: MAX_LOG_LINE_CHARS } }, null, 2) },
+        { name: 'doctor.json', data: JSON.stringify(safe(doctor), null, 2) },
+        { name: 'config.json', data: JSON.stringify(safe(config.value), null, 2) },
+        { name: 'logs.json', data: JSON.stringify(safe(logs), null, 2) },
+    ];
+    await mkdir(resolve(out, '..'), { recursive: true });
+    await writeStoredZip(resolve(out), entries);
+    writeValue(ctx, { ok: true, file: resolve(out), includeContent: false }, `Diagnostic bundle: ${resolve(out)}\n`);
+    return 0;
+}
+async function updateCommand(ctx, args, deps = {}) {
+    if (await hasActiveRuns(ctx.paths))
+        throw Object.assign(new Error('UPDATE_ACTIVE_RUN'), { code: 'UPDATE_ACTIVE_RUN' });
+    const checkOnly = takeFlag(args, '--check');
+    const channel = (takeOption(args, '--channel') ?? process.env.TALOS_CLI_UPDATE_CHANNEL ?? 'stable');
+    if (channel !== 'stable' && channel !== 'preview')
+        throw new Error('UPDATE_CHANNEL_INVALID');
+    assertNoUnknownOptions(args);
+    /* R7 (owner 2026-09-25): an npm install asks the registry and says the npm command; nothing is downloaded or changed. */
+    if (installedWithNpm(deps.update?.packageRoot)) {
+        const npm = await checkNpmRegistry({ currentVersion: CLI_VERSION, channel, ...(deps.update?.fetchFn ? { fetchFn: deps.update.fetchFn } : {}) });
+        writeValue(ctx, npm, `${npm.available ? t('common.update.npmAvailable', { version: npm.version, current: npm.currentVersion, command: npm.command }) : t('common.update.upToDate')}\n`);
+        return 0;
+    }
+    const url = process.env.TALOS_CLI_UPDATE_MANIFEST_URL ?? await discoverGitHubReleaseManifest({ channel });
+    const result = await performUpdateCheck({ currentVersion: CLI_VERSION, channel, platform: platformId(), manifestUrl: url });
+    if (checkOnly || !result.available) {
+        writeValue(ctx, { ...result, manifest: undefined }, result.available ? `Update ${result.version} available\n` : 'TALOS CLI is up to date\n');
+        return 0;
+    }
+    if (!result.asset)
+        throw new Error('UPDATE_ASSET_NOT_FOUND');
+    const file = await downloadVerifiedUpdate({ asset: result.asset, cacheDir: join(ctx.paths.cacheRoot, 'updates') });
+    if (process.platform === 'win32' && result.asset.kind === 'installer') {
+        const child = spawn(file, ['/S', '/UPDATE=1'], { detached: true, stdio: 'ignore', windowsHide: true });
+        child.unref();
+        writeValue(ctx, { ok: true, version: result.version, installer: file, launched: true }, `Launching TALOS CLI ${result.version} installer\n`);
+        return 0;
+    }
+    writeValue(ctx, { ok: true, version: result.version, file, launched: false }, `Verified update downloaded to ${file}; install it manually on this platform\n`);
+    return 0;
+}
+async function initProject(ctx, args) { assertNoUnknownOptions(args); const dir = join(ctx.projectRoot, '.talos-cli'); await mkdir(join(dir, 'commands'), { recursive: true }); await mkdir(join(dir, 'extensions'), { recursive: true }); const file = join(dir, 'config.json'); try {
+    await stat(file);
+}
+catch {
+    await writeFile(file, '{}\n', { encoding: 'utf8', mode: 0o600 });
+} writeValue(ctx, { ok: true, directory: dir }, `Initialized ${dir}\n`); return 0; }
+export async function runSystemCommand(ctx, family, args0, deps = {}) { const args = [...args0]; if (family === 'doctor') {
+    const json = takeFlag(args, '--json'), profile = takeFlag(args, '--profile');
+    assertNoUnknownOptions(args);
+    const r = await doctorData(ctx, deps, { profile });
+    if (json || ctx.invocation.outputFormat === 'json')
+        ctx.io.writeOut(`${JSON.stringify(r)}\n`);
+    else {
+        const verdict = doctorVerdict({ ok: r.ok, checks: r.checks, turn: { ready: r.ready, reasons: r.reasons } });
+        ctx.io.writeOut(`${verdict.headline}${profile ? ' · profiled' : ''}\n`);
+        for (const c of r.checks)
+            ctx.io.writeOut(`${c.ok ? 'OK ' : 'ERR'} ${c.id}${c.detail ? `: ${c.detail}` : ''}\n`);
+        for (const [name, section] of Object.entries(r.sections))
+            ctx.io.writeOut(`INFO ${name}: ${name === 'credentials' ? credentialsLine(section) : name === 'catalog' ? catalogLine(section) : String(section?.state ?? 'unknown')}\n`);
+        const readiness = r.sections.providers?.activeModel;
+        if (readiness && !readiness.ready && readiness.message)
+            ctx.io.writeOut(`INFO provider: ${readiness.message}\n`);
+        if (r.performance)
+            ctx.io.writeOut(`INFO performance: rss=${r.performance.rssBytes} bytes\n`);
+    }
+    return doctorVerdict({ ok: r.ok, checks: r.checks, turn: { ready: r.ready, reasons: r.reasons } }).exitCode;
+} if (family === 'logs') {
+    const tailRaw = takeOption(args, '--tail') ?? '100';
+    assertNoUnknownOptions(args);
+    const tail = Number(tailRaw);
+    if (!Number.isSafeInteger(tail) || tail < 1 || tail > 10000)
+        throw new Error('LOG_TAIL_INVALID');
+    const rows = await readLogs(ctx.paths.logsRoot, tail);
+    writeValue(ctx, rows, rows.flatMap(r => [`== ${r.file} ==`, ...r.lines]).join('\n') + (rows.length ? '\n' : ''));
+    return 0;
+} if (family === 'diagnostic') {
+    const op = args.shift();
+    if (op !== 'bundle')
+        throw new Error('DIAGNOSTIC_OPERATION_REQUIRED');
+    return diagnosticBundle(ctx, args, deps);
+} if (family === 'update')
+    return updateCommand(ctx, args, deps); if (family === 'init')
+    return initProject(ctx, args); throw new Error(`Unsupported system command: ${family}`); }

package/dist/config/commands.js

@@ -0,0 +1,60 @@
+import { readConfigScope, replaceConfigScope } from "./load.js";
+/* R5a (Q-R5-3): `models.<id>.<key>` — a model id has `:` and often `.` (`openai:gpt-4.1`), the separator itself, so for this
+   one branch everything between `models.` and the last key is the id. Every other path keeps the strict segment rule. */
+const MODEL_ID = /^[A-Za-z0-9][A-Za-z0-9:._/-]*$/u, SEGMENT = /^[A-Za-z][A-Za-z0-9_-]*$/u;
+function parts(path) {
+    const raw = String(path ?? '');
+    if (raw.startsWith('models.')) {
+        const rest = raw.slice('models.'.length), cut = rest.lastIndexOf('.');
+        if (cut > 0) {
+            const id = rest.slice(0, cut), key = rest.slice(cut + 1);
+            if (MODEL_ID.test(id) && !id.includes('..') && SEGMENT.test(key))
+                return ['models', id, key];
+        }
+        if (rest && MODEL_ID.test(rest) && !rest.includes('..') && !rest.endsWith('.'))
+            return ['models', rest];
+        throw new Error('CONFIG_PATH_INVALID');
+    }
+    const p = raw.split('.').filter(Boolean);
+    if (!p.length || p.some(x => !SEGMENT.test(x)))
+        throw new Error('CONFIG_PATH_INVALID');
+    return p;
+}
+export function configGet(value, path) { let cursor = value; for (const p of parts(path)) {
+    if (!cursor || typeof cursor !== 'object' || Array.isArray(cursor) || !Object.hasOwn(cursor, p))
+        throw new Error('CONFIG_PATH_NOT_FOUND');
+    cursor = cursor[p];
+} return structuredClone(cursor); }
+function setAt(root, path, value) { const ps = parts(path); let c = root; for (const p of ps.slice(0, -1)) {
+    const old = c[p];
+    if (old === undefined)
+        c[p] = {};
+    else if (!old || typeof old !== 'object' || Array.isArray(old))
+        throw new Error('CONFIG_PATH_CONFLICT');
+    c = c[p];
+} c[ps.at(-1)] = structuredClone(value); }
+function unsetAt(root, path) { const ps = parts(path); const stack = []; let c = root; for (const p of ps.slice(0, -1)) {
+    if (!c[p] || typeof c[p] !== 'object' || Array.isArray(c[p]))
+        return;
+    stack.push([c, p]);
+    c = c[p];
+} delete c[ps.at(-1)]; for (let i = stack.length - 1; i >= 0; i--) {
+    const [parent, key] = stack[i];
+    const node = parent[key];
+    if (node && typeof node === 'object' && !Array.isArray(node) && Object.keys(node).length === 0)
+        delete parent[key];
+    else
+        break;
+} }
+export async function configSet({ paths, projectRoot, scope, path, value }) { const current = await readConfigScope({ paths, projectRoot, scope }); const next = structuredClone(current); setAt(next, path, value); await replaceConfigScope({ paths, projectRoot, scope, value: next }); }
+export async function configUnset({ paths, projectRoot, scope, path }) { const current = await readConfigScope({ paths, projectRoot, scope }); const next = structuredClone(current); unsetAt(next, path); await replaceConfigScope({ paths, projectRoot, scope, value: next }); }
+function leaves(v, prefix = '') { if (v && typeof v === 'object' && !Array.isArray(v)) {
+    return Object.entries(v).flatMap(([k, x]) => leaves(x, prefix ? `${prefix}.${k}` : k));
+} return prefix ? [{ path: prefix, value: v }] : []; }
+/** The origin of a leaf: its own, else the NEAREST recorded ancestor's (R0: was the top-level key's, which named user keymap overrides `default`). */
+function originOf(effective, path) { const p = path.split('.'); for (let i = p.length; i > 0; i--) {
+    const found = effective.origins.get(p.slice(0, i).join('.'));
+    if (found !== undefined)
+        return found;
+} return 'default'; }
+export function configOrigins(effective) { return leaves(effective.value).map(row => ({ ...row, origin: originOf(effective, row.path) })); }