@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/task-workspace/active-store.js

@@ -0,0 +1,55 @@
+// Durable singleton active task-workspace pointer (Issue #446, Epic #443).
+//
+// Studio binds exactly ONE active task workspace at a time. The pointer is the durable source of truth
+// for "which workspace is active"; the WorkspaceBinding surfaces consume is DERIVED from the referenced
+// WorkspaceInstance (see binding.ts), never stored here — so there is no second copy of the root to
+// drift. The table is pinned to a single row (id = 'active', CHECK-enforced) over the SAME node:sqlite
+// handle as the UI store and the #445 instance store (schema.ts §V8), so the V8 sibling row shares the
+// single-writer transaction model.
+//
+// The pointer is content-free: an opaque workspace id + an opaque actor id + ISO timestamps. No root,
+// no branch, no path is persisted here. "Clear active" deletes the row → unbound mode.
+const SQL_GET = `SELECT workspace_id, set_by, set_at, updated_at FROM task_workspace_active_pointer WHERE id = 'active'`;
+const SQL_CLEAR = `DELETE FROM task_workspace_active_pointer WHERE id = 'active'`;
+// `set_at` records when the CURRENT workspace became active, `updated_at` the last touch. On conflict
+// the CASE keeps the original `set_at` when the SAME workspace is re-set (an idempotent re-activation
+// preserves its "became active" time) and resets it when switching to a DIFFERENT workspace.
+const SQL_SET = `
+INSERT INTO task_workspace_active_pointer (id, workspace_id, set_by, set_at, updated_at)
+VALUES ('active', ?, ?, ?, ?)
+ON CONFLICT(id) DO UPDATE SET
+  set_at = CASE
+    WHEN task_workspace_active_pointer.workspace_id = excluded.workspace_id
+    THEN task_workspace_active_pointer.set_at
+    ELSE excluded.set_at
+  END,
+  workspace_id = excluded.workspace_id,
+  set_by = excluded.set_by,
+  updated_at = excluded.updated_at
+RETURNING workspace_id, set_by, set_at, updated_at
+`;
+function rowToPointer(row) {
+    return {
+        workspaceId: row.workspace_id,
+        setBy: row.set_by,
+        setAt: row.set_at,
+        updatedAt: row.updated_at,
+    };
+}
+export function buildActiveWorkspacePointerStoreOverDatabase(db) {
+    return {
+        get: () => {
+            const row = db.prepare(SQL_GET).get();
+            return row === undefined ? undefined : rowToPointer(row);
+        },
+        set: (input) => {
+            const row = db
+                .prepare(SQL_SET)
+                .get(input.workspaceId, input.setBy, input.atIso, input.atIso);
+            return rowToPointer(row);
+        },
+        clear: () => {
+            db.prepare(SQL_CLEAR).run();
+        },
+    };
+}

package/dist/task-workspace/authorization.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import type { UiHandlerDeps } from "../deps.js";
+type ManagedRootDeps = Pick<UiHandlerDeps, "managedTaskWorkspaceRoot" | "store" | "workspaceProvisioning">;
+export declare function resolveManagedTaskWorkspaceRoot(deps: Pick<ManagedRootDeps, "managedTaskWorkspaceRoot" | "workspaceProvisioning">, root: string): WorkspaceInfo | undefined;
+export declare function resolveRegisteredOrManagedWorkspaceRoot(deps: ManagedRootDeps, root: string): WorkspaceInfo | undefined;
+export {};
+//# sourceMappingURL=authorization.d.ts.map

package/dist/task-workspace/authorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../../src/task-workspace/authorization.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,KAAK,eAAe,GAAG,IAAI,CACzB,aAAa,EACb,0BAA0B,GAAG,OAAO,GAAG,uBAAuB,CAC/D,CAAC;AAmBF,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,IAAI,CAAC,eAAe,EAAE,0BAA0B,GAAG,uBAAuB,CAAC,EACjF,IAAI,EAAE,MAAM,GACX,aAAa,GAAG,SAAS,CAiB3B;AAED,wBAAgB,uCAAuC,CACrD,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,MAAM,GACX,aAAa,GAAG,SAAS,CAK3B"}

package/dist/task-workspace/authorization.js

