@oscharko-dev/keiko-server 0.2.7 → 0.2.9

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"}

package/dist/task-workspace/errors.js

@@ -0,0 +1,81 @@
+// Structured failure taxonomy for managed task-workspace provisioning + activation (Issue #445).
+//
+// Every failure mode the Issue enumerates — invalid base branch, unsafe path, branch conflict,
+// existing unmanaged path, lock contention, missing repository, worktree pointer drift — maps to ONE
+// explicit code with a deterministic HTTP status and a content-free evidence outcome. A partial
+// failure therefore always leaves a CLASSIFIED, visible state rather than an unclassified one (SC4):
+// the service persists the instance in `failed`/`recovery-required` and emits the matching outcome
+// before the error propagates to the route.
+const ERROR_SPECS = {
+    INVALID_REQUEST: { status: 400, outcome: "blocked" },
+    MISSING_REPOSITORY: { status: 400, outcome: "blocked" },
+    INVALID_BASE_BRANCH: { status: 400, outcome: "blocked" },
+    UNSAFE_PATH: { status: 400, outcome: "blocked" },
+    BRANCH_CONFLICT: { status: 409, outcome: "blocked" },
+    EXISTING_UNMANAGED_PATH: { status: 409, outcome: "blocked" },
+    LOCK_CONTENTION: { status: 409, outcome: "retry-required" },
+    POINTER_DRIFT: { status: 409, outcome: "retry-required" },
+    PROVISIONING_FAILED: { status: 500, outcome: "failed" },
+    WORKSPACE_NOT_FOUND: { status: 404, outcome: "blocked" },
+    ILLEGAL_TRANSITION: { status: 409, outcome: "blocked" },
+    OPERATOR_APPROVAL_REQUIRED: { status: 403, outcome: "blocked" },
+    REPAIR_NOT_APPLICABLE: { status: 409, outcome: "blocked" },
+    REPAIR_FAILED: { status: 500, outcome: "failed" },
+    CLEANUP_NOT_ELIGIBLE: { status: 409, outcome: "blocked" },
+    CLEANUP_FAILED: { status: 500, outcome: "failed" },
+};
+// The caller-facing failure classification (Issue #449, ADR-0093 D3). This is a DISTINCT axis from the
+// evidence `outcome` above: the outcome records what the ledger saw (`blocked`/`failed`/`retry-required`),
+// this class tells a BFF/UI caller what to DO next (retry as-is, route to repair, fix inputs, seek
+// approval, or give up). The map is total by construction — `Record<TaskWorkspaceErrorCode, ...>` requires
+// an entry for every code, so adding a future code without classifying it is a compile-time error and the
+// taxonomy can never silently fall out of date.
+//
+//   retryable     — LOCK_CONTENTION: a live advisory lock held by another actor is TTL-bounded; retry.
+//   repairable    — POINTER_DRIFT: a stale/missing pointer re-fails a bare retry; route to #447 repair.
+//   blocked       — a precondition/validation/conflict/applicability gate: change inputs or state.
+//   policy-denied — OPERATOR_APPROVAL_REQUIRED: needs governance approval, not a retry.
+//   terminal      — a mutation errored after the safety gate authorized it: needs intervention.
+const WORKSPACE_FAILURE_CLASS_BY_CODE = {
+    INVALID_REQUEST: "blocked",
+    MISSING_REPOSITORY: "blocked",
+    INVALID_BASE_BRANCH: "blocked",
+    UNSAFE_PATH: "blocked",
+    BRANCH_CONFLICT: "blocked",
+    EXISTING_UNMANAGED_PATH: "blocked",
+    LOCK_CONTENTION: "retryable",
+    POINTER_DRIFT: "repairable",
+    PROVISIONING_FAILED: "terminal",
+    WORKSPACE_NOT_FOUND: "blocked",
+    ILLEGAL_TRANSITION: "blocked",
+    OPERATOR_APPROVAL_REQUIRED: "policy-denied",
+    REPAIR_NOT_APPLICABLE: "blocked",
+    REPAIR_FAILED: "terminal",
+    CLEANUP_NOT_ELIGIBLE: "blocked",
+    CLEANUP_FAILED: "terminal",
+};
+export function classifyTaskWorkspaceError(code) {
+    return WORKSPACE_FAILURE_CLASS_BY_CODE[code];
+}
+export class TaskWorkspaceError extends Error {
+    code;
+    status;
+    outcome;
+    reasons;
+    constructor(code, message, reasons = []) {
+        super(message);
+        this.name = "TaskWorkspaceError";
+        this.code = code;
+        this.status = ERROR_SPECS[code].status;
+        this.outcome = ERROR_SPECS[code].outcome;
+        this.reasons = reasons;
+    }
+    // The caller-facing failure class, derived (never stored) from the code so it can never drift from the
+    // taxonomy. Route mappers surface it in the error body so the BFF/UI can branch on a stable signal.
+    get failureClass() {
+        return classifyTaskWorkspaceError(this.code);
+    }
+}
+export function taskWorkspaceErrorOutcome(code) {
+    return ERROR_SPECS[code].outcome;
+}

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

