@oscharko-dev/keiko-server 0.2.8 → 0.2.9

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

package/dist/task-workspace/field-safety.js

@@ -0,0 +1,42 @@
+// Strict free-form identity-field guard for managed task workspaces
+// (Issue #449 / PR #1587 security follow-up — LOW, defense in depth).
+//
+// `requestedBy` and `taskId` are length-bounded but otherwise free-form. They flow into the advisory
+// lock `owner` (locks.ts makeWorkspaceLock), the active-pointer `setBy` (lifecycle.ts setActiveImpl),
+// the persisted WorkspaceInstance, and the content-free lifecycle evidence — all of which may later be
+// surfaced to an operator. There is no injection sink in the server layer today, so this is a
+// fail-closed hardening: a C0/C1/DEL control, a zero-width, or a bidirectional-override
+// ("Trojan-source") code point in an identity field signals a bug or a spoofing attempt (a forged
+// operator name on an audit line, a reordered task id), never legitimate input.
+//
+// We REJECT rather than strip. `taskId` is the idempotency key — it is hashed raw into the workspace
+// id, the task branch, and the managed worktree path (naming.ts) — and `requestedBy` is compared by
+// equality for advisory-lock ownership. Silently stripping would change the derived identity and could
+// collapse two distinct actors to the same owner string; rejecting keeps the persisted identity
+// faithful to the caller's input.
+//
+// The unsafe character set IS the canonical `stripUnsafeFormatChars` primitive (keiko-contracts
+// text-safety), reused so the security-critical Unicode ranges live in exactly one place, made
+// STRICTER: identity fields are single-line tokens, so the TAB/LF/CR that text-safety deliberately
+// preserves for multi-line evidence are forbidden here too (they would otherwise enable log-line
+// spoofing in an operator audit view).
+import { stripUnsafeFormatChars } from "@oscharko-dev/keiko-contracts/text-safety";
+import { TaskWorkspaceError } from "./errors.js";
+// True when `value` carries any control (C0/C1/DEL, incl. TAB/LF/CR), zero-width, BOM, or
+// bidirectional-override code point. Pure; no allocation on the common (clean) path.
+export function containsUnsafeFieldChars(value) {
+    // stripUnsafeFormatChars removes C0/C1/DEL (except TAB/LF/CR) + bidi/zero-width/BOM and returns the
+    // SAME reference when nothing was removed, so a reference inequality means an unsafe code point was
+    // present. The TAB/LF/CR that text-safety preserves are caught explicitly to keep identity fields
+    // strictly single-line.
+    if (stripUnsafeFormatChars(value) !== value)
+        return true;
+    return /[\t\n\r]/u.test(value);
+}
+// Throws INVALID_REQUEST when a free-form identity field carries a forbidden code point. `field` names
+// the offending field in the reason list WITHOUT echoing its (untrusted) value.
+export function assertSafeFieldValue(value, field) {
+    if (containsUnsafeFieldChars(value)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "field contains forbidden characters", [field]);
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { WorkspaceHealthService, WorkspaceHealthServiceDeps } from "./types.js";
+export declare function deriveOrphanId(repositoryId: string, leaf: string): string;
+export declare function createWorkspaceHealthService(deps: WorkspaceHealthServiceDeps): WorkspaceHealthService;
+//# sourceMappingURL=health.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/task-workspace/health.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAAE,sBAAsB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAWrF,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKzE;AAsKD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,0BAA0B,GAC/B,sBAAsB,CAKxB"}

package/dist/task-workspace/health.js

@@ -0,0 +1,163 @@
+// Operational health + drift evaluation and orphan detection for managed task workspaces (Issue #448,
+// Epic #443).
+//
+// This is the READ-ONLY observation surface. For each persisted instance it gathers the SAME
+// content-free facts the #447 reconciler uses — realpath containment, the `.git` pointer/HEAD/branch
+// identity, and lock liveness (delegated to gatherInstanceReconciliationFacts, no second engine) — then
+// adds the two #448-specific LIVE signals the narrow #445 adapter could not provide before: a
+// `git status --porcelain` dirty probe (through the read-only `status` verb added in #448) and the
+// managed-root ownership proof. Every classification decision is deferred to the pure contract
+// (classifyWorkspaceHealth), so health stays deterministic and 100%-testable.
+//
+// It additionally detects ORPHANED managed worktrees: directories under the Keiko-owned managed root
+// that no persisted record references. Each candidate is realpath-contained before it is reported, and
+// it is surfaced with a content-free `orphanId` (a hash of its managed-root-relative location) so the
+// report carries no path. The service performs NO store writes and emits NO evidence — reconciliation
+// (#447) owns the persisted health columns and their events; health is pure observation.
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { detectWorkspaceAt } from "@oscharko-dev/keiko-workspace";
+import { TASK_WORKSPACE_SCHEMA_VERSION, classifyWorkspaceHealth, deriveOrphanWorktreeHealthEntry, deriveWorkspaceHealthEntry, evaluateWorkspaceCleanupSafety, } from "@oscharko-dev/keiko-contracts";
+import { deriveRepositoryId } from "./naming.js";
+import { isManagedRootOwned, isManagedTargetContained } from "./managed-root.js";
+import { gatherInstanceReconciliationFacts } from "./reconciliation.js";
+const ORPHAN_ID_PREFIX = "orph_";
+function isoFrom(nowMs) {
+    return new Date(nowMs).toISOString();
+}
+// Content-free identity for an orphaned managed directory: a hash of its managed-root-relative
+// `<repositoryId>/<leaf>` location, so the report references the orphan without leaking any path.
+// Exported so the cleanup service references the SAME id when it acts on or refuses an orphan.
+export function deriveOrphanId(repositoryId, leaf) {
+    return (ORPHAN_ID_PREFIX +
+        createHash("sha256").update(`${repositoryId}/${leaf}`, "utf8").digest("hex").slice(0, 24));
+}
+// A live dirty probe through a worktree-bound adapter. Only meaningful when the worktree exists and is
+// contained; an inconclusive probe (broken pointer, unreadable tree) reports not-dirty — the structural
+// classification already surfaces a broken/missing worktree, and containment + ownership remain the
+// authoritative cleanup guards.
+async function probeDirty(deps, worktreePath, probeable) {
+    if (!probeable)
+        return false;
+    const adapter = deps.createAdapter(detectWorkspaceAt(worktreePath));
+    const status = await adapter.worktreeStatus();
+    return status.ok && status.dirty;
+}
+// Classifies ONE persisted instance against pre-fetched repository worktree state, layering the live
+// dirty + ownership signals onto the reused reconciliation facts. Pure decisioning is delegated to the
+// contract; this only does the IO.
+async function evaluateInstance(deps, adapter, worktrees, instance, ownershipProven, nowMs) {
+    const { facts } = await gatherInstanceReconciliationFacts(deps, adapter, worktrees, instance, nowMs);
+    const worktreeDirty = await probeDirty(deps, instance.managedWorktreePath, facts.worktreeDirExists && facts.pathContained);
+    const evaluation = classifyWorkspaceHealth({
+        reconciliation: facts,
+        worktreeDirty,
+        ownershipProven,
+    });
+    return deriveWorkspaceHealthEntry({
+        workspaceId: instance.workspaceId,
+        taskId: instance.taskId,
+        lifecycleState: instance.lifecycleState,
+        health: instance.health,
+        evaluation,
+        ...(instance.lastVerifiedAt !== undefined ? { lastVerifiedAt: instance.lastVerifiedAt } : {}),
+    });
+}
+// Detects orphaned managed worktrees for one repository: directories under `<managedRoot>/<repoId>`
+// that no persisted instance references. Each candidate is realpath-contained before it is reported,
+// and its live cleanup-eligibility is evaluated (owned + contained + clean; orphans hold no lock).
+async function detectOrphans(deps, repositoryId, knownPaths, ownershipProven) {
+    const repoDir = join(deps.managedRoot, repositoryId);
+    if (!existsSync(repoDir))
+        return [];
+    let leaves;
+    try {
+        leaves = readdirSync(repoDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const leaf of leaves) {
+        const candidate = join(repoDir, leaf);
+        if (knownPaths.has(candidate))
+            continue;
+        const contained = isManagedTargetContained(deps.managedRoot, candidate);
+        if (!contained) {
+            // An uncontained directory (e.g. a symlink escape) is reported as an orphan but NEVER
+            // cleanup-eligible — the live safety gate refuses it.
+            entries.push(deriveOrphanWorktreeHealthEntry({
+                orphanId: deriveOrphanId(repositoryId, leaf),
+                cleanupEligible: false,
+            }));
+            continue;
+        }
+        const worktreeDirty = await probeDirty(deps, candidate, true);
+        const decision = evaluateWorkspaceCleanupSafety({
+            lifecycleState: "abandoned",
+            hasRecord: false,
+            pathContained: true,
+            ownershipProven,
+            worktreeDirty,
+            lockLive: false,
+        });
+        entries.push(deriveOrphanWorktreeHealthEntry({
+            orphanId: deriveOrphanId(repositoryId, leaf),
+            cleanupEligible: decision.allowed,
+        }));
+    }
+    return entries;
+}
+// Groups the in-scope instances by repository root so each repository's worktree list is fetched once.
+function groupByRepositoryRoot(instances) {
+    const byRepo = new Map();
+    for (const instance of instances) {
+        const group = byRepo.get(instance.repositoryRoot) ?? [];
+        group.push(instance);
+        byRepo.set(instance.repositoryRoot, group);
+    }
+    return byRepo;
+}
+function instancesFor(deps, repositoryRoot) {
+    if (repositoryRoot === undefined || repositoryRoot.length === 0)
+        return deps.store.listAll();
+    return deps.store.listByRepository(deriveRepositoryId(repositoryRoot));
+}
+async function reportImpl(deps, repositoryRoot) {
+    const instances = instancesFor(deps, repositoryRoot);
+    const ownershipProven = isManagedRootOwned(deps.managedRoot);
+    const byRepo = groupByRepositoryRoot(instances);
+    const entries = [];
+    const seenRepoIds = new Set();
+    for (const [root, group] of byRepo) {
+        const repositoryId = deriveRepositoryId(root);
+        seenRepoIds.add(repositoryId);
+        const adapter = deps.createAdapter(detectWorkspaceAt(root));
+        const worktrees = await adapter.listWorktrees();
+        const knownPaths = new Set(group.map((instance) => instance.managedWorktreePath));
+        for (const instance of group) {
+            entries.push(await evaluateInstance(deps, adapter, worktrees, instance, ownershipProven, deps.now()));
+        }
+        entries.push(...(await detectOrphans(deps, repositoryId, knownPaths, ownershipProven)));
+    }
+    // A scoped report whose repository has no persisted instances still surfaces its orphans.
+    if (repositoryRoot !== undefined && repositoryRoot.length > 0) {
+        const repositoryId = deriveRepositoryId(repositoryRoot);
+        if (!seenRepoIds.has(repositoryId)) {
+            entries.push(...(await detectOrphans(deps, repositoryId, new Set(), ownershipProven)));
+        }
+    }
+    return {
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        generatedAt: isoFrom(deps.now()),
+        entries,
+    };
+}
+export function createWorkspaceHealthService(deps) {
+    return {
+        report: (repositoryRoot) => reportImpl(deps, repositoryRoot),
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { WorkspaceLifecycleService, WorkspaceLifecycleServiceDeps } from "./types.js";
+export declare function createWorkspaceLifecycleService(deps: WorkspaceLifecycleServiceDeps): WorkspaceLifecycleService;
+//# sourceMappingURL=lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/task-workspace/lifecycle.ts"],"names":[],"mappings":"AA0CA,OAAO,KAAK,EAKV,yBAAyB,EACzB,6BAA6B,EAC9B,MAAM,YAAY,CAAC;AAyRpB,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,6BAA6B,GAClC,yBAAyB,CAyB3B"}

package/dist/task-workspace/lifecycle.js

@@ -0,0 +1,248 @@
+// Active task-workspace binding + lifecycle-action service (Issue #446, Epic #443).
+//
+// This is the cross-surface binding AUTHORITY. It owns the singleton active pointer (active-store.ts)
+// and the operator-driven switch / pause / resume / handoff-preparation actions. The WorkspaceBinding
+// every surface consumes is DERIVED from the active instance (binding.ts) — there is one derivation,
+// never a recomputed second copy of the root, so a switch atomically retargets all surfaces.
+//
+// It REUSES #445 and does NOT duplicate any worktree / lock / transition engine (SC1):
+//   - setActive / resume delegate the lifecycle walk into `active` to provisioning.activate(), which
+//     already gates validateTaskWorkspaceTransition, resolves preconditions, persists, emits evidence,
+//     and rejects drift; this service only then records the active pointer.
+//   - pause / prepareHandoff load the instance, resolve the #444 TaskWorkspaceTransitionContext,
+//     gate validateTaskWorkspaceTransition, persist through the SAME store, and append the SAME
+//     content-free lifecycle evidence.
+//
+// The worktree-clean precondition is derived from the persisted instance's drift markers
+// (uncommitted-changes ⇒ dirty) — the SAME signal the switcher renders as the dirty badge — so the
+// service stays within the deliberately narrow #445 worktree adapter (no `git status` subcommand, no
+// adapter allowlist widening). Live re-verification of cleanliness is #447/#448's responsibility.
+import { TASK_WORKSPACE_SCHEMA_VERSION, validateTaskWorkspaceTransition, } from "@oscharko-dev/keiko-contracts";
+import { buildBinding } from "./binding.js";
+import { assertSafeFieldValue } from "./field-safety.js";
+import { deriveManagedWorktreePath, deriveRepositoryId } from "./naming.js";
+import { isManagedTargetContained, managedTargetExists } from "./managed-root.js";
+import { lockIsLive, resolveLockTtl } from "./locks.js";
+import { activePointerKey, 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();
+}
+function emit(ctx, input) {
+    const event = buildWorkspaceEvent({
+        eventId: ctx.deps.newId(),
+        workspaceId: input.instance.workspaceId,
+        taskId: input.instance.taskId,
+        type: input.type,
+        at: isoFrom(input.nowMs),
+        correlationId: input.instance.workspaceId,
+        fromState: input.fromState,
+        toState: input.instance.lifecycleState,
+    });
+    appendWorkspaceLifecycleEvidence(ctx.deps.evidenceStore, {
+        kind: WORKSPACE_LIFECYCLE_EVIDENCE_KIND,
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        recordedAt: input.nowMs,
+        operation: input.operation,
+        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 assertBindableManagedPath(ctx, instance) {
+    const expected = deriveManagedWorktreePath({
+        managedRoot: ctx.deps.managedRoot,
+        repositoryId: instance.repositoryId,
+        workspaceId: instance.workspaceId,
+    });
+    if (instance.managedWorktreePath !== expected ||
+        !isManagedTargetContained(ctx.deps.managedRoot, instance.managedWorktreePath)) {
+        throw new TaskWorkspaceError("POINTER_DRIFT", "persisted managed worktree path is not bindable");
+    }
+}
+function canExposeBinding(ctx, instance) {
+    if (instance.lifecycleState !== "active" && instance.lifecycleState !== "handoff-ready") {
+        return false;
+    }
+    try {
+        assertBindableManagedPath(ctx, instance);
+    }
+    catch {
+        return false;
+    }
+    return managedTargetExists(instance.managedWorktreePath);
+}
+// Resolves the #444 transition context for a direct (pause / handoff) action. The actor holds the
+// mutation lock by construction unless ANOTHER actor holds a live lock (then it is contention, not a
+// transition rejection). worktree-clean is the persisted drift signal; path-contained is the managed
+// worktree still being present on disk.
+function resolveTransitionContext(ctx, instance, requestedBy, nowMs) {
+    if (lockIsLive(instance.lock, nowMs, ctx.lockTtlMs) && instance.lock?.owner !== requestedBy) {
+        throw new TaskWorkspaceError("LOCK_CONTENTION", "workspace is locked by another actor");
+    }
+    return {
+        lockHeldByActor: true,
+        pathContained: isManagedTargetContained(ctx.deps.managedRoot, instance.managedWorktreePath) &&
+            managedTargetExists(instance.managedWorktreePath),
+        worktreeClean: !instance.driftMarkers.includes("uncommitted-changes"),
+        branchReady: true,
+        providerReady: false,
+        operatorApproved: false,
+    };
+}
+function runDirectTransition(ctx, request, spec) {
+    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();
+    const context = resolveTransitionContext(ctx, instance, request.requestedBy, nowMs);
+    const validation = validateTaskWorkspaceTransition({
+        from: instance.lifecycleState,
+        to: spec.to,
+        context,
+    });
+    if (!validation.ok) {
+        throw new TaskWorkspaceError("ILLEGAL_TRANSITION", `cannot ${spec.operation} workspace from ${instance.lifecycleState}`, validation.reasons);
+    }
+    const fromState = instance.lifecycleState;
+    const persisted = ctx.deps.store.upsert({
+        ...instance,
+        lifecycleState: spec.to,
+        lock: null,
+        updatedAt: isoFrom(nowMs),
+    });
+    if (spec.clearPointerIfActive &&
+        ctx.deps.activePointerStore.get()?.workspaceId === persisted.workspaceId) {
+        ctx.deps.activePointerStore.clear();
+    }
+    emit(ctx, {
+        operation: spec.operation,
+        outcome: spec.outcome,
+        type: spec.eventType,
+        instance: persisted,
+        fromState,
+        nowMs,
+    });
+    return { instance: persisted, binding: buildBinding(persisted) };
+}
+async function setActiveImpl(ctx, request) {
+    if (!isBoundedNonEmpty(request.requestedBy)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "requestedBy is required");
+    }
+    // requestedBy is persisted as the active-pointer `setBy`; reject control/zero-width/bidi here so the
+    // operator-visible pointer can never carry a spoofed actor name.
+    assertSafeFieldValue(request.requestedBy, "requestedBy");
+    // Delegate the lifecycle walk (paused/active → active, drift + lock checks, persistence, evidence)
+    // to the #445 service. That call already serializes on the target's `ws:` key (#449, ADR-0093 D1), so
+    // we must NOT re-acquire `ws:` here — the in-process mutex is not reentrant. Only on success do we
+    // record the active pointer — the switch is atomic from the surfaces' view because the derived binding
+    // flips in one persisted step.
+    const result = await ctx.deps.provisioning.activate({
+        workspaceId: request.workspaceId,
+        // taskId "" intentionally skips activate's optional taskId cross-check — at switch time identity is
+        // the workspaceId only, and the store lookup by workspaceId is the authoritative identity gate.
+        taskId: "",
+        requestedBy: request.requestedBy,
+        acquireLock: request.acquireLock,
+    });
+    // The pointer flip is serialized per repository under the `active:` key so two concurrent switches in
+    // the same repository cannot tear the singleton pointer write. Sequenced AFTER activate (whose `ws:`
+    // lock has already drained), never nested inside it. Because `ws:` was released between activate and
+    // here, a concurrent pause/abandon/cleanup on the same workspace may have moved it out of `active`; we
+    // RE-VERIFY the live state inside the `active:` critical section before binding the singleton pointer,
+    // so the switch can never durably advertise a paused/abandoned task as active (#449 AC1, ADR-0093 D1).
+    // getById + set are synchronous here, so no flow can interleave between the check and the write.
+    const pointer = await ctx.deps.mutex.runExclusive([activePointerKey(result.instance.repositoryId)], () => {
+        const current = ctx.deps.store.getById(result.instance.workspaceId);
+        if (current?.lifecycleState !== "active") {
+            throw new TaskWorkspaceError("LOCK_CONTENTION", "workspace state changed during activation; retry");
+        }
+        assertBindableManagedPath(ctx, current);
+        return ctx.deps.activePointerStore.set({
+            workspaceId: current.workspaceId,
+            setBy: request.requestedBy,
+            atIso: isoFrom(ctx.deps.now()),
+        });
+    });
+    return { instance: result.instance, binding: result.binding, pointer };
+}
+function getActiveImpl(ctx) {
+    const pointer = ctx.deps.activePointerStore.get();
+    if (pointer === undefined)
+        return undefined;
+    const instance = ctx.deps.store.getById(pointer.workspaceId);
+    if (instance === undefined) {
+        // Defensive: a dangling pointer (instance deleted without the FK cascade firing) self-heals to
+        // unbound mode rather than reporting a phantom active workspace.
+        ctx.deps.activePointerStore.clear();
+        return undefined;
+    }
+    if (!canExposeBinding(ctx, instance)) {
+        ctx.deps.activePointerStore.clear();
+        return undefined;
+    }
+    return { instance, binding: buildBinding(instance), pointer };
+}
+function listImpl(ctx, repositoryRoot) {
+    if (!isBoundedNonEmpty(repositoryRoot)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "repository root is required");
+    }
+    return ctx.deps.store.listByRepository(deriveRepositoryId(repositoryRoot));
+}
+async function resumeImpl(ctx, request) {
+    const view = await setActiveImpl(ctx, {
+        workspaceId: request.workspaceId,
+        requestedBy: request.requestedBy,
+        acquireLock: false,
+    });
+    return { instance: view.instance, binding: view.binding };
+}
+const PAUSE_SPEC = {
+    to: "paused",
+    operation: "pause",
+    outcome: "paused",
+    eventType: "paused",
+    clearPointerIfActive: true,
+};
+const HANDOFF_SPEC = {
+    to: "handoff-ready",
+    operation: "handoff",
+    outcome: "handoff-prepared",
+    eventType: "handoff-prepared",
+    clearPointerIfActive: false,
+};
+export function createWorkspaceLifecycleService(deps) {
+    const ctx = { deps, lockTtlMs: resolveLockTtl(deps.lockTtlMs) };
+    return {
+        list: (repositoryRoot) => listImpl(ctx, repositoryRoot),
+        getActive: () => getActiveImpl(ctx),
+        setActive: (request) => setActiveImpl(ctx, request),
+        clearActive: () => {
+            deps.activePointerStore.clear();
+        },
+        // pause / handoff are direct transitions on one instance — serialized under its `ws:` key (#449,
+        // ADR-0093 D1) so they cannot race a concurrent activate/repair/cleanup of the same workspace.
+        pause: (request) => ctx.deps.mutex.runExclusive([workspaceKey(request.workspaceId)], () => runDirectTransition(ctx, request, PAUSE_SPEC)),
+        resume: (request) => resumeImpl(ctx, request),
+        prepareHandoff: (request) => ctx.deps.mutex.runExclusive([workspaceKey(request.workspaceId)], () => runDirectTransition(ctx, request, HANDOFF_SPEC)),
+    };
+}