@@ -0,0 +1,54 @@
+// Authorization helpers for task-bound execution roots (Epic #443).
+//
+// Legacy BFF routes authorize `projectId` / `workspaceRoot` against the UI project store. A bound task
+// workspace intentionally points those surfaces at a managed worktree instead, so the route boundary
+// must accept that root only when it can be re-proven from the persisted WorkspaceInstance and the
+// Keiko-owned managed root. This does not grant arbitrary filesystem authority: the leaf id, persisted
+// path, derived managed path, realpath containment, and on-disk presence must all agree.
+import { basename } from "node:path";
+import { isManagedTargetContained, managedTargetExists } from "./managed-root.js";
+import { deriveManagedWorktreePath } from "./naming.js";
+function workspaceInfo(root) {
+    return {
+        root,
+        name: undefined,
+        version: undefined,
+        testFramework: "unknown",
+        sourceDirs: [],
+        testDirs: [],
+        languages: [],
+        ignoreLines: [],
+    };
+}
+function pathLeaf(path) {
+    return basename(path.replace(/[/\\]+$/u, ""));
+}
+export function resolveManagedTaskWorkspaceRoot(deps, root) {
+    const managedRoot = deps.managedTaskWorkspaceRoot;
+    const provisioning = deps.workspaceProvisioning;
+    if (managedRoot === undefined || provisioning === undefined || root.length === 0) {
+        return undefined;
+    }
+    const instance = provisioning.getInstance(pathLeaf(root));
+    if (instance === undefined)
+        return undefined;
+    const expected = deriveManagedWorktreePath({
+        managedRoot,
+        repositoryId: instance.repositoryId,
+        workspaceId: instance.workspaceId,
+    });
+    if (root !== expected || instance.managedWorktreePath !== expected)
+        return undefined;
+    if (!isManagedTargetContained(managedRoot, instance.managedWorktreePath))
+        return undefined;
+    if (!managedTargetExists(instance.managedWorktreePath))
+        return undefined;
+    return workspaceInfo(instance.managedWorktreePath);
+}
+export function resolveRegisteredOrManagedWorkspaceRoot(deps, root) {
+    for (const project of deps.store.listProjects()) {
+        if (project.path === root)
+            return workspaceInfo(project.path);
+    }
+    return resolveManagedTaskWorkspaceRoot(deps, root);
+}

package/dist/task-workspace/binding.d.ts

@@ -0,0 +1,3 @@
+import { type WorkspaceBinding, type WorkspaceInstance } from "@oscharko-dev/keiko-contracts";
+export declare function buildBinding(instance: WorkspaceInstance): WorkspaceBinding;
+//# sourceMappingURL=binding.d.ts.map

package/dist/task-workspace/binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding.d.ts","sourceRoot":"","sources":["../../src/task-workspace/binding.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAEvC,wBAAgB,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,gBAAgB,CAU1E"}

package/dist/task-workspace/binding.js

@@ -0,0 +1,22 @@
+// Derive the authoritative active-workspace binding from a persisted instance (Issue #446, Epic #443).
+//
+// The #444 contract makes the WorkspaceBinding the single source of truth surfaces consume, with the
+// invariant gitDeliveryRoot === activeRoot === editorProjectRoot enforced by validateWorkspaceBinding.
+// #445 first computed this binding privately inside provisioning; #446 promotes it to a shared helper
+// so BOTH the provisioning/activation path AND the #446 lifecycle/active-pointer path derive the same
+// binding from a stored instance — there is exactly one derivation, never a recomputed second one.
+//
+// The active root is the managed worktree path: every bound surface (editor/runtime/git-delivery/
+// terminal/files/...) operates on the task's isolated worktree, never the bare repository root.
+import { TASK_WORKSPACE_SCHEMA_VERSION, TASK_WORKSPACE_SURFACES, } from "@oscharko-dev/keiko-contracts";
+export function buildBinding(instance) {
+    return {
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        workspaceId: instance.workspaceId,
+        taskId: instance.taskId,
+        activeRoot: instance.managedWorktreePath,
+        boundSurfaces: TASK_WORKSPACE_SURFACES,
+        gitDeliveryRoot: instance.managedWorktreePath,
+        editorProjectRoot: instance.managedWorktreePath,
+    };
+}

package/dist/task-workspace/cleanup.d.ts

