@oscharko-dev/keiko 0.2.0-beta.4 → 0.2.0-beta.6

package/node_modules/@oscharko-dev/keiko-cli/dist/memory.js

@@ -4,26 +4,34 @@
 //              forget) against the local vault and print the applied counts. Reuses the exact same
 //              `runMemoryMaintenance` core the BFF route uses, so the CLI and UI never drift.
 //   stats      Print memory counts by status, by scope kind, and the total.
+//   diagnostics
+//              Print a redacted body-free diagnostics snapshot for local support.
 //
 // The vault is opened at the resolved memory dir (default $KEIKO_MEMORY_DIR or the platform state
 // dir; override with --memory-dir). Tests inject a vault via deps so no disk is touched. Exit 0 on
 // success, 1 on a runtime error (vault open / maintenance fault), 2 on usage (unknown/missing
 // subcommand).
 import { createMemoryVault } from "@oscharko-dev/keiko-memory-vault";
-import { createMemoryEmbedder, runMemoryMaintenance, } from "@oscharko-dev/keiko-server";
+import { createMemoryEmbedder, exportMemoryDiagnostics, runMemoryMaintenance, } from "@oscharko-dev/keiko-server";
+import { createAuditRedactor, createNodeEvidenceStore, resolveEvidenceDir, } from "@oscharko-dev/keiko-evidence";
 import { loadConfigFromFile, requestOpenAIEmbedding, GatewayError, } from "@oscharko-dev/keiko-model-gateway";
 const USAGE = `Usage:
-  keiko memory maintain [--memory-dir PATH]   Run a bounded consolidate + decay + forget pass.
+  keiko memory maintain [--memory-dir PATH] [--evidence-dir PATH]
+                                              Run a bounded consolidate + decay + forget pass.
   keiko memory stats [--memory-dir PATH]      Print memory counts by status and scope.
+  keiko memory diagnostics [--memory-dir PATH] [--evidence-dir PATH] [--last N]
+                                              Print redacted local diagnostics JSON.
   keiko memory reembed [--memory-dir PATH] [--limit N] [--config PATH]
                                               Backfill embeddings for accepted memories lacking one.
 
 Opens the local memory vault (default $KEIKO_MEMORY_DIR or the platform state dir; override with
 --memory-dir). \`maintain\` strengthens recalled memories, decays stale ones, archives faded ones,
-forgets expired/very-faint ones, and auto-supersedes pairwise correction conflicts. \`reembed\`
-computes the embedding for each accepted memory that has none (bounded by --limit, default 200), so
-pre-existing memories become semantically retrievable; it is gated on an embedding model being
-configured (via --config / $KEIKO_CONFIG_FILE) and is best-effort.
+forgets expired/very-faint ones, and reports unresolved consolidation review items. \`diagnostics\`
+prints schema version, generated time, scope/status counts, redacted storage path, and a bounded
+audit tail without memory body or payload content. \`reembed\` computes the embedding for each
+accepted memory that has none (bounded by --limit, default 200), so pre-existing memories become
+semantically retrievable; it is gated on an embedding model being configured (via --config /
+$KEIKO_CONFIG_FILE) and is best-effort.
 `;
 const DEFAULT_REEMBED_LIMIT = 200;
 function flagValue(args, name) {
@@ -47,6 +55,31 @@ function resolveVault(args, env, deps) {
 function scopeKindOf(scope) {
     return scope.kind;
 }
+function scopeKey(scope) {
+    switch (scope.kind) {
+        case "user":
+            return `user:${scope.userId}`;
+        case "workspace":
+            return `workspace:${scope.workspaceId}`;
+        case "project":
+            return `project:${scope.projectId}`;
+        case "workflow":
+            return `workflow:${scope.workflowDefinitionId}`;
+        case "global":
+            return "global";
+        default: {
+            const never = scope;
+            return never;
+        }
+    }
+}
+function uniqueRecordScopes(records) {
+    const scopes = new Map();
+    for (const record of records) {
+        scopes.set(scopeKey(record.scope), record.scope);
+    }
+    return scopes.size === 0 ? [{ kind: "global" }] : [...scopes.values()];
+}
 function tallyBy(records, keyOf) {
     const counts = new Map();
     for (const record of records) {
@@ -80,6 +113,7 @@ function renderMaintenanceReport(counts) {
         `  superseded:        ${String(counts.superseded)}`,
         `  edgesCreated:      ${String(counts.edgesCreated)}`,
         `  clustersInspected: ${String(counts.clustersInspected)}`,
+        `  reviewItems:       ${String(counts.reviewItemsCreated)}`,
         "",
     ].join("\n");
 }
@@ -95,10 +129,43 @@ function runStats(args, io, env, deps) {
             vault.close();
     }
 }
+function parseLastAuditEvents(args) {
+    const raw = flagValue(args, "--last");
+    if (raw === undefined)
+        return undefined;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function runDiagnostics(args, io, env, deps) {
+    const vault = resolveVault(args, env, deps);
+    const evidenceDir = resolveEvidenceDir(flagValue(args, "--evidence-dir"), env);
+    const evidenceStore = deps.evidenceStore ?? createNodeEvidenceStore(evidenceDir);
+    const redactString = deps.redactString ?? createAuditRedactor({}, env);
+    try {
+        const records = vault.listMemories({ includeExpired: true });
+        const lastNAuditEvents = parseLastAuditEvents(args);
+        const diagnostics = exportMemoryDiagnostics({
+            vault,
+            scopes: uniqueRecordScopes(records),
+            evidenceStore,
+            redactString,
+            evidenceDir,
+            ...(lastNAuditEvents === undefined ? {} : { lastNAuditEvents }),
+        });
+        io.out(`${JSON.stringify(diagnostics, null, 2)}\n`);
+        return 0;
+    }
+    finally {
+        if (deps.vault === undefined)
+            vault.close();
+    }
+}
 function runMaintain(args, io, env, deps) {
     const vault = resolveVault(args, env, deps);
+    const evidenceDir = resolveEvidenceDir(flagValue(args, "--evidence-dir"), env);
+    const evidenceStore = deps.evidenceStore ?? createNodeEvidenceStore(evidenceDir);
     try {
-        const counts = runMemoryMaintenance(vault);
+        const counts = runMemoryMaintenance(vault, evidenceStore);
         io.out(renderMaintenanceReport(counts));
         return 0;
     }
@@ -200,6 +267,8 @@ function dispatchSubcommand(sub, args, io, env, deps) {
             return runMaintain(args, io, env, deps);
         if (sub === "stats")
             return runStats(args, io, env, deps);
+        if (sub === "diagnostics")
+            return runDiagnostics(args, io, env, deps);
         if (sub === "reembed")
             return runReembed(args, io, env, deps);
     }

package/node_modules/@oscharko-dev/keiko-cli/dist/run.d.ts

@@ -1,8 +1,10 @@
+import { type EnvSource } from "@oscharko-dev/keiko-model-gateway";
+import { type ModelPort } from "@oscharko-dev/keiko-harness";
 import { type EvidenceStore } from "@oscharko-dev/keiko-evidence";
-import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
 import type { CliIo } from "./runner.js";
 export interface RunDeps {
     readonly store?: EvidenceStore | undefined;
+    readonly model?: ModelPort | undefined;
 }
 export declare function runAgentCli(args: readonly string[], io: CliIo, env?: EnvSource, deps?: RunDeps): Promise<number>;
 //# sourceMappingURL=run.d.ts.map

package/node_modules/@oscharko-dev/keiko-cli/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAmBA,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAItC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAuBzC,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC5C;AA8JD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,GAAE,SAAc,EACnB,IAAI,GAAE,OAAY,GACjB,OAAO,CAAC,MAAM,CAAC,CA+BjB"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAUA,OAAO,EASL,KAAK,SAAS,EACf,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAoC,KAAK,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAQ/F,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAyBzC,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACxC;AA8PD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,GAAE,SAAc,EACnB,IAAI,GAAE,OAAY,GACjB,OAAO,CAAC,MAAM,CAAC,CAsCjB"}

package/node_modules/@oscharko-dev/keiko-cli/dist/run.js

@@ -1,13 +1,14 @@
-// `keiko run` — the dry-run task command. It builds an AgentSession wired to deterministic mocked
-// model/tool fixtures (no provider call, no real tools) and renders the HarnessEvent stream to
-// CliIo. Since ADR-0010 it ALSO writes a redacted evidence manifest by default (evidence is the
-// product value): a tee EventSink forwards every event to BOTH a MemoryEventSink (which retains raw
-// content to assemble the replay manifest) and the existing CliEventSink (whose summarisers never
-// print sensitive fields). After the run resolves, the audit layer builds + redacts + persists the
-// manifest and the EvidenceReport is printed. Writing is on by default; --no-evidence disables it,
-// --evidence-dir relocates it. Tests inject an in-memory EvidenceStore via deps so no write ever
-// touches the repository tree.
-import { DryRunToolPort } from "@oscharko-dev/keiko-harness";
+// `keiko run` — the dry-run task command. It builds an AgentSession with the configured model
+// gateway and a dry-run tool port (provider call is real, tools are non-mutating) and renders the
+// HarnessEvent stream to CliIo. Since ADR-0010 it ALSO writes a redacted evidence manifest by
+// default (evidence is the product value): a tee EventSink forwards every event to BOTH a
+// MemoryEventSink (which retains raw content to assemble the replay manifest) and the existing
+// CliEventSink (whose summarisers never print sensitive fields). After the run resolves, the audit
+// layer builds + redacts + persists the manifest and the EvidenceReport is printed. Writing is on by
+// default; --no-evidence disables it, --evidence-dir relocates it. Tests inject an in-memory
+// EvidenceStore via deps so no write ever touches the repository tree.
+import { ConfigInvalidError, Gateway, GatewayError, assertConfiguredModel, loadConfigFromFile, redact, resolveCostClass, selectConfiguredModel, } from "@oscharko-dev/keiko-model-gateway";
+import { DryRunToolPort, GatewayModelPort } from "@oscharko-dev/keiko-harness";
 import { createSession, HARNESS_VERSION } from "@oscharko-dev/keiko-harness";
 import { CliEventSink, MemoryEventSink } from "@oscharko-dev/keiko-harness";
 import { DEFAULT_LIMITS } from "@oscharko-dev/keiko-harness";
@@ -15,8 +16,6 @@ import { persistEvidence } from "@oscharko-dev/keiko-evidence";
 import { renderEvidenceReport } from "@oscharko-dev/keiko-evidence";
 import { createNodeEvidenceStore, resolveEvidenceDir, } from "@oscharko-dev/keiko-evidence";
 import { AuditError } from "@oscharko-dev/keiko-evidence";
-import { redact } from "@oscharko-dev/keiko-model-gateway";
-import { resolveCostClass } from "@oscharko-dev/keiko-model-gateway";
 const TASK_TYPES = new Set([
     "generate-unit-tests",
     "investigate-bug",
@@ -32,8 +31,10 @@ const USAGE = `Usage:
     --evidence-dir PATH      Write evidence under PATH (default $KEIKO_EVIDENCE_DIR or ./.keiko/evidence).
     --include-reasoning      Include redacted reasoning entries in the manifest.
     --include-diff           Include the redacted proposed diff in the manifest.
+    --config PATH            Gateway config file (or set KEIKO_CONFIG_FILE).
+    --model MODEL_ID         Configured model id to use.
 
-All tasks run in dry-run mode: a patch is proposed as an event, never written to disk.
+All tasks run in dry-run mode for tools/files: a patch is proposed as an event, never written to disk.
 `;
 function flag(args, name) {
     const i = args.indexOf(name);
@@ -49,24 +50,8 @@ function parseEvidenceFlags(args) {
         evidenceDirFlag: flag(args, "--evidence-dir"),
         includeReasoning: args.includes("--include-reasoning"),
         includeDiff: args.includes("--include-diff"),
-    };
-}
-// A deterministic, dependency-free canned final response. It never requests tools, so the dry-run
-// path is reproducible regardless of task type.
-function cannedResponse() {
-    return {
-        modelId: "mock-model",
-        content: "--- a/file\n+++ b/file\n+// dry-run proposed change\n",
-        finishReason: "stop",
-        toolCalls: [],
-        structuredOutput: null,
-        usage: {
-            requestId: "dry-run",
-            promptTokens: 0,
-            completionTokens: 0,
-            latencyMs: 1,
-            costClass: "low",
-        },
+        model: flag(args, "--model"),
+        config: flag(args, "--config"),
     };
 }
 function parseTask(taskType, args) {
@@ -96,13 +81,60 @@ function teeSink(sinks) {
     return {
         retainsRawContent: true,
         emit: (event) => {
+            const redacted = redactEventForNonRetainingSink(event);
             for (const sink of sinks) {
-                sink.emit(event);
+                sink.emit(sink.retainsRawContent === true ? event : redacted);
             }
         },
     };
 }
-function seedFor(task, result) {
+function redactEventForNonRetainingSink(event) {
+    if (event.type === "run:failed") {
+        return redactRunFailedEvent(event);
+    }
+    if (event.type === "run:completed") {
+        return redactRunCompletedEvent(event);
+    }
+    if (event.type === "reasoning:trace") {
+        return redactReasoningTraceEvent(event);
+    }
+    if (event.type === "run:cancelled" && event.reason !== undefined) {
+        return { ...event, reason: redact(event.reason) };
+    }
+    if (event.type === "model:call:failed" || event.type === "tool:call:failed") {
+        return { ...event, message: redact(event.message) };
+    }
+    if (event.type === "patch:proposed")
+        return { ...event, diff: redact(event.diff) };
+    if (event.type === "verification:result")
+        return { ...event, detail: redact(event.detail) };
+    return event;
+}
+function redactRunFailedEvent(event) {
+    return {
+        ...event,
+        failure: {
+            ...event.failure,
+            message: redact(event.failure.message),
+            ...(event.failure.detail === undefined ? {} : { detail: redact(event.failure.detail) }),
+        },
+    };
+}
+function redactRunCompletedEvent(event) {
+    return {
+        ...event,
+        report: redact(event.report),
+        ...(event.patchDiff === undefined ? {} : { patchDiff: redact(event.patchDiff) }),
+    };
+}
+function redactReasoningTraceEvent(event) {
+    return {
+        ...event,
+        rationale: redact(event.rationale),
+        ...(event.modelResponse === undefined ? {} : { modelResponse: redact(event.modelResponse) }),
+    };
+}
+function seedFor(task, result, modelId) {
     return {
         runId: result.runId,
         fingerprint: result.fingerprint,
@@ -110,7 +142,7 @@ function seedFor(task, result) {
         taskType: task.taskType,
         taskInput: task,
         limits: DEFAULT_LIMITS,
-        modelId: "mock-model",
+        modelId,
         workingDirectory: ".",
         dryRun: true,
         startedAt: new Date(result.startedAt).toISOString(),
@@ -120,9 +152,9 @@ function seedFor(task, result) {
 // correct here (CLAUDE.md): on any failure — typed AuditError or otherwise — print a REDACTED
 // message and return exit 1 rather than rejecting out of runAgentCli as an unhandled rejection (C3).
 // Returns undefined on success so the caller falls through to the run-outcome exit code.
-function writeEvidence(result, memory, task, ctx, io) {
+function writeEvidence(result, memory, task, ctx, io, modelId) {
     try {
-        const manifest = memory.collectManifest(seedFor(task, result));
+        const manifest = memory.collectManifest(seedFor(task, result, modelId));
         const store = ctx.deps.store ??
             createNodeEvidenceStore(resolveEvidenceDir(ctx.flags.evidenceDirFlag, ctx.env));
         const out = persistEvidence({
@@ -142,6 +174,52 @@ function writeEvidence(result, memory, task, ctx, io) {
         return 1;
     }
 }
+function configuredModelId(flags, env) {
+    const path = flags.config ?? env.KEIKO_CONFIG_FILE;
+    if (path === undefined) {
+        return flags.model;
+    }
+    const config = loadConfigFromFile(path, env);
+    if (flags.model !== undefined) {
+        assertConfiguredModel(config, flags.model);
+        return flags.model;
+    }
+    return selectConfiguredModel(config, { kind: "chat" });
+}
+function resolveModel(flags, io, env, deps) {
+    try {
+        if (deps.model !== undefined) {
+            const modelId = configuredModelId(flags, env);
+            if (modelId === undefined) {
+                io.err("Error: no model id available; pass --model MODEL_ID for injected test runs.\n");
+                return 1;
+            }
+            return { port: deps.model, modelId };
+        }
+        const path = flags.config ?? env.KEIKO_CONFIG_FILE;
+        if (path === undefined) {
+            throw new ConfigInvalidError("no config source; pass --config PATH or set KEIKO_CONFIG_FILE");
+        }
+        const config = loadConfigFromFile(path, env);
+        if (flags.model !== undefined) {
+            assertConfiguredModel(config, flags.model);
+        }
+        const modelId = flags.model ?? selectConfiguredModel(config, { kind: "chat" });
+        if (modelId === undefined) {
+            io.err("Error: no configured chat model is available.\n");
+            return 1;
+        }
+        return { port: new GatewayModelPort(new Gateway(config)), modelId };
+    }
+    catch (error) {
+        if (error instanceof GatewayError) {
+            io.err(`Error: model gateway configuration problem — ${redact(error.message)}\n` +
+                `Provide a gateway config with --config PATH or KEIKO_CONFIG_FILE.\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
 function outcomeToExitCode(result, io) {
     if (result.outcome === "completed") {
         io.out(`run ${result.runId} completed (fingerprint ${result.fingerprint})\n`);
@@ -152,7 +230,8 @@ function outcomeToExitCode(result, io) {
         return 1;
     }
     const category = result.failure?.category ?? "HARNESS_INTERNAL";
-    io.err(`run ${result.runId} ${result.outcome} [${category}]: ${result.failure?.message ?? ""}\n`);
+    const message = redact(result.failure?.message ?? "");
+    io.err(`run ${result.runId} ${result.outcome} [${category}]: ${message}\n`);
     return 1;
 }
 export async function runAgentCli(args, io, env = {}, deps = {}) {
@@ -167,19 +246,20 @@ export async function runAgentCli(args, io, env = {}, deps = {}) {
         return 2;
     }
     const flags = parseEvidenceFlags(args);
-    const response = cannedResponse();
+    const model = resolveModel(flags, io, env, deps);
+    if (typeof model === "number") {
+        return model;
+    }
     const memory = new MemoryEventSink();
-    const config = { model: "mock-model", workingDirectory: ".", dryRun: true };
+    const config = { model: model.modelId, workingDirectory: ".", dryRun: true };
     const session = createSession(task, config, {
-        model: {
-            call: (request) => Promise.resolve({ ...response, modelId: request.modelId }),
-        },
+        model: model.port,
         tools: new DryRunToolPort(),
         sink: teeSink([memory, new CliEventSink(io)]),
     });
     const result = await session.result;
     if (flags.write) {
-        const evidenceFailure = writeEvidence(result, memory, task, { flags, env, deps }, io);
+        const evidenceFailure = writeEvidence(result, memory, task, { flags, env, deps }, io, model.modelId);
         if (evidenceFailure !== undefined) {
             return evidenceFailure;
         }

package/node_modules/@oscharko-dev/keiko-cli/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAKnE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAmED,wBAAgB,MAAM,CACpB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,GAAE,SAAc,GAClB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiB1B"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAKnE,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC;AAiFD,wBAAgB,MAAM,CACpB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,GAAE,SAAc,GAClB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB1B"}

package/node_modules/@oscharko-dev/keiko-cli/dist/runner.js

@@ -11,6 +11,7 @@ import { runInitCli } from "./init.js";
 import { runLifecycleCli } from "./lifecycle.js";
 import { runUiCli } from "./ui.js";
 import { runLauncherCli } from "./launcher.js";
+import { emitDoctorWarning, runDoctorCli } from "./doctor.js";
 import { SDK_VERSION } from "@oscharko-dev/keiko-sdk";
 const HELP_TEXT = `keiko ${SDK_VERSION}
 Enterprise model-agnostic developer-assist coding agent.
@@ -19,6 +20,7 @@ Usage:
   keiko [--help | -h]      Print this help and exit.
   keiko [--version | -v]   Print the version and exit.
   keiko init [OPTIONS]     Add local package.json start/stop scripts.
+  keiko doctor             Diagnose stale global-vs-local launch paths.
   keiko start|stop|status|restart Manage the local Keiko UI process.
   keiko models list        List registered model capabilities.
   keiko models validate    Validate gateway configuration.
@@ -50,6 +52,7 @@ const COMMAND_HANDLERS = {
     evaluate: (rest, io, env) => runEvaluateCli(rest, io, env, {}),
     memory: (rest, io, env) => runMemoryCli(rest, io, env),
     init: runInitCli,
+    doctor: runDoctorCli,
     start: (rest, io, env) => runLifecycleCli("start", rest, io, env),
     stop: (rest, io, env) => runLifecycleCli("stop", rest, io, env),
     status: (rest, io, env) => runLifecycleCli("status", rest, io, env),
@@ -61,10 +64,7 @@ const COMMAND_HANDLERS = {
 function dispatchCommand(name, rest, io, env) {
     return COMMAND_HANDLERS[name]?.(rest, io, env);
 }
-// Returns a number for synchronous commands; the async `run` command returns a Promise.
-// The process shim in index.ts awaits the union before calling process.exit.
-export function runCli(args, io, env = {}) {
-    const first = args[0];
+function handleMetaCommand(first, io) {
     if (first === undefined || first === "--help" || first === "-h") {
         io.out(HELP_TEXT);
         return 0;
@@ -73,6 +73,22 @@ export function runCli(args, io, env = {}) {
         io.out(`keiko ${SDK_VERSION}\n`);
         return 0;
     }
+    return undefined;
+}
+// Returns a number for synchronous commands; the async `run` command returns a Promise.
+// The process shim in index.ts awaits the union before calling process.exit.
+export function runCli(args, io, env = {}) {
+    const first = args[0];
+    const meta = handleMetaCommand(first, io);
+    if (meta !== undefined)
+        return meta;
+    if (first === undefined) {
+        io.err("keiko: internal error while dispatching command.\n");
+        return 2;
+    }
+    if (first === "start" || first === "ui") {
+        emitDoctorWarning(io);
+    }
     const result = dispatchCommand(first, args.slice(1), io, env);
     if (result !== undefined) {
         return result;

package/node_modules/@oscharko-dev/keiko-cli/dist/ui.d.ts

@@ -28,7 +28,7 @@ export type SpawnFn = (command: string, args: readonly string[], opts: SpawnOpti
 export declare function parseUiArgs(args: readonly string[]): UiParseResult;
 export declare function applyServerTimeouts(server: Server): void;
 export declare function waitForShutdown(server: Server): Promise<void>;
-export declare function reExecWithSqliteFlag(_env: EnvSource, spawnFn: SpawnFn): Promise<number>;
+export declare function reExecWithSqliteFlag(_env: EnvSource, spawnFn: SpawnFn, cwd: string): Promise<number>;
 export declare function runUiCli(args: readonly string[], io: CliIo, env: EnvSource, deps?: UiCliDeps): Promise<number>;
 export {};
 //# sourceMappingURL=ui.d.ts.map

package/node_modules/@oscharko-dev/keiko-cli/dist/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAKxC,OAAO,EAAS,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAmBzC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,KAAK,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAa/C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAC7B,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,aAAa,CAAC;KAC5B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAI7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAG3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAEnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,MAAM,OAAO,GAAG,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,YAAY,KACf,YAAY,CAAC;AA8DlB,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CAYlE;AAkFD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGxD;AAWD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB7D;AA0BD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAwB7F;AAqGD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,SAAc,GACnB,OAAO,CAAC,MAAM,CAAC,CAuBjB"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAKxC,OAAO,EAAS,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAOL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAkBzC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,KAAK,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAAC;AAa/C,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAC7B,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,aAAa,CAAC;KAC5B,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAI7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAG3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IAEnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAED,MAAM,MAAM,OAAO,GAAG,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,YAAY,KACf,YAAY,CAAC;AA8DlB,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,aAAa,CAYlE;AAoFD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGxD;AAWD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB7D;AA0BD,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,SAAS,EACf,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAwBjB;AAyGD,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,KAAK,EACT,GAAG,EAAE,SAAS,EACd,IAAI,GAAE,SAAc,GACnB,OAAO,CAAC,MAAM,CAAC,CAuBjB"}

package/node_modules/@oscharko-dev/keiko-cli/dist/ui.js

@@ -16,14 +16,14 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { createUiServer, loadCspHeader, buildUiHandlerDeps, DEFAULT_UI_PORT, UI_HOST, UiStoreError, } from "@oscharko-dev/keiko-server";
+import { resolvePreferredInstallLayout } from "./install-layout.js";
 const ALLOWED_HOSTS = new Set(["127.0.0.1", "localhost"]);
 const SQLITE_FLAG = "--experimental-sqlite";
-const KEIKO_ENV_NAME_RE = /^KEIKO_[A-Z0-9_]+$/;
-// Non-KEIKO names the local .env loader may import. Deliberately a closed allowlist —
-// arbitrary secrets must never be slurped into the server process. FIGMA_ACCESS_TOKEN is
-// part of the documented Figma connector contract (#751): the read-only PAT is configured
-// via .env and consumed server-side only.
-const ENV_NAME_ALLOWLIST = new Set(["FIGMA_ACCESS_TOKEN"]);
+// Deliberately a closed allowlist: repo-local .env discovery must not import KEIKO_*
+// runtime configuration because the UI may be launched from an untrusted project root.
+// FIGMA_ACCESS_TOKEN is the documented Figma connector exception (#751); it is consumed
+// server-side only and never sent to the browser.
+const LOCAL_DOTENV_ENV_NAME_ALLOWLIST = new Set(["FIGMA_ACCESS_TOKEN"]);
 const DEFAULT_STATE_DIR = ".keiko";
 const USAGE = `Usage:
   keiko ui [--port PORT] [--host 127.0.0.1|localhost] [--evidence-dir PATH] [--config PATH] [--ui-db PATH]
@@ -102,7 +102,10 @@ export function parseUiArgs(args) {
     }
     return { port, evidenceDir: evidenceRaw, config: configRaw, uiDbPath: uiDbRaw };
 }
-function defaultStaticRoot() {
+function defaultStaticRoot(cwd) {
+    const preferredLayout = resolvePreferredInstallLayout(cwd);
+    if (preferredLayout !== undefined)
+        return preferredLayout.staticRoot;
     // The root bin shim (`dist/cli/index.js`) surfaces `KEIKO_UI_STATIC_ROOT` so the
     // cli package does not have to know its own installation layout. The
     // import.meta.url fallback preserves the standalone behaviour for callers that
@@ -138,7 +141,7 @@ function loadLocalKeikoEnv(cwd, env) {
         if (equals <= 0)
             continue;
         const key = line.slice(0, equals).trim();
-        if (!KEIKO_ENV_NAME_RE.test(key) && !ENV_NAME_ALLOWLIST.has(key))
+        if (!LOCAL_DOTENV_ENV_NAME_ALLOWLIST.has(key))
             continue;
         if (merged[key] !== undefined)
             continue;
@@ -229,8 +232,8 @@ function alreadyFlagged(env, execArgv) {
 }
 // Re-spawns the current process with --experimental-sqlite prepended, inheriting stdio. Returns
 // the exit code the child terminated with so the parent can propagate it.
-export async function reExecWithSqliteFlag(_env, spawnFn) {
-    const entry = process.argv[1];
+export async function reExecWithSqliteFlag(_env, spawnFn, cwd) {
+    const entry = resolvePreferredInstallLayout(cwd)?.binPath ?? process.argv[1];
     if (entry === undefined)
         return 1;
     const childArgs = [SQLITE_FLAG, ...process.execArgv, entry, ...process.argv.slice(2)];
@@ -258,7 +261,7 @@ export async function reExecWithSqliteFlag(_env, spawnFn) {
 // Returns undefined when no re-exec is needed; returns the child's exit code when a re-exec
 // happened. The guard never runs when an injected test factory bypasses the production loop, and
 // it never re-loops once --experimental-sqlite is already in execArgv.
-async function maybeReExecForSqlite(env, deps) {
+async function maybeReExecForSqlite(env, deps, cwd) {
     if (deps.createServer !== undefined)
         return undefined;
     const execArgv = (deps.currentExecArgv ?? (() => process.execArgv))();
@@ -268,7 +271,7 @@ async function maybeReExecForSqlite(env, deps) {
     if (probe())
         return undefined;
     const spawnFn = deps.spawnFn ?? spawn;
-    return reExecWithSqliteFlag(env, spawnFn);
+    return reExecWithSqliteFlag(env, spawnFn, cwd);
 }
 function buildHandlerDepsOrReport(parsed, cwd, effectiveEnv, io) {
     try {
@@ -342,10 +345,10 @@ export async function runUiCli(args, io, env, deps = {}) {
     const parsed = parseUiArgsOrExit(args, io);
     if (typeof parsed === "number")
         return parsed;
-    const reExec = await maybeReExecForSqlite(effectiveEnv, deps);
+    const reExec = await maybeReExecForSqlite(effectiveEnv, deps, cwd);
     if (reExec !== undefined)
         return reExec;
-    const staticRoot = deps.staticRoot ?? defaultStaticRoot();
+    const staticRoot = deps.staticRoot ?? defaultStaticRoot(cwd);
     if (!ensureStaticRoot(staticRoot, io)) {
         return 1;
     }

package/node_modules/@oscharko-dev/keiko-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oscharko-dev/keiko-cli",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.6",
   "private": true,
   "type": "module",
   "license": "Apache-2.0",