@oscharko-dev/keiko-cli 0.2.0

package/dist/runner.d.ts

@@ -0,0 +1,7 @@
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+export interface CliIo {
+    readonly out: (text: string) => void;
+    readonly err: (text: string) => void;
+}
+export declare function runCli(args: readonly string[], io: CliIo, env?: EnvSource): number | Promise<number>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAiBA,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;AAuFD,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/dist/runner.js

@@ -0,0 +1,108 @@
+import { runModelsCli } from "./models.js";
+import { runAgentCli } from "./run.js";
+import { runContextCli } from "./context.js";
+import { runVerifyCli } from "./verify.js";
+import { runGenTestsCli } from "./gen-tests.js";
+import { runInvestigateCli } from "./investigate.js";
+import { runEvidenceCli } from "./evidence.js";
+import { runEvaluateCli } from "./evaluate.js";
+import { runPromptEnhancerCli } from "./prompt-enhancer.js";
+import { runMemoryCli } from "./memory.js";
+import { runInitCli } from "./init.js";
+import { runLifecycleCli } from "./lifecycle.js";
+import { runUiCli } from "./ui.js";
+import { runLauncherCli } from "./launcher.js";
+import { runUninstallCli } from "./uninstall.js";
+import { runRepairCli } from "./repair.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.
+
+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 repair [OPTIONS]   Repair a broken local install (offline remediation pass).
+  keiko uninstall [OPTIONS] Remove Keiko's runtime artifacts (state, shortcuts, scripts).
+  keiko start|stop|status|restart Manage the local Keiko UI process.
+  keiko models list        List registered model capabilities.
+  keiko models validate    Validate gateway configuration.
+  keiko run <task>         Run a bounded dry-run task through the agent harness.
+  keiko context [OPTIONS]  Print a redacted workspace context summary (dry-run).
+  keiko verify [OPTIONS]   Run the project's gates and print a redacted evidence summary.
+  keiko gen-tests [OPTIONS] Generate a reviewable unit-test patch (dry-run by default).
+  keiko investigate [OPTIONS] Investigate a bug and propose a fix + regression test (dry-run by default).
+  keiko evidence <list|show> Inspect redacted evidence manifests written by \`keiko run\`.
+  keiko evaluate [OPTIONS]     Run the evaluation harness (offline by default; --live for live model).
+  keiko prompt-enhancer [OPTIONS] Enhance a raw prompt into a governed, reviewable Enhanced Prompt.
+  keiko memory <maintain|stats> Run a memory maintenance pass or print vault stats (#204).
+  keiko ui [OPTIONS]       Launch the local UI on 127.0.0.1 and print its URL.
+  keiko launcher <install|remove|status> [OPTIONS]
+                           Manage a user-local OS shortcut for \`keiko start --open\`.
+
+Exit codes:
+  0  Success
+  1  Runtime error
+  2  Usage error
+`;
+const COMMAND_HANDLERS = {
+    models: runModelsCli,
+    run: runAgentCli,
+    context: (rest, io) => runContextCli(rest, io),
+    verify: (rest, io) => runVerifyCli(rest, io),
+    "gen-tests": runGenTestsCli,
+    investigate: runInvestigateCli,
+    evidence: (rest, io, env) => runEvidenceCli(rest, io, { env }),
+    evaluate: (rest, io, env) => runEvaluateCli(rest, io, env, {}),
+    "prompt-enhancer": (rest, io, env) => runPromptEnhancerCli(rest, io, env, {}),
+    memory: (rest, io, env) => runMemoryCli(rest, io, env),
+    init: runInitCli,
+    doctor: runDoctorCli,
+    repair: runRepairCli,
+    uninstall: runUninstallCli,
+    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),
+    restart: (rest, io, env) => runLifecycleCli("restart", rest, io, env),
+    ui: runUiCli,
+    launcher: runLauncherCli,
+};
+// Dispatches named subcommands; returns undefined when the name is not recognised.
+function dispatchCommand(name, rest, io, env) {
+    return COMMAND_HANDLERS[name]?.(rest, io, env);
+}
+function handleMetaCommand(first, io) {
+    if (first === undefined || first === "--help" || first === "-h") {
+        io.out(HELP_TEXT);
+        return 0;
+    }
+    if (first === "--version" || first === "-v") {
+        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;
+    }
+    io.err(`keiko: unknown ${first.startsWith("-") ? "option" : "command"}: ${first}\n`);
+    io.err("Run `keiko --help` for usage.\n");
+    return 2;
+}