@@ -0,0 +1,4 @@
+import type { WorkspaceCleanupService, WorkspaceCleanupServiceDeps } from "./types.js";
+export declare function safelyRemoveManagedPath(managedRoot: string, target: string): void;
+export declare function createWorkspaceCleanupService(deps: WorkspaceCleanupServiceDeps): WorkspaceCleanupService;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/task-workspace/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/task-workspace/cleanup.ts"],"names":[],"mappings":"AAgDA,OAAO,KAAK,EAGV,uBAAuB,EACvB,2BAA2B,EAI5B,MAAM,YAAY,CAAC;AAiCpB,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAcjF;AAgeD,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,2BAA2B,GAChC,uBAAuB,CAgBzB"}

package/dist/task-workspace/cleanup.js

@@ -0,0 +1,428 @@
+// Governed cleanup for managed task workspaces (Issue #448, Epic #443).
+//
+// Cleanup is the destructive counterpart to health. It NEVER removes anything without (a) operator
+// approval (the #444 request-cleanup / complete-cleanup operations both require it), (b) a LIVE
+// re-verification of containment + ownership + cleanliness + lock liveness at the moment of removal —
+// the persisted `managedWorktreePath` is NEVER trusted (SC2) — and (c) the pure cleanup-safety gate
+// allowing it. A refusal is a FIRST-CLASS successful safety outcome, audited and returned, never thrown
+// (SC4). Removal goes through the governed worktree adapter first, falling back only to a single
+// ownership-and-realpath-gated `safelyRemoveManagedPath` choke point — the ONLY place a filesystem
+// deletion happens, defended so it can never escape the Keiko-owned managed root (SC1).
+//
+// It REUSES the existing engines and adds none: containment + ownership are the #445 managed-root
+// helpers, worktree removal is the narrow #445 adapter, fact gathering is the #447 reconciliation path,
+// the lifecycle transition is the #444 contract gate, and every outcome writes the same content-free
+// lifecycle evidence as provisioning/reconciliation/repair.
+import { existsSync, readdirSync, realpathSync, rmSync } from "node:fs";
+import { join, relative } from "node:path";
+import { detectWorkspaceAt } from "@oscharko-dev/keiko-workspace";
+import { TASK_WORKSPACE_SCHEMA_VERSION, evaluateWorkspaceCleanupSafety, isCleanupEligibleLifecycleState, validateTaskWorkspaceTransition, } from "@oscharko-dev/keiko-contracts";
+import { deriveRepositoryId } from "./naming.js";
+import { assertManagedTargetContained, isManagedRootOwned, isManagedTargetContained, } from "./managed-root.js";
+import { deriveOrphanId } from "./health.js";
+import { assertSafeFieldValue } from "./field-safety.js";
+import { gatherInstanceReconciliationFacts } from "./reconciliation.js";
+import { lockIsLive, makeWorkspaceLock, resolveLockTtl } from "./locks.js";
+import { workspaceKey } from "./mutex.js";
+import { TaskWorkspaceError } from "./errors.js";
+import { appendWorkspaceLifecycleEvidence, buildWorkspaceEvent, WORKSPACE_LIFECYCLE_EVIDENCE_KIND, } from "./evidence.js";
+const MAX_FIELD_LENGTH = 512;
+function isBoundedNonEmpty(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= MAX_FIELD_LENGTH;
+}
+function isoFrom(nowMs) {
+    return new Date(nowMs).toISOString();
+}
+// The SINGLE filesystem-deletion choke point (SC1). Before `rmSync` it proves: (1) Keiko owns the
+// managed root (the marker file is present — never created here), (2) the target realpath-resolves
+// inside the managed root (rejects symlink escape, parent traversal, out-of-root absolute targets),
+// and (3) the target is a strict `<repositoryId>/<leaf>` descendant (never the managed root itself nor
+// a bare repository-id directory). Any failure throws a content-free error and removes nothing.
+// Exported so the security negative matrix exercises the guard directly.
+export function safelyRemoveManagedPath(managedRoot, target) {
+    if (!isManagedRootOwned(managedRoot)) {
+        throw new TaskWorkspaceError("UNSAFE_PATH", "managed root ownership could not be proven");
+    }
+    // Throws UNSAFE_PATH on any lexical/realpath containment failure (delegated to keiko-workspace).
+    assertManagedTargetContained(managedRoot, target);
+    const rootReal = realpathSync(managedRoot);
+    const targetReal = realpathSync(target);
+    const rel = relative(rootReal, targetReal);
+    const segments = rel.split(/[\\/]/u).filter((segment) => segment.length > 0);
+    if (rel.length === 0 || rel.startsWith("..") || segments.includes("..") || segments.length < 2) {
+        throw new TaskWorkspaceError("UNSAFE_PATH", "refusing to remove a non-leaf managed path");
+    }
+    rmSync(targetReal, { recursive: true, force: false });
+}
+function emit(ctx, input) {
+    const event = buildWorkspaceEvent({
+        eventId: ctx.deps.newId(),
+        workspaceId: input.workspaceId,
+        taskId: input.taskId,
+        type: input.type,
+        at: isoFrom(input.nowMs),
+        correlationId: input.correlationId,
+        ...(input.fromState !== undefined ? { fromState: input.fromState } : {}),
+        ...(input.toState !== undefined ? { toState: input.toState } : {}),
+    });
+    appendWorkspaceLifecycleEvidence(ctx.deps.evidenceStore, {
+        kind: WORKSPACE_LIFECYCLE_EVIDENCE_KIND,
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        recordedAt: input.nowMs,
+        operation: "cleanup",
+        outcome: input.outcome,
+        attempt: 1,
+        durationMs: 0,
+        worktreeCount: 0,
+        event,
+    }, ctx.deps.redactString);
+}
+function loadInstance(ctx, workspaceId) {
+    if (!isBoundedNonEmpty(workspaceId)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "invalid workspaceId");
+    }
+    const instance = ctx.deps.store.getById(workspaceId);
+    if (instance === undefined) {
+        throw new TaskWorkspaceError("WORKSPACE_NOT_FOUND", "workspace not found");
+    }
+    return instance;
+}
+function hasPersistedWorkspaceForCandidate(ctx, repositoryId, leaf, candidate) {
+    const byWorkspaceId = ctx.deps.store.getById(leaf);
+    if (byWorkspaceId?.repositoryId === repositoryId &&
+        byWorkspaceId.managedWorktreePath === candidate) {
+        return true;
+    }
+    return ctx.deps.store
+        .listAll()
+        .some((instance) => instance.repositoryId === repositoryId && instance.managedWorktreePath === candidate);
+}
+// request-cleanup: a settled (cleanup-eligible) instance → cleanup-pending. Operator-approval gated by
+// the #444 transition precondition table; no physical removal happens here.
+// The *->cleanup-pending transition gate (operator-approval is the precondition the contract table
+// carries for it). Extracted so requestCleanupImpl stays small.
+function assertCleanupTransitionApproved(instance, operatorApproved) {
+    const transition = validateTaskWorkspaceTransition({
+        from: instance.lifecycleState,
+        to: "cleanup-pending",
+        context: {
+            lockHeldByActor: true,
+            pathContained: false,
+            worktreeClean: false,
+            branchReady: false,
+            providerReady: false,
+            operatorApproved,
+        },
+    });
+    if (!transition.ok) {
+        throw new TaskWorkspaceError("OPERATOR_APPROVAL_REQUIRED", "cleanup request requires operator approval", transition.reasons);
+    }
+}
+function requestCleanupImpl(ctx, request) {
+    const instance = loadInstance(ctx, request.workspaceId);
+    if (!isBoundedNonEmpty(request.requestedBy)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "requestedBy is required");
+    }
+    assertSafeFieldValue(request.requestedBy, "requestedBy");
+    if (!isCleanupEligibleLifecycleState(instance.lifecycleState)) {
+        throw new TaskWorkspaceError("CLEANUP_NOT_ELIGIBLE", `workspace in ${instance.lifecycleState} is not eligible for cleanup`);
+    }
+    if (instance.lifecycleState === "cleanup-pending") {
+        // Idempotent: already requested.
+        return { outcome: "requested", workspaceId: instance.workspaceId, instance };
+    }
+    assertCleanupTransitionApproved(instance, request.operatorApproved);
+    const nowMs = ctx.deps.now();
+    const fromState = instance.lifecycleState;
+    const persisted = ctx.deps.store.upsert({
+        ...instance,
+        lifecycleState: "cleanup-pending",
+        updatedAt: isoFrom(nowMs),
+    });
+    emit(ctx, {
+        outcome: "cleanup-requested",
+        type: "cleanup-requested",
+        workspaceId: persisted.workspaceId,
+        taskId: persisted.taskId,
+        correlationId: persisted.auditCorrelationId,
+        fromState,
+        toState: persisted.lifecycleState,
+        nowMs,
+    });
+    return { outcome: "requested", workspaceId: persisted.workspaceId, instance: persisted };
+}
+// Re-gathers the LIVE facts for one instance (never trusting the persisted row) and runs the pure
+// safety gate. Builds its own repo-root adapter for structural facts and a worktree-bound adapter for
+// the dirty probe.
+// Live dirty probe for the DESTRUCTIVE path. Unlike the read-only health probe (health.ts, which treats
+// an inconclusive probe as not-dirty because it never deletes), this fails CLOSED: an existing,
+// contained worktree whose `git status` is inconclusive (`ok:false` — a corrupt/missing `.git` pointer
+// leaves the directory and its uncommitted/untracked files on disk while git refuses to read it) is
+// treated as DIRTY. A structurally-broken tree that may still hold real work is therefore refused
+// rather than force-removed (SC4). A missing worktree (nothing to lose) probes not-dirty.
+async function probeCleanupDirty(ctx, worktreePath, probeable) {
+    if (!probeable)
+        return false;
+    const status = await ctx.deps.createAdapter(detectWorkspaceAt(worktreePath)).worktreeStatus();
+    return !status.ok || status.dirty;
+}
+async function evaluateLiveCleanupSafety(ctx, instance) {
+    const adapter = ctx.deps.createAdapter(detectWorkspaceAt(instance.repositoryRoot));
+    const worktrees = await adapter.listWorktrees();
+    const { facts } = await gatherInstanceReconciliationFacts(ctx.deps, adapter, worktrees, instance, ctx.deps.now());
+    const worktreeDirty = await probeCleanupDirty(ctx, instance.managedWorktreePath, facts.worktreeDirExists && facts.pathContained);
+    return evaluateWorkspaceCleanupSafety({
+        lifecycleState: instance.lifecycleState,
+        hasRecord: true,
+        pathContained: facts.pathContained,
+        ownershipProven: isManagedRootOwned(ctx.deps.managedRoot),
+        worktreeDirty,
+        lockLive: facts.lockLive,
+    });
+}
+// Governed physical removal of a managed worktree: the narrow adapter `remove --force` first (the
+// safety gate already proved the tree is clean, contained, and owned), then a `prune` to clear the
+// admin entry; if the directory git no longer tracks survives, the gated `safelyRemoveManagedPath`
+// fallback removes it. Throws CLEANUP_FAILED only on an unexpected IO error.
+async function removeManagedWorktree(ctx, repositoryRoot, worktreePath) {
+    try {
+        const adapter = ctx.deps.createAdapter(detectWorkspaceAt(repositoryRoot));
+        const removal = await adapter.removeWorktree({ worktreePath, force: true });
+        await adapter.pruneWorktrees();
+        if (existsSync(worktreePath)) {
+            const dirty = await probeCleanupDirty(ctx, worktreePath, true);
+            if (dirty || !removal.ok) {
+                return { removed: false, refusalReason: "worktree-dirty" };
+            }
+            safelyRemoveManagedPath(ctx.deps.managedRoot, worktreePath);
+        }
+        return { removed: true };
+    }
+    catch (error) {
+        if (error instanceof TaskWorkspaceError)
+            throw error;
+        throw new TaskWorkspaceError("CLEANUP_FAILED", "governed worktree removal failed");
+    }
+}
+function cleanupLock(ctx, requestedBy, nowMs) {
+    return makeWorkspaceLock({
+        newId: ctx.deps.newId,
+        owner: requestedBy,
+        reason: "cleanup",
+        nowMs,
+        ttlMs: ctx.lockTtlMs,
+    });
+}
+// Emits the content-free refusal event and returns the refused result (a successful safety outcome).
+function refuseCleanup(ctx, instance, refusalReason) {
+    emit(ctx, {
+        outcome: "cleanup-refused",
+        type: "transition-rejected",
+        workspaceId: instance.workspaceId,
+        taskId: instance.taskId,
+        correlationId: instance.auditCorrelationId,
+        fromState: instance.lifecycleState,
+        nowMs: ctx.deps.now(),
+    });
+    return {
+        outcome: "refused",
+        workspaceId: instance.workspaceId,
+        ...(refusalReason !== undefined ? { refusalReason } : {}),
+    };
+}
+// Performs the approved removal: acquire the cleanup lock (the #444 complete-cleanup operation requires
+// one) as a concurrency marker, remove the worktree through the governed path, clear the active pointer,
+// delete the retired row, and audit. The content-free history survives in the evidence ledger.
+async function finalizeCleanup(ctx, instance, requestedBy, nowMs) {
+    const locked = ctx.deps.store.upsert({
+        ...instance,
+        lock: cleanupLock(ctx, requestedBy, nowMs),
+        updatedAt: isoFrom(nowMs),
+    });
+    const removal = await removeManagedWorktree(ctx, locked.repositoryRoot, locked.managedWorktreePath);
+    if (!removal.removed) {
+        const unlocked = ctx.deps.store.upsert({
+            ...locked,
+            lock: null,
+            updatedAt: isoFrom(ctx.deps.now()),
+        });
+        return refuseCleanup(ctx, unlocked, removal.refusalReason);
+    }
+    if (ctx.deps.activePointerStore.get()?.workspaceId === locked.workspaceId) {
+        ctx.deps.activePointerStore.clear();
+    }
+    ctx.deps.store.delete(locked.workspaceId);
+    emit(ctx, {
+        outcome: "cleanup-completed",
+        type: "cleanup-completed",
+        workspaceId: locked.workspaceId,
+        taskId: locked.taskId,
+        correlationId: locked.auditCorrelationId,
+        fromState: "cleanup-pending",
+        nowMs: ctx.deps.now(),
+    });
+    return { outcome: "completed", workspaceId: locked.workspaceId };
+}
+// The pre-removal guards: bounded actor, operator approval, no foreign live lock, and a cleanup-pending
+// lifecycle. Throws on any violation (these are caller errors, not safety refusals).
+function assertCompleteCleanupAllowed(ctx, request, instance, nowMs) {
+    if (!request.operatorApproved) {
+        throw new TaskWorkspaceError("OPERATOR_APPROVAL_REQUIRED", "cleanup requires operator approval");
+    }
+    if (lockIsLive(instance.lock, nowMs, ctx.lockTtlMs) &&
+        instance.lock?.owner !== request.requestedBy) {
+        throw new TaskWorkspaceError("LOCK_CONTENTION", "workspace is locked by another actor");
+    }
+    if (instance.lifecycleState !== "cleanup-pending") {
+        throw new TaskWorkspaceError("CLEANUP_NOT_ELIGIBLE", "complete-cleanup requires a cleanup-pending workspace (request cleanup first)");
+    }
+}
+// complete-cleanup: the live-verified governed removal of a cleanup-pending instance (lock + operator
+// approval). Re-verifies safety LIVE; on refusal it audits and returns (never throws).
+async function completeCleanupImpl(ctx, request) {
+    if (!isBoundedNonEmpty(request.requestedBy)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "requestedBy is required");
+    }
+    assertSafeFieldValue(request.requestedBy, "requestedBy");
+    const instance = loadInstance(ctx, request.workspaceId);
+    const nowMs = ctx.deps.now();
+    assertCompleteCleanupAllowed(ctx, request, instance, nowMs);
+    const safety = await evaluateLiveCleanupSafety(ctx, instance);
+    if (!safety.allowed)
+        return refuseCleanup(ctx, instance, safety.refusalReason);
+    return finalizeCleanup(ctx, instance, request.requestedBy, nowMs);
+}
+// Governed removal of orphaned managed worktrees: directories under the managed root with no persisted
+// record. Each is realpath-contained, ownership-proven, and dirty-probed before the gated fs removal;
+// an unsafe orphan is refused with its content-free reason, never removed.
+async function cleanupOneOrphan(ctx, repositoryId, leaf, ownershipProven) {
+    const orphanId = deriveOrphanId(repositoryId, leaf);
+    const candidate = join(ctx.deps.managedRoot, repositoryId, leaf);
+    if (hasPersistedWorkspaceForCandidate(ctx, repositoryId, leaf, candidate)) {
+        return { removed: false };
+    }
+    const pathContained = isManagedTargetContained(ctx.deps.managedRoot, candidate);
+    // Fail closed: an orphan whose `git status` is inconclusive (broken pointer) is treated as dirty and
+    // refused, never force-removed (SC4) — it may still hold uncommitted work.
+    const worktreeDirty = await probeCleanupDirty(ctx, candidate, pathContained);
+    const decision = evaluateWorkspaceCleanupSafety({
+        lifecycleState: "abandoned",
+        hasRecord: false,
+        pathContained,
+        ownershipProven,
+        worktreeDirty,
+        lockLive: false,
+    });
+    if (!decision.allowed) {
+        return {
+            removed: false,
+            refusal: { orphanId, refusalReason: decision.refusalReason ?? "path-escape" },
+        };
+    }
+    const stillDirty = await probeCleanupDirty(ctx, candidate, pathContained);
+    if (stillDirty) {
+        return {
+            removed: false,
+            refusal: { orphanId, refusalReason: "worktree-dirty" },
+        };
+    }
+    safelyRemoveManagedPath(ctx.deps.managedRoot, candidate);
+    emit(ctx, {
+        outcome: "cleanup-completed",
+        type: "cleanup-completed",
+        workspaceId: orphanId,
+        taskId: orphanId,
+        correlationId: orphanId,
+        nowMs: ctx.deps.now(),
+    });
+    return { removed: true };
+}
+function orphanLeavesFor(ctx, repositoryId, knownPaths) {
+    const repoDir = join(ctx.deps.managedRoot, repositoryId);
+    if (!existsSync(repoDir))
+        return [];
+    try {
+        return readdirSync(repoDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .filter((leaf) => !knownPaths.has(join(repoDir, leaf)));
+    }
+    catch {
+        return [];
+    }
+}
+// The repository-id set to sweep: the requested repository only, or — for a global sweep — every
+// repository with a persisted record plus every repository-id directory still on disk. The
+// persisted-record ids are read from the already-built `knownByRepo` map (its keys ARE the distinct
+// persisted repository ids) rather than a second `store.listAll()`, so the global sweep scans the store
+// once instead of twice (#449 perf review — avoids re-running rowToInstance + validate over every row).
+function resolveOrphanRepositoryIds(ctx, request, knownByRepo) {
+    if (request.repositoryRoot !== undefined && request.repositoryRoot.length > 0) {
+        return new Set([deriveRepositoryId(request.repositoryRoot)]);
+    }
+    const ids = new Set(knownByRepo.keys());
+    for (const onDisk of managedRepoDirs(ctx))
+        ids.add(onDisk);
+    return ids;
+}
+// The managed worktree paths a persisted record claims, grouped by repository id, so the orphan sweep
+// can exclude them.
+function buildKnownPathsByRepo(ctx) {
+    const knownByRepo = new Map();
+    for (const instance of ctx.deps.store.listAll()) {
+        const set = knownByRepo.get(instance.repositoryId) ?? new Set();
+        set.add(instance.managedWorktreePath);
+        knownByRepo.set(instance.repositoryId, set);
+    }
+    return knownByRepo;
+}
+async function cleanupOrphansImpl(ctx, request) {
+    if (!isBoundedNonEmpty(request.requestedBy)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "requestedBy is required");
+    }
+    assertSafeFieldValue(request.requestedBy, "requestedBy");
+    if (!request.operatorApproved) {
+        throw new TaskWorkspaceError("OPERATOR_APPROVAL_REQUIRED", "cleanup requires operator approval");
+    }
+    const ownershipProven = isManagedRootOwned(ctx.deps.managedRoot);
+    const knownByRepo = buildKnownPathsByRepo(ctx);
+    let removed = 0;
+    const refused = [];
+    for (const repositoryId of resolveOrphanRepositoryIds(ctx, request, knownByRepo)) {
+        const known = knownByRepo.get(repositoryId) ?? new Set();
+        for (const leaf of orphanLeavesFor(ctx, repositoryId, known)) {
+            // Serialize each candidate leaf and re-check persisted liveness inside the critical section. The
+            // initial known-path snapshot may be stale if a provision finishes while a sweep is walking disk.
+            const outcome = await ctx.deps.mutex.runExclusive([workspaceKey(leaf)], () => cleanupOneOrphan(ctx, repositoryId, leaf, ownershipProven));
+            if (outcome.removed)
+                removed += 1;
+            if (outcome.refusal !== undefined)
+                refused.push(outcome.refusal);
+        }
+    }
+    return { removed, refused };
+}
+function managedRepoDirs(ctx) {
+    if (!existsSync(ctx.deps.managedRoot))
+        return [];
+    try {
+        return readdirSync(ctx.deps.managedRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+export function createWorkspaceCleanupService(deps) {
+    const ctx = { deps, lockTtlMs: resolveLockTtl(deps.lockTtlMs) };
+    return {
+        // Serialized under the workspace's `ws:` key (#449, ADR-0093 D1) so a governed removal cannot race a
+        // concurrent activate/pause/repair of the same workspace. `runExclusive` also turns a synchronous
+        // validation throw from requestCleanupImpl into a rejected promise (the consistent async contract).
+        cleanup: (request) => ctx.deps.mutex.runExclusive([workspaceKey(request.workspaceId)], () => request.mode === "request"
+            ? requestCleanupImpl(ctx, request)
+            : completeCleanupImpl(ctx, request)),
+        cleanupOrphans: (request) => cleanupOrphansImpl(ctx, request),
+    };
+}

package/dist/task-workspace/errors.d.ts

@@ -0,0 +1,14 @@
+export type TaskWorkspaceErrorCode = "INVALID_REQUEST" | "MISSING_REPOSITORY" | "INVALID_BASE_BRANCH" | "UNSAFE_PATH" | "BRANCH_CONFLICT" | "EXISTING_UNMANAGED_PATH" | "LOCK_CONTENTION" | "POINTER_DRIFT" | "PROVISIONING_FAILED" | "WORKSPACE_NOT_FOUND" | "ILLEGAL_TRANSITION" | "OPERATOR_APPROVAL_REQUIRED" | "REPAIR_NOT_APPLICABLE" | "REPAIR_FAILED" | "CLEANUP_NOT_ELIGIBLE" | "CLEANUP_FAILED";
+import type { WorkspaceFailureClass } from "@oscharko-dev/keiko-contracts";
+export type WorkspaceFailureOutcome = "blocked" | "failed" | "retry-required";
+export declare function classifyTaskWorkspaceError(code: TaskWorkspaceErrorCode): WorkspaceFailureClass;
+export declare class TaskWorkspaceError extends Error {
+    readonly code: TaskWorkspaceErrorCode;
+    readonly status: number;
+    readonly outcome: WorkspaceFailureOutcome;
+    readonly reasons: readonly string[];
+    constructor(code: TaskWorkspaceErrorCode, message: string, reasons?: readonly string[]);
+    get failureClass(): WorkspaceFailureClass;
+}
+export declare function taskWorkspaceErrorOutcome(code: TaskWorkspaceErrorCode): WorkspaceFailureOutcome;
+//# sourceMappingURL=errors.d.ts.map

package/dist/task-workspace/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/task-workspace/errors.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,sBAAsB,GAC9B,iBAAiB,GACjB,oBAAoB,GACpB,qBAAqB,GACrB,aAAa,GACb,iBAAiB,GACjB,yBAAyB,GACzB,iBAAiB,GACjB,eAAe,GACf,qBAAqB,GACrB,qBAAqB,GACrB,oBAAoB,GAIpB,4BAA4B,GAC5B,uBAAuB,GACvB,eAAe,GAIf,sBAAsB,GACtB,gBAAgB,CAAC;AAErB,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAK3E,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,QAAQ,GAAG,gBAAgB,CAAC;AA2D9E,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,sBAAsB,GAAG,qBAAqB,CAE9F;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAgB,IAAI,EAAE,sBAAsB,CAAC;IAC7C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,uBAAuB,CAAC;IACjD,SAAgB,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;gBAGzC,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,SAAS,MAAM,EAAO;IAYjC,IAAW,YAAY,IAAI,qBAAqB,CAE/C;CACF;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,GAAG,uBAAuB,CAE/F"}