@@ -0,0 +1,32 @@
+import type { EvidenceStore } from "@oscharko-dev/keiko-evidence";
+import { TASK_WORKSPACE_SCHEMA_VERSION, type TaskWorkspaceDriftMarker, type TaskWorkspaceHealth, type TaskWorkspaceLifecycleState, type WorkspaceEvent, type WorkspaceEventType } from "@oscharko-dev/keiko-contracts";
+export declare const WORKSPACE_LIFECYCLE_EVIDENCE_KIND: "task-workspace-lifecycle";
+export type WorkspaceLifecycleOperation = "provision" | "activate" | "pause" | "resume" | "handoff" | "reconcile" | "repair" | "cleanup";
+export type WorkspaceLifecycleOutcome = "provisioned" | "activated" | "resumed" | "paused" | "handoff-prepared" | "blocked" | "failed" | "retry-required" | "reconciled" | "repaired" | "operator-required" | "cleanup-requested" | "cleanup-completed" | "cleanup-refused";
+export interface WorkspaceLifecycleEvidenceRecord {
+    readonly kind: typeof WORKSPACE_LIFECYCLE_EVIDENCE_KIND;
+    readonly schemaVersion: typeof TASK_WORKSPACE_SCHEMA_VERSION;
+    readonly recordedAt: number;
+    readonly operation: WorkspaceLifecycleOperation;
+    readonly outcome: WorkspaceLifecycleOutcome;
+    readonly attempt: number;
+    readonly durationMs: number;
+    readonly worktreeCount: number;
+    readonly event: WorkspaceEvent;
+}
+export interface BuildWorkspaceEventInput {
+    readonly eventId: string;
+    readonly workspaceId: string;
+    readonly taskId: string;
+    readonly type: WorkspaceEventType;
+    readonly at: string;
+    readonly correlationId: string;
+    readonly fromState?: TaskWorkspaceLifecycleState | undefined;
+    readonly toState?: TaskWorkspaceLifecycleState | undefined;
+    readonly health?: TaskWorkspaceHealth | undefined;
+    readonly driftMarkers?: readonly TaskWorkspaceDriftMarker[] | undefined;
+    readonly lockId?: string | undefined;
+}
+export declare function buildWorkspaceEvent(input: BuildWorkspaceEventInput): WorkspaceEvent;
+export declare function appendWorkspaceLifecycleEvidence(store: EvidenceStore, record: WorkspaceLifecycleEvidenceRecord, redact: (input: string) => string): string | undefined;
+//# sourceMappingURL=evidence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/task-workspace/evidence.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EACL,6BAA6B,EAE7B,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,2BAA2B,EAChC,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,+BAA+B,CAAC;AAEvC,eAAO,MAAM,iCAAiC,EAAG,0BAAmC,CAAC;AAOrF,MAAM,MAAM,2BAA2B,GACnC,WAAW,GACX,UAAU,GACV,OAAO,GACP,QAAQ,GACR,SAAS,GACT,WAAW,GACX,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,MAAM,yBAAyB,GACjC,aAAa,GACb,WAAW,GACX,SAAS,GACT,QAAQ,GACR,kBAAkB,GAClB,SAAS,GACT,QAAQ,GACR,gBAAgB,GAIhB,YAAY,GACZ,UAAU,GACV,mBAAmB,GAInB,mBAAmB,GACnB,mBAAmB,GACnB,iBAAiB,CAAC;AAEtB,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,OAAO,iCAAiC,CAAC;IACxD,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAC;IAC7D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,2BAA2B,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;CAChC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,2BAA2B,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,2BAA2B,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,wBAAwB,EAAE,GAAG,SAAS,CAAC;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAMD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,cAAc,CAsBnF;AAMD,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,gCAAgC,EACxC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAChC,MAAM,GAAG,SAAS,CAOpB"}

