@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/runtime/containerRunner.js

@@ -0,0 +1,443 @@
+// Issue #1388 (Epic #1491, ADR-0070, D2/D3) — the governed container-run pilot manager. A request
+// names a `taskId` from a server-frozen CLOSED catalog; the server resolves it to a vetted
+// ContainerTask whose image is in a closed allowlist and constructs the EXACT, server-frozen
+// `docker run` argv (no client-supplied image/argv/mount/flag). Execution reuses the single governed
+// runCommand spawn boundary (ADR-0043 D2) exactly as the #1387 command runner does — no Docker SDK,
+// no daemon-socket client, no second spawn path.
+//
+// Engine-unavailable is a GOVERNANCE failure, not an execution outcome: `execute` THROWS
+// ContainerRunnerError("CONTAINER_ENGINE_UNAVAILABLE") BEFORE any run id is minted, so there is no
+// run/event/evidence for a run that never started. Only real execution outcomes become a
+// ContainerRunResult.
+import { randomUUID } from "node:crypto";
+import { CommandCancelledError, CommandDeniedError, CommandTimeoutError, DEFAULT_SANDBOX_POLICY, runCommand, } from "@oscharko-dev/keiko-tools";
+import { nodeSpawnFn } from "@oscharko-dev/keiko-tools/internal/exec";
+import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
+import { CONTAINER_RUNTIME_SCHEMA_VERSION, CONTAINER_TASK_RULES, } from "@oscharko-dev/keiko-contracts";
+import { ContainerRunnerError } from "./containerRunner-errors.js";
+import { appendContainerRunEvidence, buildContainerRunEvidenceEntry, } from "./containerRunner-evidence.js";
+import { detectContainerEngines } from "./containerEngineDetector.js";
+// Tight cap — a container run is a high-trust surface, so a small number of concurrent runs.
+const MAX_CONCURRENT_CONTAINER_RUNS = 2;
+const MIN_TIMEOUT_MS = 1_000;
+// ─── Defaults (conservative; justified inline) ─────────────────────────────────────
+export const DEFAULT_CONTAINER_RESOURCE_LIMITS = {
+    pidsLimit: 256, // enough for a small toolchain; blocks fork-bombs
+    memoryBytes: 536_870_912, // 512 MiB — bounded, fits a diagnostic image
+    cpus: 1, // single core; deterministic, no host saturation
+};
+// The pilot image is pinned by TAG (not digest) because no published Keiko-vetted digest exists yet;
+// the digest-pin path is documented in docs/container-runtime/security-notes.md and is a one-line
+// change here once a digest is vetted. `--pull never` means the image MUST already be present
+// locally — a missing image is a structured image-missing failure, never a silent network fetch.
+const PILOT_IMAGE = "docker.io/library/alpine:3.20";
+export const DEFAULT_CONTAINER_EXECUTION_POLICY = {
+    // Closed set: exactly the one pinned pilot image. An image ∉ this list → IMAGE_NOT_ALLOWED.
+    imageAllowlist: Object.freeze([PILOT_IMAGE]),
+    limits: DEFAULT_CONTAINER_RESOURCE_LIMITS,
+    mountMode: "read-only",
+    networkMode: "none",
+    workspaceMountPath: "/workspace",
+    pull: "never",
+};
+export const DEFAULT_CONTAINER_TASKS = Object.freeze([
+    {
+        id: "container-pilot:diagnostic",
+        kind: "diagnostic",
+        label: "Container engine pilot diagnostic",
+        image: PILOT_IMAGE,
+        // Trivial in-container command (NOT docker flags). Proves the detection+policy+spawn composition.
+        // Deliberately NOT `sh -c …`: `-c` is a CONTAINER_DENY_FLAGS member (a transitive-shell escalation
+        // flag), so a `-c` anywhere in the argv would self-deny at the runCommand boundary. A bare
+        // `echo …` argv keeps the frozen hardened argv passing isCommandAllowed (the §1.8 LOAD-BEARING
+        // no-self-deny invariant).
+        args: Object.freeze(["echo", "keiko-container-pilot ok"]),
+        engine: "docker",
+    },
+]);
+// ─── Server-frozen argv (D3) — PURE, unit-tested in isolation ──────────────────────
+// Returns the EXACT docker/podman argv. The image MUST already be asserted ∈ policy.imageAllowlist
+// by the caller (execute does this and throws IMAGE_NOT_ALLOWED otherwise); this builder additionally
+// re-asserts so a misuse can never emit a non-allowlisted image. No client input reaches this argv.
+export function buildContainerRunArgv(task, policy, workspaceRoot) {
+    if (!policy.imageAllowlist.includes(task.image)) {
+        throw new ContainerRunnerError("IMAGE_NOT_ALLOWED", "Task image is not allowlisted.");
+    }
+    return [
+        "run",
+        "--rm", // no container persistence (NIST 800-190 4.4)
+        "--network",
+        policy.networkMode, // "none" — the container has no network (4.1.3)
+        "--read-only", // read-only root filesystem (3.1.2 / 4.5.2)
+        "--cap-drop",
+        "ALL", // drop all Linux capabilities (4.5.3)
+        "--security-opt",
+        "no-new-privileges", // forbid privilege escalation (4.5.3)
+        "--pids-limit",
+        String(policy.limits.pidsLimit),
+        "--memory",
+        String(policy.limits.memoryBytes),
+        "--cpus",
+        String(policy.limits.cpus),
+        "--pull",
+        policy.pull, // "never" — the image must already be present locally (3.1.1 / 4.2)
+        "-v",
+        // read-only workspace bind mount at a fixed in-container path; NO read-write/broad host mount,
+        // and NEVER the Docker socket.
+        `${workspaceRoot}:${policy.workspaceMountPath}:ro`,
+        task.image,
+        ...task.args,
+    ];
+}
+const IMAGE_MISSING_SIGNATURES = [
+    "no such image",
+    "unable to find image",
+    "image not known",
+    "manifest unknown",
+];
+const PULL_DENIED_SIGNATURES = [
+    "pull policy",
+    "pull never",
+    "--pull=never",
+    "image must be present",
+];
+const MOUNT_FAILURE_SIGNATURES = [
+    "error mounting",
+    "invalid mount",
+    "bind mount",
+    "no such file or directory", // bind source absent
+    "are you trying to mount",
+];
+function matchesSignature(haystack, signatures) {
+    const lower = haystack.toLowerCase();
+    return signatures.some((needle) => lower.includes(needle));
+}
+// Classifies a NON-ZERO exit into a container-specific failure reason by stderr signature, so the
+// audit distinguishes a missing image / denied pull / mount failure from a plain non-zero exit.
+function classifyNonZeroFailure(stderr) {
+    if (matchesSignature(stderr, IMAGE_MISSING_SIGNATURES))
+        return "image-missing";
+    if (matchesSignature(stderr, PULL_DENIED_SIGNATURES))
+        return "pull-denied";
+    if (matchesSignature(stderr, MOUNT_FAILURE_SIGNATURES))
+        return "mount-failure";
+    return "non-zero-exit";
+}
+function outcomeFromResult(result) {
+    // runCommand resolves only on a real process exit (timeout/cancel reject). A truncation that
+    // killed the child is terminal → output-capped; otherwise classify by exit code + stderr.
+    const failureReason = result.truncated
+        ? "output-capped"
+        : result.exitCode === 0
+            ? "none"
+            : classifyNonZeroFailure(result.stderr);
+    return {
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+        truncated: result.truncated,
+        timedOut: false,
+        failureReason,
+        eventKind: failureReason === "none" ? "run-completed" : "run-failed",
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+function deniedFailureReason(error) {
+    if (error instanceof CommandDeniedError && !error.message.includes("not found on PATH")) {
+        return "denied";
+    }
+    return "spawn-error";
+}
+function outcomeFromError(error, cancelledByUser, durationMs) {
+    const base = { exitCode: null, durationMs, truncated: false, stdout: "", stderr: "" };
+    if (error instanceof CommandCancelledError || cancelledByUser) {
+        return { ...base, timedOut: false, failureReason: "cancelled", eventKind: "run-cancelled" };
+    }
+    if (error instanceof CommandTimeoutError) {
+        return { ...base, timedOut: true, failureReason: "timed-out", eventKind: "run-failed" };
+    }
+    return {
+        ...base,
+        timedOut: false,
+        failureReason: deniedFailureReason(error),
+        eventKind: "run-failed",
+    };
+}
+function clampTimeout(requested, ceiling) {
+    if (requested === undefined || !Number.isFinite(requested)) {
+        return ceiling;
+    }
+    const rounded = Math.round(requested);
+    if (rounded <= MIN_TIMEOUT_MS)
+        return MIN_TIMEOUT_MS;
+    if (rounded >= ceiling)
+        return ceiling;
+    return rounded;
+}
+function requestIdPayload(input) {
+    return input.requestId === undefined ? {} : { requestId: input.requestId };
+}
+function projectFor(store, projectId) {
+    for (const project of store.listProjects()) {
+        if (project.path === projectId) {
+            return project;
+        }
+    }
+    return undefined;
+}
+function projectRootOrThrow(project) {
+    try {
+        return nodeWorkspaceFs.realPath(project.path);
+    }
+    catch {
+        throw new ContainerRunnerError("PROJECT_NOT_FOUND", "Project root path could not be resolved.");
+    }
+}
+function buildWorkspaceInfo(projectRoot) {
+    return {
+        root: projectRoot,
+        name: undefined,
+        version: undefined,
+        testFramework: "unknown",
+        sourceDirs: [],
+        testDirs: [],
+        languages: [],
+        ignoreLines: [],
+    };
+}
+class ContainerRunnerManagerImpl {
+    store;
+    evidenceStore;
+    policy;
+    executionPolicy;
+    catalog;
+    processEnv;
+    redactor;
+    runDeps;
+    detect;
+    now;
+    runs = new Map();
+    subscribers = new Set();
+    constructor(opts) {
+        this.store = opts.store;
+        this.evidenceStore = opts.evidenceStore;
+        this.policy = opts.policy ?? DEFAULT_SANDBOX_POLICY;
+        this.executionPolicy = opts.executionPolicy ?? DEFAULT_CONTAINER_EXECUTION_POLICY;
+        this.catalog = opts.catalog ?? DEFAULT_CONTAINER_TASKS;
+        this.processEnv = opts.processEnv ?? process.env;
+        this.redactor = opts.redactor ?? ((input) => input);
+        this.runDeps = opts.runDeps ?? {};
+        this.detect = opts.detect;
+        this.now = opts.now ?? Date.now;
+    }
+    inFlightCount = () => this.runs.size;
+    subscribe = (listener) => {
+        this.subscribers.add(listener);
+        return () => {
+            this.subscribers.delete(listener);
+        };
+    };
+    abort = (runId) => {
+        const entry = this.runs.get(runId);
+        if (entry === undefined)
+            return false;
+        entry.cancelledByUser = true;
+        entry.controller.abort();
+        return true;
+    };
+    capability = (projectId) => {
+        return this.resolveCapability(projectId);
+    };
+    listCatalog = async (projectId) => {
+        const capability = await this.resolveCapability(projectId);
+        // Graceful degradation: no engine → engineAvailable:false + tasks:[] (never an error).
+        const engineAvailable = capability.anyAvailable;
+        return {
+            schemaVersion: CONTAINER_RUNTIME_SCHEMA_VERSION,
+            projectId,
+            engineAvailable,
+            tasks: engineAvailable ? this.catalog : [],
+        };
+    };
+    execute = async (input) => {
+        const workspace = this.resolveWorkspace(input.projectId);
+        // Engine-unavailable is a GOVERNANCE failure: throw BEFORE minting a run id (route → 503).
+        const capability = await this.resolveCapability(input.projectId);
+        if (!capability.anyAvailable) {
+            throw new ContainerRunnerError("CONTAINER_ENGINE_UNAVAILABLE", "No container engine is available.");
+        }
+        const task = this.catalog.find((entry) => entry.id === input.taskId);
+        if (task === undefined) {
+            throw new ContainerRunnerError("TASK_NOT_FOUND", "Task is not in the container catalog.");
+        }
+        if (!this.executionPolicy.imageAllowlist.includes(task.image)) {
+            throw new ContainerRunnerError("IMAGE_NOT_ALLOWED", "Task image is not allowlisted.");
+        }
+        if (this.runs.size >= MAX_CONCURRENT_CONTAINER_RUNS) {
+            throw new ContainerRunnerError("RUN_LIMIT_EXCEEDED", "Too many in-flight container runs.");
+        }
+        return this.runExecution(task, workspace, input);
+    };
+    resolveCapability(projectId) {
+        if (this.detect !== undefined) {
+            return this.detect(projectId);
+        }
+        const probeDeps = {
+            runCommand,
+            workspace: this.tryWorkspace(projectId),
+            policy: this.policy,
+            processEnv: this.processEnv,
+            now: this.now,
+        };
+        return detectContainerEngines(probeDeps);
+    }
+    tryWorkspace(projectId) {
+        const project = projectFor(this.store, projectId);
+        if (project === undefined) {
+            return undefined;
+        }
+        try {
+            return buildWorkspaceInfo(projectRootOrThrow(project));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    resolveWorkspace(projectId) {
+        const project = projectFor(this.store, projectId);
+        if (project === undefined) {
+            throw new ContainerRunnerError("PROJECT_NOT_FOUND", "Project not found.");
+        }
+        return buildWorkspaceInfo(projectRootOrThrow(project));
+    }
+    buildRunDeps(workspace) {
+        return {
+            workspace,
+            // Host CLI policy: network:"inherit" so the docker/podman CLI reaches the daemon socket. The
+            // CONTAINER is isolated by --network none in the frozen argv (D4).
+            policy: { ...this.policy, network: "inherit" },
+            commandRules: CONTAINER_TASK_RULES,
+            spawn: this.runDeps.spawn ?? nodeSpawnFn,
+            processEnv: this.processEnv,
+            now: this.runDeps.now ?? this.now,
+            ...(this.runDeps.resolveExecutable === undefined
+                ? {}
+                : { resolveExecutable: this.runDeps.resolveExecutable }),
+            ...(this.runDeps.fs === undefined ? {} : { fs: this.runDeps.fs }),
+            ...(this.runDeps.home === undefined ? {} : { home: this.runDeps.home }),
+        };
+    }
+    async runExecution(task, workspace, input) {
+        const runId = randomUUID();
+        const controller = new AbortController();
+        const entry = { controller, cancelledByUser: false };
+        this.runs.set(runId, entry);
+        const startedAt = this.now();
+        this.emit({
+            kind: "run-started",
+            runId,
+            payload: {
+                taskId: task.id,
+                kind: task.kind,
+                engine: task.engine,
+                startedAt,
+                ...requestIdPayload(input),
+            },
+        });
+        try {
+            return await this.invoke(runId, task, workspace, input, entry, startedAt);
+        }
+        finally {
+            this.runs.delete(runId);
+        }
+    }
+    async invoke(runId, task, workspace, input, entry, startedAt) {
+        const deps = this.buildRunDeps(workspace);
+        const argv = buildContainerRunArgv(task, this.executionPolicy, workspace.root);
+        const timeoutMs = clampTimeout(input.timeoutMs, this.policy.defaultTimeoutMs);
+        try {
+            // Single governed spawn boundary; the injected fake spawn (if any) rides in `deps.spawn`.
+            const result = await runCommand({
+                command: task.engine,
+                args: argv,
+                cwd: undefined,
+                timeoutMs,
+                signal: entry.controller.signal,
+            }, deps);
+            return this.finalize(runId, task, argv.length, input, outcomeFromResult(result), startedAt);
+        }
+        catch (error) {
+            const outcome = outcomeFromError(error, entry.cancelledByUser, this.now() - startedAt);
+            return this.finalize(runId, task, argv.length, input, outcome, startedAt);
+        }
+    }
+    finalize(runId, task, argCount, input, outcome, startedAt) {
+        this.persist(runId, task, argCount, input, outcome, startedAt);
+        this.emit({
+            kind: outcome.eventKind,
+            runId,
+            payload: {
+                exitCode: outcome.exitCode,
+                durationMs: outcome.durationMs,
+                truncated: outcome.truncated,
+                timedOut: outcome.timedOut,
+                failureReason: outcome.failureReason,
+                ...requestIdPayload(input),
+            },
+        });
+        return {
+            schemaVersion: CONTAINER_RUNTIME_SCHEMA_VERSION,
+            runId,
+            taskId: task.id,
+            kind: task.kind,
+            engine: task.engine,
+            exitCode: outcome.exitCode,
+            durationMs: outcome.durationMs,
+            truncated: outcome.truncated,
+            timedOut: outcome.timedOut,
+            failureReason: outcome.failureReason,
+            stdout: outcome.stdout,
+            stderr: outcome.stderr,
+        };
+    }
+    persist(runId, task, argCount, input, outcome, startedAt) {
+        if (this.evidenceStore === undefined)
+            return;
+        try {
+            const evidence = buildContainerRunEvidenceEntry({
+                runId,
+                projectId: input.projectId,
+                taskId: task.id,
+                kind: task.kind,
+                engine: task.engine,
+                imageId: task.id, // closed-catalog id, NOT the raw image ref free-text
+                argCount,
+                exitCode: outcome.exitCode,
+                durationMs: outcome.durationMs,
+                timedOut: outcome.timedOut,
+                truncated: outcome.truncated,
+                failureReason: outcome.failureReason,
+                stdoutBytes: Buffer.byteLength(outcome.stdout, "utf8"),
+                stderrBytes: Buffer.byteLength(outcome.stderr, "utf8"),
+                startedAt,
+            });
+            appendContainerRunEvidence(this.evidenceStore, evidence, this.redactor);
+        }
+        catch {
+            // Evidence is best-effort process-evidence; a write hiccup must not corrupt a real run result.
+        }
+    }
+    emit(event) {
+        for (const listener of [...this.subscribers]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A subscriber throwing must not stop fan-out (matches the command-runner pattern).
+            }
+        }
+    }
+}
+export function createContainerRunnerManager(opts) {
+    return new ContainerRunnerManagerImpl(opts);
+}

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAejG,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAI9D,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,OAAO,cAAc,CAAC;AAEnC,MAAM,WAAW,YAAY;IAE3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAGrB,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAEpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAGtB,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAClD;AA0JD,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAgBzD"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAejG,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAM9D,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,OAAO,cAAc,CAAC;AAEnC,MAAM,WAAW,YAAY;IAE3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAGrB,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAEpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAGtB,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAClD;AAiKD,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CA2BzD"}

package/dist/server.js

@@ -8,6 +8,8 @@ import { isAllowedHost } from "./host-check.js";
 import { resolveContainedPath, serveFile } from "./static.js";
 import { errorBody, isApiPath, matchRoute, methodNotAllowedBody, notFoundBody, STREAMING, } from "./routes.js";
 import { buildRedactor } from "./deps.js";
+import { isVoiceDictationCapable, isVoiceRealtimeCapable } from "./read-handlers.js";
+import { createVoiceControlPlane } from "./voice-realtime.js";
 import { createRunRegistry } from "./runs.js";
 import { createInMemoryUiStore } from "./store/index.js";
 export const DEFAULT_UI_PORT = 1983;
@@ -117,7 +119,12 @@ async function resolveCsp(deps) {
 async function handle(deps, handlerDeps, req, res) {
     const url = new URL(req.url ?? "/", `http://${UI_HOST}`);
     const apiPath = isApiPath(url.pathname);
-    applySecurityHeaders(res, await resolveCsp(deps), apiPath);
+    // Issue #495/#497 — scope the Permissions-Policy microphone directive to deployments that advertise
+    // speech-to-text dictation OR full-realtime voice (whose WebRTC capture track also needs the mic);
+    // a no-voice deployment keeps the strict `microphone=()` default, never widened beyond `(self)`.
+    applySecurityHeaders(res, await resolveCsp(deps), apiPath, {
+        allowMicrophone: isVoiceDictationCapable(handlerDeps) || isVoiceRealtimeCapable(handlerDeps),
+    });
     if (!isAllowedHost(req, deps.port)) {
         rejectForbiddenHost(res);
         return;
@@ -130,10 +137,16 @@ async function handle(deps, handlerDeps, req, res) {
     await serveStatic(res, deps.staticRoot, url.pathname);
 }
 // Creates the BFF server. The caller binds it with `server.listen(deps.port, UI_HOST)` so it never
-// listens on a non-loopback interface. The previous PTY WebSocket upgrade handler is removed —
-// the terminal tool is now bounded-exec over plain HTTP (ADR-0018 D1/D8).
+// listens on a non-loopback interface. The previous PTY WebSocket upgrade handler is removed — the
+// terminal tool is now bounded-exec over plain HTTP (ADR-0018 D1/D8). Issue #497 (ADR-0058 D3,
+// ADR-0059) re-opens the upgrade for the single loopback voice control path `/api/voice/control`, and
+// ONLY when the deployment is full-realtime voice capable; every other upgrade keeps the hard reject.
 export function createUiServer(deps) {
     const handlerDeps = deps.handlerDeps ?? fallbackDeps();
+    const voiceControl = createVoiceControlPlane({
+        port: deps.port,
+        handlerDeps: () => handlerDeps,
+    });
     const server = createServer((req, res) => {
         void handle(deps, handlerDeps, req, res).catch(() => {
             if (!res.headersSent) {
@@ -144,9 +157,16 @@ export function createUiServer(deps) {
             }
         });
     });
-    server.on("upgrade", (_req, socket) => {
+    server.on("upgrade", (req, socket, head) => {
+        if (voiceControl.handleUpgrade(req, socket, head)) {
+            return;
+        }
+        // Default: every non-voice-control or ungated upgrade is hard-rejected, as before.
         socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
         socket.destroy();
     });
+    server.on("close", () => {
+        voiceControl.closeAll();
+    });
     return server;
 }

package/dist/store/schema.d.ts

@@ -1,4 +1,4 @@
 import type { DatabaseSync } from "node:sqlite";
-export declare const SCHEMA_VERSION = 6;
+export declare const SCHEMA_VERSION = 8;
 export declare function runMigrations(db: DatabaseSync): void;
 //# sourceMappingURL=schema.d.ts.map

package/dist/store/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/store/schema.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,cAAc,IAAI,CAAC;AA4NhC,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAepD"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/store/schema.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,cAAc,IAAI,CAAC;AA2RhC,wBAAgB,aAAa,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAepD"}

package/dist/store/schema.js

@@ -1,7 +1,7 @@
 // ADR-0013 D5 — Schema v1 + migration runner via PRAGMA user_version. Forward-only, idempotent,
 // transactional. Each migration is a `.sql` string of one or more CREATE/ALTER statements; the
 // runner applies migrations whose 1-based index > current user_version.
-export const SCHEMA_VERSION = 6;
+export const SCHEMA_VERSION = 8;
 const V1_SQL = `
 CREATE TABLE projects (
   path TEXT NOT NULL PRIMARY KEY,
@@ -189,6 +189,65 @@ CREATE INDEX idx_relationship_audit_relationship
 const V6_SQL = `
 ALTER TABLE chat_messages ADD COLUMN grounded_answer_json TEXT;
 `;
+// V7 (issue #445, epic #443) — durable managed task-workspace instances. STRICT mode. One row per
+// provisioned/activated task workspace; the partial unique index on (repository_id, task_id) enforces
+// the idempotency invariant at the DB layer as a second barrier alongside the deterministic id
+// derivation (AC3). All columns are content-free per the #444 contract (ids/hashes, enums, ISO
+// timestamps, branch/path names); `lock_json`, `drift_markers_json`, and `recovery_hints_json` carry
+// the nested WorkspaceLock / drift-marker / recovery-hint shapes the contract validator gates.
+const V7_SQL = `
+CREATE TABLE task_workspace_instances (
+  workspace_id           TEXT NOT NULL PRIMARY KEY,
+  schema_version         TEXT NOT NULL,
+  task_id                TEXT NOT NULL,
+  repository_id          TEXT NOT NULL,
+  repository_root        TEXT NOT NULL,
+  base_branch            TEXT NOT NULL,
+  task_branch            TEXT NOT NULL,
+  managed_worktree_path  TEXT NOT NULL,
+  gitdir_identity        TEXT NOT NULL,
+  lifecycle_state        TEXT NOT NULL,
+  health                 TEXT NOT NULL,
+  lock_json              TEXT,
+  created_at             TEXT NOT NULL,
+  updated_at             TEXT NOT NULL,
+  last_verified_at       TEXT,
+  last_verified_head     TEXT,
+  drift_markers_json     TEXT NOT NULL,
+  recovery_hints_json    TEXT NOT NULL,
+  audit_correlation_id   TEXT NOT NULL,
+  CHECK (
+    schema_version IN ('1')
+    AND lifecycle_state IN (
+      'provisioning','active','paused','handoff-ready','archived','merged',
+      'abandoned','recovery-required','failed','cleanup-pending'
+    )
+    AND health IN ('healthy','degraded','drifted','locked-out','missing','unknown')
+  )
+) STRICT;
+
+CREATE UNIQUE INDEX uniq_task_workspace_repo_task
+  ON task_workspace_instances(repository_id, task_id);
+CREATE INDEX idx_task_workspace_repository
+  ON task_workspace_instances(repository_id, updated_at);
+`;
+// V8 (issue #446, epic #443) — singleton active task-workspace pointer. Studio binds exactly ONE
+// active task workspace at a time; this table holds at most one row (id pinned to the constant
+// 'active', enforced by CHECK). The WorkspaceBinding surfaces consume is DERIVED from the referenced
+// instance (binding.ts), never stored, so the active root has no second copy to drift. Content-free:
+// an opaque workspace id + an opaque actor id + ISO timestamps only. ON DELETE CASCADE clears the
+// pointer when the referenced instance is removed (the lifecycle service also clears it defensively).
+const V8_SQL = `
+CREATE TABLE task_workspace_active_pointer (
+  id            TEXT NOT NULL PRIMARY KEY DEFAULT 'active',
+  workspace_id  TEXT NOT NULL,
+  set_by        TEXT NOT NULL,
+  set_at        TEXT NOT NULL,
+  updated_at    TEXT NOT NULL,
+  CHECK (id = 'active'),
+  FOREIGN KEY (workspace_id) REFERENCES task_workspace_instances(workspace_id) ON DELETE CASCADE
+) STRICT;
+`;
 const MIGRATIONS = [
     { version: 1, sql: V1_SQL },
     { version: 2, sql: V2_SQL },
@@ -196,6 +255,8 @@ const MIGRATIONS = [
     { version: 4, sql: V4_SQL },
     { version: 5, sql: V5_SQL },
     { version: 6, sql: V6_SQL },
+    { version: 7, sql: V7_SQL },
+    { version: 8, sql: V8_SQL },
 ];
 function currentUserVersion(db) {
     const row = db.prepare("PRAGMA user_version").get();

package/dist/task-workspace/active-store.d.ts

@@ -0,0 +1,21 @@
+import type { DatabaseSync } from "node:sqlite";
+export interface ActiveWorkspacePointer {
+    readonly workspaceId: string;
+    readonly setBy: string;
+    readonly setAt: string;
+    readonly updatedAt: string;
+}
+export interface ActiveWorkspacePointerStore {
+    /** The current active pointer, or undefined in unbound mode (no row). */
+    readonly get: () => ActiveWorkspacePointer | undefined;
+    /** Upsert the singleton row (id pinned to 'active'); returns the persisted pointer. */
+    readonly set: (input: {
+        readonly workspaceId: string;
+        readonly setBy: string;
+        readonly atIso: string;
+    }) => ActiveWorkspacePointer;
+    /** Delete the singleton row → unbound mode. Idempotent. */
+    readonly clear: () => void;
+}
+export declare function buildActiveWorkspacePointerStoreOverDatabase(db: DatabaseSync): ActiveWorkspacePointerStore;
+//# sourceMappingURL=active-store.d.ts.map

package/dist/task-workspace/active-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active-store.d.ts","sourceRoot":"","sources":["../../src/task-workspace/active-store.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,2BAA2B;IAC1C,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,sBAAsB,GAAG,SAAS,CAAC;IACvD,uFAAuF;IACvF,QAAQ,CAAC,GAAG,EAAE,CAAC,KAAK,EAAE;QACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;KACxB,KAAK,sBAAsB,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAsCD,wBAAgB,4CAA4C,CAC1D,EAAE,EAAE,YAAY,GACf,2BAA2B,CAgB7B"}