package/dist/state-paths.d.ts

@@ -0,0 +1,43 @@
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+export declare const DEFAULT_STATE_DIR_NAME = ".keiko";
+export declare const KEIKO_STATE_FILES: readonly ["ui.pid", "ui.log", "launcher-state.json"];
+export declare const LAUNCHER_STATE_TMP_PREFIX = ".launcher-state-";
+export declare function resolveStateDir(cwd: string, env: EnvSource, stateDirArg?: string): string;
+export declare function readPidFile(path: string): number | undefined;
+export declare function defaultIsProcessAlive(pid: number): boolean;
+export type PidState = "absent" | "stale" | "running";
+export interface PidClassification {
+    readonly state: PidState;
+    readonly pid: number | undefined;
+}
+export declare function classifyPid(pidFilePath: string, isAlive: (pid: number) => boolean): PidClassification;
+export declare const RUNTIME_STATE_DIR_MODE = 448;
+export declare const RUNTIME_STATE_FILE_MODE = 384;
+export type RuntimeStateCategory = "lifecycle" | "launcher" | "ui-database" | "gateway-config" | "credential-vault" | "memory-vault" | "local-knowledge" | "evidence" | "quality-intelligence";
+export interface RuntimeStateNode {
+    readonly relPath: string;
+    readonly absPath: string;
+    readonly category: RuntimeStateCategory;
+}
+export interface RetainedNode {
+    readonly relPath: string;
+    readonly absPath: string;
+    readonly reason: "unknown" | "symlink" | "hardlink";
+    readonly owned: boolean;
+}
+export interface RuntimeStateScan {
+    readonly root: StateRootInspection;
+    readonly present: boolean;
+    readonly files: readonly RuntimeStateNode[];
+    readonly directories: readonly RuntimeStateNode[];
+    readonly retained: readonly RetainedNode[];
+}
+export type StateRootStatus = "absent" | "directory" | "symlink" | "not-directory";
+export interface StateRootInspection {
+    readonly status: StateRootStatus;
+    readonly absPath: string;
+}
+export declare function inspectStateRoot(stateDir: string): StateRootInspection;
+export declare function scanRuntimeState(stateDir: string): RuntimeStateScan;
+export declare function isInsidePath(ancestor: string, descendant: string): boolean;
+//# sourceMappingURL=state-paths.d.ts.map

package/dist/state-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-paths.d.ts","sourceRoot":"","sources":["../src/state-paths.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAGnE,eAAO,MAAM,sBAAsB,WAAW,CAAC;AAI/C,eAAO,MAAM,iBAAiB,sDAAuD,CAAC;AAItF,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAK5D,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAMzF;AAID,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK5D;AAMD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAID,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,GAChC,iBAAiB,CAInB;AAsCD,eAAO,MAAM,sBAAsB,MAAQ,CAAC;AAC5C,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAmC7C,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,UAAU,GACV,aAAa,GACb,gBAAgB,GAChB,kBAAkB,GAClB,cAAc,GACd,iBAAiB,GACjB,UAAU,GACV,sBAAsB,CAAC;AAyM3B,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;CACzC;AAOD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,eAAe,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAWtE;AAsFD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAWnE;AAID,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAE1E"}

package/dist/state-paths.js