package/dist/task-workspace/evidence.js

@@ -0,0 +1,52 @@
+// Content-free lifecycle evidence for managed task workspaces (Issue #445, Epic #443).
+//
+// Each provision / activate / block / fail / retry-required outcome writes ONE evidence document
+// through the shared EvidenceStore.put port, redacted via the same deepRedactStrings defense-in-depth
+// as the command-runner and memory-audit ledgers. The payload is a #444 `WorkspaceEvent` — validated
+// here against the contract's closed allowlist so a smuggled source/secret field is rejected before
+// persistence (SC3) — plus counts/enums only (operation, outcome, duration, attempt, worktree count).
+// It carries NO repository root, NO worktree path, NO branch name, NO command output.
+//
+// `EvidenceTaskType` is a closed union, so this is NOT an EvidenceManifest: it is a self-describing
+// content-free document keyed by the event id, exactly like the memory-audit ledger entries.
+import { deepRedactStrings } from "@oscharko-dev/keiko-evidence";
+import { TASK_WORKSPACE_SCHEMA_VERSION, validateWorkspaceEvent, } from "@oscharko-dev/keiko-contracts";
+export const WORKSPACE_LIFECYCLE_EVIDENCE_KIND = "task-workspace-lifecycle";
+// Assembles and VALIDATES a content-free WorkspaceEvent. The validation is defense in depth: with the
+// typed inputs above the event is always well-formed, but routing it through the contract validator
+// guarantees no caller can ever persist a non-content-free shape through this path (SC3). Throws on a
+// validation failure rather than persisting a malformed audit record.
+export function buildWorkspaceEvent(input) {
+    const event = {
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        eventId: input.eventId,
+        workspaceId: input.workspaceId,
+        taskId: input.taskId,
+        type: input.type,
+        at: input.at,
+        correlationId: input.correlationId,
+        ...(input.fromState !== undefined ? { fromState: input.fromState } : {}),
+        ...(input.toState !== undefined ? { toState: input.toState } : {}),
+        ...(input.health !== undefined ? { health: input.health } : {}),
+        ...(input.driftMarkers !== undefined ? { driftMarkers: input.driftMarkers } : {}),
+        ...(input.lockId !== undefined ? { lockId: input.lockId } : {}),
+    };
+    const validation = validateWorkspaceEvent(event);
+    if (!validation.ok) {
+        throw new Error(`content-free workspace event invariant violated: ${validation.reasons.join("; ")}`);
+    }
+    return event;
+}
+// Persists ONE lifecycle evidence document, redacting every string leaf first. Best-effort by
+// construction: an evidence-store error must never corrupt the real provisioning result, so it is
+// swallowed and reported as `undefined` (mirrors the command-runner evidence write). Returns the
+// stored location on success.
+export function appendWorkspaceLifecycleEvidence(store, record, redact) {
+    try {
+        const safe = deepRedactStrings(record, redact);
+        return store.put(safe.event.eventId, JSON.stringify(safe, null, 2));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/task-workspace/field-safety.d.ts

@@ -0,0 +1,3 @@
+export declare function containsUnsafeFieldChars(value: string): boolean;
+export declare function assertSafeFieldValue(value: string, field: string): void;
+//# sourceMappingURL=field-safety.d.ts.map

package/dist/task-workspace/field-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-safety.d.ts","sourceRoot":"","sources":["../../src/task-workspace/field-safety.ts"],"names":[],"mappings":"AA4BA,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAO/D;AAID,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIvE"}