@@ -0,0 +1,396 @@
+// Shared resolution of Keiko's runtime state directory and the set of files Keiko
+// itself writes there. Consumed by `keiko uninstall` (to reverse them) and
+// `keiko repair` (to detect and clean stale ones). Resolution mirrors `lifecycle.ts`
+// (`--state-dir` > KEIKO_STATE_DIR > <cwd>/.keiko) so `start`, `uninstall`, and
+// `repair` all operate on the same directory.
+//
+// DELETION SAFETY CONTRACT: callers remove ONLY the explicitly enumerated state
+// artifacts below (the fixed `KEIKO_STATE_FILES` plus the launcher's
+// `.launcher-state-*` mkdtemp dirs) and then rmdir the state directory when it is
+// empty. Nothing here recursively deletes an arbitrary directory, so a mis-pointed
+// `--state-dir`/KEIKO_STATE_DIR can never escalate into data loss outside Keiko's
+// own files.
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+import { assertValidRunId } from "@oscharko-dev/keiko-security";
+export const DEFAULT_STATE_DIR_NAME = ".keiko";
+// Runtime files Keiko writes under the state dir. `ui.pid`/`ui.log` come from
+// `lifecycle.ts`; `launcher-state.json` from `launcher-state.ts`.
+export const KEIKO_STATE_FILES = ["ui.pid", "ui.log", "launcher-state.json"];
+// `launcher-state.ts` writes ephemeral mkdtemp dirs with this prefix during atomic
+// state saves; a crash can leave one behind, so uninstall/repair sweep them by prefix.
+export const LAUNCHER_STATE_TMP_PREFIX = ".launcher-state-";
+// Resolves the state directory the same way `keiko start` does. An explicit
+// `--state-dir` argument wins, then `KEIKO_STATE_DIR`, then `<cwd>/.keiko`. Relative
+// values resolve against `cwd`.
+export function resolveStateDir(cwd, env, stateDirArg) {
+    const value = stateDirArg !== undefined && stateDirArg.length > 0
+        ? stateDirArg
+        : (env.KEIKO_STATE_DIR ?? DEFAULT_STATE_DIR_NAME);
+    return isAbsolute(value) ? value : resolve(cwd, value);
+}
+// Reads a pid file written by `lifecycle.ts`. Returns the integer pid, or undefined
+// when the file is absent or does not contain a positive integer.
+export function readPidFile(path) {
+    if (!existsSync(path))
+        return undefined;
+    const raw = readFileSync(path, "utf8").trim();
+    if (!/^[1-9]\d*$/.test(raw))
+        return undefined;
+    return Number(raw);
+}
+// Liveness probe identical in semantics to the lifecycle handler: a successful
+// signal-0 means alive; an EPERM error means the process exists but is owned by
+// another user (still alive); any other error means it is gone. Kept local to this
+// leaf module so uninstall/repair do not pull in lifecycle's heavy spawn/net imports.
+export function defaultIsProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return typeof error === "object" && error !== null && "code" in error && error.code === "EPERM";
+    }
+}
+// Classifies the UI pid file: `absent` (missing or malformed), `stale` (a pid is
+// recorded but the process is gone), or `running` (recorded and alive).
+export function classifyPid(pidFilePath, isAlive) {
+    const pid = readPidFile(pidFilePath);
+    if (pid === undefined)
+        return { state: "absent", pid: undefined };
+    return isAlive(pid) ? { state: "running", pid } : { state: "stale", pid };
+}
+// ── Runtime-state confidentiality manifest (Issue #1321) ──────────────────────
+//
+// `keiko repair` and `keiko uninstall --state` must reason about EVERY Keiko-owned
+// sensitive artifact under the state directory, not only the three lifecycle/launcher
+// files above. Rather than a blanket recursive chmod/delete of arbitrary content under
+// `.keiko` (which could touch a customer file that merely happens to live there), this
+// manifest is an explicit allowlist describing the on-disk layout each Keiko store
+// writes:
+//
+//   <stateDir>/
+//     ui.pid, ui.log                        lifecycle.ts
+//     launcher-state.json                   launcher-state.ts
+//     .launcher-state-*/                    launcher-state.ts atomic-save temp dirs
+//     keiko-ui.db[-wal|-shm|.corrupt.*]     keiko-server  store/paths.ts (UI_DB_FILENAME)
+//     keiko.config.json                     keiko-server  deps.ts (model-gateway config)
+//     credentials/*.vault, *.key            keiko-server  credentialVault.ts (sealed apiKeys + keyfile)
+//     memory/keiko-memory.db[-wal|-shm|.*]  keiko-memory-vault paths.ts (MEMORY_DB_FILENAME)
+//     local-knowledge/<ns>/capsules.db[…]   keiko-local-knowledge store-paths.ts
+//     evidence/<runId>.json|.lock|…         keiko-evidence store.ts
+//     evidence/figma/*.vault, *.key         keiko-server  figmaTokenStore.ts (sealed Figma PAT + keyfile)
+//     evidence/qi/<runId>.qi.json|…         keiko-evidence qualityIntelligence/*
+//     evidence/qi/figma-snapshots/<runId>/… keiko-evidence figmaSnapshot side files
+//
+// The sealed `*.vault` ciphertext and its `*.key` keyfile (the env/keychain-tier fallback,
+// ADR-0046) are the most confidentiality-critical artifacts here, so they are first-class
+// manifest entries rather than incidental files.
+//
+// The filenames are duplicated here ON PURPOSE: keiko-cli is a leaf consumer and must
+// not take a package-graph edge onto keiko-local-knowledge / keiko-evidence internals
+// just to learn a constant. Each descriptor cites its source of truth so drift stays
+// auditable. The walker classifies entries WITHOUT mutating anything — `repair` chmods
+// and `uninstall` unlinks, but only entries this allowlist recognizes as Keiko-owned;
+// every unrecognized entry is reported as `retained` and left in place.
+// POSIX modes Keiko enforces on its own runtime state: private directories and private
+// files. NTFS has no equivalent; callers no-op on win32 and emit a diagnostic instead.
+export const RUNTIME_STATE_DIR_MODE = 0o700;
+export const RUNTIME_STATE_FILE_MODE = 0o600;
+const UI_DB_FILENAME = "keiko-ui.db"; // keiko-server/src/store/paths.ts
+const MEMORY_DB_FILENAME = "keiko-memory.db"; // keiko-memory-vault/src/paths.ts
+const CAPSULES_DB_FILENAME = "capsules.db"; // keiko-local-knowledge/src/store-paths.ts
+const GATEWAY_CONFIG_FILENAME = "keiko.config.json"; // keiko-server/src/deps.ts
+const CREDENTIALS_SUBDIR = "credentials"; // keiko-server/src/credentialVault.ts (CREDENTIALS_SUBDIR)
+const MEMORY_SUBDIR = "memory"; // keiko-memory-vault/src/paths.ts (MEMORY_DIR_NAME)
+const LOCAL_KNOWLEDGE_SUBDIR = "local-knowledge"; // keiko-local-knowledge store-paths.ts (SUBSYSTEM_DIR)
+const EVIDENCE_SUBDIR = "evidence"; // keiko-evidence/src/store.ts (DEFAULT_EVIDENCE_DIR)
+const FIGMA_VAULT_SUBDIR = "figma"; // keiko-server figmaTokenStore.ts (Figma PAT vault dir, under evidence)
+const QI_SUBDIR = "qi"; // keiko-evidence/src/qualityIntelligence/store.ts (QI_SUBDIR)
+const FIGMA_SNAPSHOTS_SUBDIR = "figma-snapshots"; // keiko-evidence figmaSnapshot/store.ts (SIDE_FILE_SUBDIR)
+const PROVIDER_CREDENTIALS_VAULT = "provider-credentials.vault"; // keiko-server/src/credentialVault.ts
+const PROVIDER_CREDENTIALS_KEYFILE = "provider-credentials-vault.key"; // keiko-server/src/credentialVault.ts
+const FIGMA_TOKEN_VAULT = "figma-token.vault"; // keiko-server figmaTokenStore.ts
+const FIGMA_TOKEN_KEYFILE = "figma-vault.key"; // keiko-server figmaTokenStore.ts
+const EVIDENCE_MANIFEST_SUFFIX = ".json"; // keiko-evidence/src/store.ts
+const EVIDENCE_LOCK_SUFFIX = ".lock"; // keiko-evidence/src/store.ts
+const PRODUCER_TEMP_SUFFIX = ".tmp"; // atomic-save temp files (`<target>.<random>.tmp`)
+const PRODUCER_TEMP_TOKEN = /^[A-Za-z0-9._-]{8,}$/u;
+const SECRET_VAULT_TEMP_FILE = /^\.secret-vault\.[1-9][0-9]*\.[0-9a-f]{16}\.tmp$/u;
+const QI_OWNED_SUFFIXES = [
+    ".qi.json", // keiko-evidence/src/qualityIntelligence/store.ts
+    ".candidates.json", // keiko-evidence/src/qualityIntelligence/candidatesArtifact.ts
+    ".review.json", // keiko-server/src/qualityIntelligence/reviewStore.ts
+    ".figma-codegen.json", // keiko-server/src/qualityIntelligence/retentionRoutes.ts
+    ".figma-audit.json", // keiko-server/src/qualityIntelligence/retentionRoutes.ts
+    ".figma-consent.json", // keiko-server/src/qualityIntelligence/retentionRoutes.ts
+    ".figma-snapshot.json", // keiko-evidence/src/qualityIntelligence/figmaSnapshot/store.ts
+    ".figma-snapshot.management.json", // keiko-evidence/src/qualityIntelligence/figmaSnapshot/store.ts
+];
+// A SQLite store file plus its exact WAL/SHM sidecars and `.corrupt.<ts>` quarantine copies
+// — and ONLY those. Matching is exact-name or a known dotted suffix, never a bare `${base}-`
+// or `${base}.` prefix, so a customer file such as `keiko-ui.db.backup` or `keiko-ui.db-old`
+// is left as an unrecognized entry and is never chmod-ed or deleted.
+//   `<base>`                                   the live database
+//   `<base>-wal`, `<base>-shm`                 WAL/SHM sidecars
+//   `<base>-wal.corrupt.<ts>`, `-shm.corrupt`  quarantined sidecars (keiko-memory-vault db.ts)
+//   `<base>.corrupt.<ts>`                      quarantined database (keiko-server store/db.ts)
+function isSqliteFamily(base, name) {
+    return (name === base ||
+        name === `${base}-wal` ||
+        name === `${base}-shm` ||
+        name.startsWith(`${base}-wal.corrupt.`) ||
+        name.startsWith(`${base}-shm.corrupt.`) ||
+        name.startsWith(`${base}.corrupt.`));
+}
+// Evidence and Quality-Intelligence records are run-id-derived artifacts, never arbitrary
+// suffix matches. Matching by the producer suffix vocabulary prevents a customer lookalike
+// such as `manual export.json` or `backup.key` from being chmod-ed or deleted.
+function isValidRunId(value) {
+    if (value.length === 0)
+        return false;
+    try {
+        assertValidRunId(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasRunIdSuffix(name, suffix) {
+    if (!name.endsWith(suffix))
+        return false;
+    return isValidRunId(name.slice(0, -suffix.length));
+}
+function hasRunIdProducerTempSuffix(name, suffix) {
+    if (!name.endsWith(PRODUCER_TEMP_SUFFIX))
+        return false;
+    const withoutTmp = name.slice(0, -PRODUCER_TEMP_SUFFIX.length);
+    const marker = `${suffix}.`;
+    const markerIndex = withoutTmp.lastIndexOf(marker);
+    if (markerIndex < 0)
+        return false;
+    const runId = withoutTmp.slice(0, markerIndex);
+    const token = withoutTmp.slice(runId.length + marker.length);
+    return PRODUCER_TEMP_TOKEN.test(token) && isValidRunId(runId);
+}
+function hasRunIdArtifactSuffix(name, suffix) {
+    return hasRunIdSuffix(name, suffix) || hasRunIdProducerTempSuffix(name, suffix);
+}
+function isEvidenceRecord(name) {
+    return (hasRunIdArtifactSuffix(name, EVIDENCE_MANIFEST_SUFFIX) ||
+        hasRunIdArtifactSuffix(name, EVIDENCE_LOCK_SUFFIX));
+}
+function isQiRecord(name) {
+    return QI_OWNED_SUFFIXES.some((suffix) => hasRunIdArtifactSuffix(name, suffix));
+}
+// Sealed credential material: the AES-256-GCM `*.vault` ciphertext and the `*.key` keyfile
+// (the env/keychain-tier fallback). Both must stay owner-only (ADR-0046).
+function isProviderCredentialVaultFile(name) {
+    return (name === PROVIDER_CREDENTIALS_VAULT ||
+        name === PROVIDER_CREDENTIALS_KEYFILE ||
+        SECRET_VAULT_TEMP_FILE.test(name));
+}
+function isFigmaVaultFile(name) {
+    return name === FIGMA_TOKEN_VAULT || name === FIGMA_TOKEN_KEYFILE;
+}
+function dirHasSqliteFamilyArtifact(absDir, base) {
+    try {
+        return readdirSync(absDir).some((name) => isSqliteFamily(base, name));
+    }
+    catch {
+        return false;
+    }
+}
+const NO_CHILD = () => undefined;
+const OWNS_NO_FILE = () => false;
+const figmaSnapshotRunSubtree = {
+    category: "quality-intelligence",
+    whole: true,
+    ownsFile: OWNS_NO_FILE,
+    childSubtree: NO_CHILD,
+};
+const figmaSnapshotsSubtree = {
+    category: "quality-intelligence",
+    whole: false,
+    ownsFile: OWNS_NO_FILE,
+    childSubtree: (name) => (isValidRunId(name) ? figmaSnapshotRunSubtree : undefined),
+};
+const qiSubtree = {
+    category: "quality-intelligence",
+    whole: false,
+    ownsFile: isQiRecord,
+    childSubtree: (name) => (name === FIGMA_SNAPSHOTS_SUBDIR ? figmaSnapshotsSubtree : undefined),
+};
+// `evidence/figma/` holds the sealed Figma PAT vault + keyfile (figmaTokenStore.ts).
+const figmaVaultSubtree = {
+    category: "credential-vault",
+    whole: false,
+    ownsFile: isFigmaVaultFile,
+    childSubtree: NO_CHILD,
+};
+function evidenceChildSubtree(name) {
+    if (name === QI_SUBDIR)
+        return qiSubtree;
+    if (name === FIGMA_VAULT_SUBDIR)
+        return figmaVaultSubtree;
+    return undefined;
+}
+const evidenceSubtree = {
+    category: "evidence",
+    whole: false,
+    ownsFile: isEvidenceRecord,
+    childSubtree: evidenceChildSubtree,
+};
+// `credentials/` holds the sealed provider-credential vault + keyfile (credentialVault.ts).
+const credentialsSubtree = {
+    category: "credential-vault",
+    whole: false,
+    ownsFile: isProviderCredentialVaultFile,
+    childSubtree: NO_CHILD,
+};
+const memorySubtree = {
+    category: "memory-vault",
+    whole: false,
+    ownsFile: (name) => isSqliteFamily(MEMORY_DB_FILENAME, name),
+    childSubtree: NO_CHILD,
+};
+const knowledgeNamespaceSubtree = {
+    category: "local-knowledge",
+    whole: false,
+    ownsFile: (name) => isSqliteFamily(CAPSULES_DB_FILENAME, name),
+    childSubtree: NO_CHILD,
+};
+// `local-knowledge/` holds one directory per namespace; each namespace directory is a
+// Keiko-owned store root (`local-knowledge/<ns>/capsules.db`).
+const localKnowledgeSubtree = {
+    category: "local-knowledge",
+    whole: false,
+    ownsFile: OWNS_NO_FILE,
+    childSubtree: (_name, absPath) => dirHasSqliteFamilyArtifact(absPath, CAPSULES_DB_FILENAME) ? knowledgeNamespaceSubtree : undefined,
+};
+const launcherTmpSubtree = {
+    category: "launcher",
+    whole: true,
+    ownsFile: OWNS_NO_FILE,
+    childSubtree: NO_CHILD,
+};
+function topLevelFileCategory(name) {
+    if (name === "ui.pid" || name === "ui.log")
+        return "lifecycle";
+    if (name === "launcher-state.json")
+        return "launcher";
+    if (name === GATEWAY_CONFIG_FILENAME)
+        return "gateway-config";
+    if (isSqliteFamily(UI_DB_FILENAME, name))
+        return "ui-database";
+    return undefined;
+}
+function topLevelChildSubtree(name) {
+    if (name === CREDENTIALS_SUBDIR)
+        return credentialsSubtree;
+    if (name === MEMORY_SUBDIR)
+        return memorySubtree;
+    if (name === LOCAL_KNOWLEDGE_SUBDIR)
+        return localKnowledgeSubtree;
+    if (name === EVIDENCE_SUBDIR)
+        return evidenceSubtree;
+    if (name.startsWith(LAUNCHER_STATE_TMP_PREFIX))
+        return launcherTmpSubtree;
+    return undefined;
+}
+export function inspectStateRoot(stateDir) {
+    try {
+        const stat = lstatSync(stateDir);
+        if (stat.isSymbolicLink())
+            return { status: "symlink", absPath: stateDir };
+        if (stat.isDirectory())
+            return { status: "directory", absPath: stateDir };
+        return { status: "not-directory", absPath: stateDir };
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")
+            return { status: "absent", absPath: stateDir };
+        throw error;
+    }
+}
+function childRelPath(relDir, name) {
+    return relDir === "" ? name : `${relDir}/${name}`;
+}
+function ownedFileCategory(scope, name) {
+    if (scope === "root")
+        return topLevelFileCategory(name);
+    if (scope.whole)
+        return scope.category;
+    return scope.ownsFile(name) ? scope.category : undefined;
+}
+function ownedChildSubtree(scope, name, absPath) {
+    if (scope === "root")
+        return topLevelChildSubtree(name);
+    if (scope.whole)
+        return scope; // a whole subtree owns all of its descendant directories
+    return scope.childSubtree(name, absPath);
+}
+function classifyEntry(absDir, relDir, name, scope, acc) {
+    const absPath = join(absDir, name);
+    const relPath = childRelPath(relDir, name);
+    const stat = lstatSync(absPath);
+    if (stat.isSymbolicLink()) {
+        // Never follow a symlink in any position: chmod-through and delete-through a symlink can
+        // escape `.keiko`. Flag it when it occupies a slot the manifest would otherwise own.
+        const owned = ownedFileCategory(scope, name) !== undefined ||
+            ownedChildSubtree(scope, name, absPath) !== undefined;
+        acc.retained.push({ relPath, absPath, reason: "symlink", owned });
+        return;
+    }
+    if (stat.isDirectory()) {
+        const child = ownedChildSubtree(scope, name, absPath);
+        if (child === undefined) {
+            acc.retained.push({ relPath, absPath, reason: "unknown", owned: false });
+            return;
+        }
+        acc.directories.push({ relPath, absPath, category: child.category });
+        walkOwnedDir(absPath, relPath, child, acc);
+        return;
+    }
+    if (stat.isFile()) {
+        const category = ownedFileCategory(scope, name);
+        if (category === undefined) {
+            acc.retained.push({ relPath, absPath, reason: "unknown", owned: false });
+        }
+        else if (stat.nlink > 1) {
+            acc.retained.push({ relPath, absPath, reason: "hardlink", owned: true });
+        }
+        else {
+            acc.files.push({ relPath, absPath, category });
+        }
+        return;
+    }
+    // Sockets, FIFOs, devices: not a Keiko artifact — retain untouched.
+    acc.retained.push({ relPath, absPath, reason: "unknown", owned: false });
+}
+function walkOwnedDir(absDir, relDir, scope, acc) {
+    for (const name of readdirSync(absDir)) {
+        classifyEntry(absDir, relDir, name, scope, acc);
+    }
+}
+// Classifies every entry under `stateDir` against the runtime-state manifest. Pure
+// read-only traversal (lstat-based, never follows symlinks); the directories list is
+// ordered shallowest-first so callers can reverse it to remove leaves before parents.
+export function scanRuntimeState(stateDir) {
+    const root = inspectStateRoot(stateDir);
+    if (root.status === "absent") {
+        return { root, present: false, files: [], directories: [], retained: [] };
+    }
+    if (root.status !== "directory") {
+        return { root, present: true, files: [], directories: [], retained: [] };
+    }
+    const acc = { files: [], directories: [], retained: [] };
+    walkOwnedDir(stateDir, "", "root", acc);
+    return { root, present: true, files: acc.files, directories: acc.directories, retained: acc.retained };
+}
+// True when `descendant` lies inside `ancestor` (used to decide whether an owned directory
+// can be removed: it can only be removed when no retained entry survives beneath it).
+export function isInsidePath(ancestor, descendant) {
+    return descendant === ancestor || descendant.startsWith(`${ancestor}${sep}`);
+}

package/dist/ui.d.ts

@@ -0,0 +1,39 @@
+import type { Server } from "node:http";
+import { type SpawnOptions, type ChildProcess } from "node:child_process";
+import { type UiHandlerDeps } from "@oscharko-dev/keiko-server";
+import type { EnvSource } from "@oscharko-dev/keiko-model-gateway";
+import type { CliIo } from "./runner.js";
+export interface UiCliArgs {
+    readonly port: number;
+    readonly evidenceDir: string | undefined;
+    readonly config: string | undefined;
+    readonly uiDbPath: string | undefined;
+}
+type UiParseResult = UiCliArgs | "help" | null;
+export interface UiCliDeps {
+    readonly createServer?: (deps: {
+        staticRoot: string;
+        csp: string;
+        port: number;
+        handlerDeps: UiHandlerDeps;
+    }) => Server | Promise<Server>;
+    readonly staticRoot?: string;
+    readonly hashesFile?: string;
+    readonly sqliteProbe?: () => boolean;
+    readonly spawnFn?: SpawnFn;
+    readonly currentExecArgv?: () => readonly string[];
+    readonly cwd?: string | undefined;
+}
+interface LiveCspSource {
+    readonly csp: () => string;
+    readonly dispose: () => void;
+}
+export type SpawnFn = (command: string, args: readonly string[], opts: SpawnOptions) => ChildProcess;
+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, cwd: string): Promise<number>;
+export declare function createLiveCspSource(staticRoot: string, hashesFile: string, io: CliIo): Promise<LiveCspSource>;
+export declare function runUiCli(args: readonly string[], io: CliIo, env: EnvSource, deps?: UiCliDeps): Promise<number>;
+export {};
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAMxC,OAAO,EAAS,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAQL,KAAK,aAAa,EACnB,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,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,UAAU,aAAa;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAOD,MAAM,MAAM,OAAO,GAAG,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,YAAY,KACf,YAAY,CAAC;AAuGlB,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,CA2BjB;AAyGD,wBAAsB,mBAAmB,CACvC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,KAAK,GACR,OAAO,CAAC,aAAa,CAAC,CAqCxB;AAED,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,CA+BjB"}