@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/task-workspace/reconciliation.js

@@ -0,0 +1,274 @@
+// Startup reconciliation for managed task workspaces (Issue #447, Epic #443).
+//
+// This turns the durable WorkspaceInstance store (#445) and the active pointer (#446) into trustworthy
+// OPERATIONAL state after restarts, partial failures, external filesystem changes, or git worktree
+// drift. For each persisted instance it gathers content-free FACTS by IO — realpath containment of the
+// persisted path inside the managed root (a persisted path is NEVER trusted without realpath
+// verification, SC), the `.git` linked-worktree pointer state + its content-free identity, the task
+// branch presence and the worktree HEAD via the narrow #445 worktree adapter, and the lock liveness —
+// then defers ALL the decision logic to the pure #444/#447 contract classifier. The classification is
+// persisted within LEGAL lifecycle transitions (an operational workspace whose disk state is no longer
+// trustworthy is flagged `recovery-required`, never silently dropped, AC2), and one content-free
+// evidence document is appended per instance.
+//
+// It REUSES the existing subsystems and adds none: containment is delegated to the same
+// managed-root/keiko-workspace helper provisioning uses, git inspection runs through the SAME narrow
+// keiko-tools worktree adapter (no `git status`, no allowlist widening), and the durable home is the
+// SAME store. Restoration of the last active workspace is conservative — it never auto-selects among
+// ambiguous active workspaces (SC).
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { assertContainedRealPath, detectWorkspaceAt, PathEscapeError, resolveWithinWorkspace, } from "@oscharko-dev/keiko-workspace";
+import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
+import { TASK_WORKSPACE_SCHEMA_VERSION, classifyWorkspaceReconciliation, deriveReconciliationEntry, reconciliationHealth, reconciliationRequiresRecoveryFlag, resolveActiveRestoration, validateTaskWorkspaceTransition, } from "@oscharko-dev/keiko-contracts";
+import { deriveRepositoryId } from "./naming.js";
+import { lockIsLive, resolveLockTtl } from "./locks.js";
+import { appendWorkspaceLifecycleEvidence, buildWorkspaceEvent, WORKSPACE_LIFECYCLE_EVIDENCE_KIND, } from "./evidence.js";
+function isoFrom(nowMs) {
+    return new Date(nowMs).toISOString();
+}
+// Non-throwing content-free identity of a worktree's git admin dir, or undefined when the `.git`
+// linked-worktree pointer is missing/malformed. Mirrors the throwing variant in provisioning.ts but
+// returns undefined so reconciliation can classify a stale pointer instead of failing.
+function safeGitdirIdentity(worktreePath) {
+    let raw;
+    try {
+        const dotGit = join(worktreePath, ".git");
+        if (statSync(dotGit).isDirectory())
+            return undefined;
+        raw = readFileSync(dotGit, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const match = /^gitdir:\s*(.+)\s*$/mu.exec(raw);
+    if (match?.[1] === undefined || match[1].length === 0)
+        return undefined;
+    return createHash("sha256").update(match[1].trim(), "utf8").digest("hex").slice(0, 32);
+}
+// Realpath-aware containment check delegated to keiko-workspace (same engine provisioning uses). True
+// when the persisted managed path still resolves inside the managed root after symlink resolution; any
+// escape OR an unverifiable parent chain is treated conservatively as not-contained, so reconciliation
+// never trusts a persisted path it cannot prove (SC).
+function isContained(managedRoot, worktreePath) {
+    try {
+        resolveWithinWorkspace(managedRoot, worktreePath);
+        assertContainedRealPath(nodeWorkspaceFs, managedRoot, worktreePath, "managed worktree path");
+        return true;
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError)
+            return false;
+        return false;
+    }
+}
+function realpathOrSelf(target) {
+    try {
+        return realpathSync(target);
+    }
+    catch {
+        return target;
+    }
+}
+// Finds the porcelain worktree-list entry whose path resolves to the managed worktree path. Compares
+// realpaths so a symlinked managed root still matches the canonical path git reports.
+function findWorktreeEntry(worktrees, worktreePath) {
+    const target = realpathOrSelf(worktreePath);
+    return worktrees.find((entry) => realpathOrSelf(entry.path) === target);
+}
+// `actor` scopes lock ownership: in a system reconciliation pass it is undefined, so ANY live lock
+// defers (status `locked`); for a repair re-classification it is the requesting actor, so only a
+// foreign live lock defers.
+function computeLockFacts(lock, nowMs, ttlMs, actor) {
+    const lockLive = lockIsLive(lock, nowMs, ttlMs);
+    return {
+        lockPresent: lock !== null,
+        lockLive,
+        lockedByOtherActor: lockLive && (actor === undefined || lock?.owner !== actor),
+    };
+}
+// Gathers the content-free reconciliation facts for one instance.
+async function gatherFacts(ctx, adapter, worktrees, instance, nowMs, actor) {
+    const pathContained = isContained(ctx.deps.managedRoot, instance.managedWorktreePath);
+    const worktreeDirExists = pathContained && existsSync(instance.managedWorktreePath);
+    const identity = worktreeDirExists ? safeGitdirIdentity(instance.managedWorktreePath) : undefined;
+    const taskBranchPresent = worktreeDirExists
+        ? await adapter.localBranchExists(instance.taskBranch)
+        : false;
+    const entry = worktreeDirExists
+        ? findWorktreeEntry(worktrees, instance.managedWorktreePath)
+        : undefined;
+    const observedHead = entry?.head;
+    const lock = computeLockFacts(instance.lock, nowMs, ctx.lockTtlMs, actor);
+    return {
+        observedHead,
+        facts: {
+            lifecycleState: instance.lifecycleState,
+            pathContained,
+            worktreeDirExists,
+            gitPointerPresent: identity !== undefined,
+            gitdirIdentityMatches: identity !== undefined && identity === instance.gitdirIdentity,
+            taskBranchPresent,
+            headMatches: instance.lastVerifiedHead === undefined || instance.lastVerifiedHead === observedHead,
+            // Worktree cleanliness is NOT live-detected: the narrow #445 adapter has no `git status` verb and
+            // widening it would weaken the governed-mutation boundary. A previously recorded dirty signal is
+            // preserved so it still surfaces; live cleanliness is #448's responsibility.
+            uncommittedChanges: instance.driftMarkers.includes("uncommitted-changes"),
+            lockPresent: lock.lockPresent,
+            lockLive: lock.lockLive,
+            lockedByOtherActor: lock.lockedByOtherActor,
+        },
+    };
+}
+function reconcileEventType(outcome, flaggedRecovery) {
+    if (flaggedRecovery)
+        return "recovery-flagged";
+    if (outcome.driftMarkers.length > 0)
+        return "drift-detected";
+    return "health-changed";
+}
+function emitReconcileEvidence(ctx, instance, fromState, outcome, flaggedRecovery, nowMs) {
+    const event = buildWorkspaceEvent({
+        eventId: ctx.deps.newId(),
+        workspaceId: instance.workspaceId,
+        taskId: instance.taskId,
+        type: reconcileEventType(outcome, flaggedRecovery),
+        at: isoFrom(nowMs),
+        correlationId: instance.auditCorrelationId,
+        fromState,
+        toState: instance.lifecycleState,
+        health: instance.health,
+        ...(outcome.driftMarkers.length > 0 ? { driftMarkers: outcome.driftMarkers } : {}),
+    });
+    appendWorkspaceLifecycleEvidence(ctx.deps.evidenceStore, {
+        kind: WORKSPACE_LIFECYCLE_EVIDENCE_KIND,
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        recordedAt: nowMs,
+        operation: "reconcile",
+        outcome: "reconciled",
+        attempt: 1,
+        durationMs: 0,
+        worktreeCount: 0,
+        event,
+    }, ctx.deps.redactString);
+}
+// Classifies one instance against pre-fetched git state, persists the classification within a legal
+// transition, and appends evidence. Pure decision-making is delegated to the contract; this only does
+// IO + persistence.
+function reconcileWithContext(ctx, facts, observedHead, instance, nowMs) {
+    const outcome = classifyWorkspaceReconciliation(facts);
+    const health = reconciliationHealth(outcome.status);
+    const fromState = instance.lifecycleState;
+    let targetState = fromState;
+    if (reconciliationRequiresRecoveryFlag(outcome.status, fromState)) {
+        const transition = validateTaskWorkspaceTransition({
+            from: fromState,
+            to: "recovery-required",
+            context: {
+                lockHeldByActor: false,
+                pathContained: facts.pathContained,
+                worktreeClean: false,
+                branchReady: false,
+                providerReady: false,
+                operatorApproved: false,
+            },
+        });
+        if (transition.ok)
+            targetState = "recovery-required";
+    }
+    const iso = isoFrom(nowMs);
+    const persisted = ctx.deps.store.upsert({
+        ...instance,
+        lifecycleState: targetState,
+        health,
+        driftMarkers: outcome.driftMarkers,
+        recoveryHints: outcome.recoveryHints,
+        lastVerifiedAt: iso,
+        updatedAt: iso,
+        ...(outcome.status === "healthy" && observedHead !== undefined
+            ? { lastVerifiedHead: observedHead }
+            : {}),
+    });
+    emitReconcileEvidence(ctx, persisted, fromState, outcome, targetState !== fromState, nowMs);
+    return { instance: persisted, outcome };
+}
+// Gathers the content-free reconciliation facts for one instance against a PRE-FETCHED adapter +
+// worktree list, WITHOUT persisting or classifying. Exported so the #448 health service can build the
+// same WorkspaceReconciliationFacts the reconciler uses (no second containment/git engine) and then
+// layer its live dirty + ownership signals on top.
+export function gatherInstanceReconciliationFacts(deps, adapter, worktrees, instance, nowMs, actor) {
+    const ctx = { deps, lockTtlMs: resolveLockTtl(deps.lockTtlMs) };
+    return gatherFacts(ctx, adapter, worktrees, instance, nowMs, actor);
+}
+// Reconciles a SINGLE instance end to end (builds its own adapter + worktree list). Exported so the
+// repair service re-classifies an instance through the exact same fact-gathering and persistence path.
+export async function reconcileSingleInstance(deps, instance, nowMs, actor) {
+    const ctx = { deps, lockTtlMs: resolveLockTtl(deps.lockTtlMs) };
+    const adapter = deps.createAdapter(detectWorkspaceAt(instance.repositoryRoot));
+    const worktrees = await adapter.listWorktrees();
+    const { facts, observedHead } = await gatherFacts(ctx, adapter, worktrees, instance, nowMs, actor);
+    return reconcileWithContext(ctx, facts, observedHead, instance, nowMs);
+}
+function entryFromInstance(instance) {
+    return deriveReconciliationEntry({
+        workspaceId: instance.workspaceId,
+        taskId: instance.taskId,
+        lifecycleState: instance.lifecycleState,
+        health: instance.health,
+        driftMarkers: instance.driftMarkers,
+        recoveryHints: instance.recoveryHints,
+        ...(instance.lastVerifiedAt !== undefined ? { lastVerifiedAt: instance.lastVerifiedAt } : {}),
+    });
+}
+// Builds the report from a set of instances. `clearDangling` is true ONLY on the live reconcile path:
+// clearing a dangling pointer is a state mutation, so the read-only report() must never perform it (it
+// still REPORTS the `cleared-dangling` kind; the next live reconcile or getActive() self-heals it).
+function buildReport(ctx, instances, nowMs, clearDangling) {
+    const entries = instances.map(entryFromInstance);
+    const pointer = ctx.deps.activePointerStore.get();
+    const restoration = resolveActiveRestoration(pointer?.workspaceId, entries);
+    if (clearDangling && restoration.kind === "cleared-dangling") {
+        ctx.deps.activePointerStore.clear();
+    }
+    return {
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        generatedAt: isoFrom(nowMs),
+        entries,
+        activeRestoration: restoration,
+    };
+}
+function instancesFor(deps, repositoryRoot) {
+    if (repositoryRoot === undefined || repositoryRoot.length === 0)
+        return deps.store.listAll();
+    return deps.store.listByRepository(deriveRepositoryId(repositoryRoot));
+}
+// Live reconcile: group the in-scope instances by repository root so each repository's worktree list
+// is fetched once, reconcile every instance, then build the report from the freshly persisted records.
+async function reconcileImpl(ctx, repositoryRoot) {
+    const instances = instancesFor(ctx.deps, repositoryRoot);
+    const byRepo = new Map();
+    for (const instance of instances) {
+        const group = byRepo.get(instance.repositoryRoot) ?? [];
+        group.push(instance);
+        byRepo.set(instance.repositoryRoot, group);
+    }
+    const reconciled = [];
+    for (const [root, group] of byRepo) {
+        const adapter = ctx.deps.createAdapter(detectWorkspaceAt(root));
+        const worktrees = await adapter.listWorktrees();
+        for (const instance of group) {
+            const nowMs = ctx.deps.now();
+            const { facts, observedHead } = await gatherFacts(ctx, adapter, worktrees, instance, nowMs, undefined);
+            reconciled.push(reconcileWithContext(ctx, facts, observedHead, instance, nowMs).instance);
+        }
+    }
+    return buildReport(ctx, reconciled, ctx.deps.now(), true);
+}
+export function createWorkspaceReconciliationService(deps) {
+    const ctx = { deps, lockTtlMs: resolveLockTtl(deps.lockTtlMs) };
+    return {
+        report: (repositoryRoot) => buildReport(ctx, instancesFor(deps, repositoryRoot), deps.now(), false),
+        reconcile: (repositoryRoot) => reconcileImpl(ctx, repositoryRoot),
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { WorkspaceRepairService, WorkspaceRepairServiceDeps } from "./types.js";
+export declare function createWorkspaceRepairService(deps: WorkspaceRepairServiceDeps): WorkspaceRepairService;
+//# sourceMappingURL=repair.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"repair.d.ts","sourceRoot":"","sources":["../../src/task-workspace/repair.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAIV,sBAAsB,EACtB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAsXpB,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,0BAA0B,GAC/B,sBAAsB,CAMxB"}

package/dist/task-workspace/repair.js

@@ -0,0 +1,286 @@
+// Controlled repair for managed task workspaces (Issue #447, Epic #443).
+//
+// Repair is the mutating counterpart to reconciliation. The #444 `repair` operation is lock-aware and
+// operator-approval-gated, so this service NEVER mutates Git or the filesystem without (a) a fresh live
+// reconciliation establishing the workspace genuinely needs the requested recovery, (b) the requested
+// strategy being applicable to that reconciled state, and (c) explicit operator approval — and every
+// repair appends content-free evidence (SC).
+//
+// It REUSES the existing engines, adds none (SC1): the worktree-recreating strategies delegate to the
+// #445 provisioning re-materialization path (which rebuilds a missing worktree from the existing branch
+// and refreshes a stale pointer through the SAME narrow worktree adapter, with its own rollback +
+// evidence); `release-stale-lock` is a content-free store upsert clearing the lock field; and
+// `abandon-and-cleanup` is a legal lifecycle transition to `abandoned` (physical cleanup stays #448's).
+// Strategies that cannot be applied safely without a human — reattach a deleted branch, resolve a moved
+// HEAD or uncommitted work, repair a containment escape — return an `operator-required` result with NO
+// mutation.
+import { detectWorkspaceAt } from "@oscharko-dev/keiko-workspace";
+import { TASK_WORKSPACE_SCHEMA_VERSION, isLegalTaskWorkspaceTransition, isWorkspaceRecoveryStrategy, isWorkspaceRepairStrategyApplicable, reconciliationStatusFromInstance, validateTaskWorkspaceTransition, workspaceEntryOperatorActionRequired, } from "@oscharko-dev/keiko-contracts";
+import { buildBinding } from "./binding.js";
+import { TaskWorkspaceError } from "./errors.js";
+import { assertSafeFieldValue } from "./field-safety.js";
+import { lockIsLive, makeWorkspaceLock, resolveLockTtl } from "./locks.js";
+import { workspaceKey } from "./mutex.js";
+import { reconcileSingleInstance } from "./reconciliation.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 #444 `repair` operation declares requiresLock:true. The service reserves the workspace lock for
+// the requesting actor before any mutation and releases it afterwards, mirroring the #445 provisioning
+// lock lifecycle. The whole repair runs under the `ws:` in-process mutex (#449, ADR-0093 D1) so the
+// advisory check → reconcile → acquire → mutate sequence is atomic against same-process callers; the
+// advisory lock builder is the consolidated locks.ts helper.
+function makeRepairLock(ctx, owner, nowMs) {
+    return makeWorkspaceLock({
+        newId: ctx.deps.newId,
+        owner,
+        reason: "repair",
+        nowMs,
+        ttlMs: ctx.lockTtlMs,
+    });
+}
+// Releases a still-held repair lock owned by this actor. The provision/release/abandon paths already
+// persist their own terminal lock state, so this only fires when a repair errored before clearing it.
+function releaseRepairLock(ctx, workspaceId, owner) {
+    const current = ctx.deps.store.getById(workspaceId);
+    if (current?.lock?.owner === owner && current.lock.reason === "repair") {
+        ctx.deps.store.upsert({ ...current, lock: null, updatedAt: isoFrom(ctx.deps.now()) });
+    }
+}
+// The reconciliation deps are a subset of the repair deps, so the repair service re-classifies a single
+// instance through the exact same fact-gathering and persistence path reconciliation uses.
+function reconDeps(deps) {
+    return {
+        store: deps.store,
+        activePointerStore: deps.activePointerStore,
+        evidenceStore: deps.evidenceStore,
+        managedRoot: deps.managedRoot,
+        createAdapter: deps.createAdapter,
+        redactString: deps.redactString,
+        now: deps.now,
+        newId: deps.newId,
+        ...(deps.lockTtlMs !== undefined ? { lockTtlMs: deps.lockTtlMs } : {}),
+    };
+}
+function emitRepair(ctx, instance, fromState, outcome, type, nowMs) {
+    const event = buildWorkspaceEvent({
+        eventId: ctx.deps.newId(),
+        workspaceId: instance.workspaceId,
+        taskId: instance.taskId,
+        type,
+        at: isoFrom(nowMs),
+        correlationId: instance.auditCorrelationId,
+        fromState,
+        toState: instance.lifecycleState,
+        health: instance.health,
+        ...(instance.driftMarkers.length > 0 ? { driftMarkers: instance.driftMarkers } : {}),
+    });
+    appendWorkspaceLifecycleEvidence(ctx.deps.evidenceStore, {
+        kind: WORKSPACE_LIFECYCLE_EVIDENCE_KIND,
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        recordedAt: nowMs,
+        operation: "repair",
+        outcome,
+        attempt: 1,
+        durationMs: 0,
+        worktreeCount: 0,
+        event,
+    }, ctx.deps.redactString);
+}
+function resultFor(instance, strategy, applied) {
+    const status = reconciliationStatusFromInstance({
+        lifecycleState: instance.lifecycleState,
+        health: instance.health,
+        driftMarkers: instance.driftMarkers,
+    });
+    return {
+        instance,
+        binding: buildBinding(instance),
+        strategy,
+        applied,
+        outcome: applied ? "repaired" : "operator-required",
+        status,
+        driftMarkers: instance.driftMarkers,
+        operatorActionRequired: workspaceEntryOperatorActionRequired(instance.recoveryHints),
+    };
+}
+// release-stale-lock: clear the lock field (no Git/filesystem mutation, just a content-free store
+// upsert), then re-reconcile so the classification recomputes without the stale-lock marker.
+async function applyReleaseStaleLock(ctx, instance, requestedBy, nowMs) {
+    const cleared = ctx.deps.store.upsert({ ...instance, lock: null, updatedAt: isoFrom(nowMs) });
+    const reconciled = await reconcileSingleInstance(reconDeps(ctx.deps), cleared, ctx.deps.now(), requestedBy);
+    return reconciled.instance;
+}
+// abandon-and-cleanup: a legal lifecycle transition to `abandoned` (operator-approval gated). Physical
+// worktree cleanup is deferred to #448; this only records the terminal decision and clears the active
+// pointer if it referenced this workspace.
+function applyAbandon(ctx, instance, nowMs) {
+    const transition = validateTaskWorkspaceTransition({
+        from: instance.lifecycleState,
+        to: "abandoned",
+        context: {
+            lockHeldByActor: true,
+            pathContained: false,
+            worktreeClean: false,
+            branchReady: false,
+            providerReady: false,
+            operatorApproved: true,
+        },
+    });
+    if (!transition.ok) {
+        throw new TaskWorkspaceError("ILLEGAL_TRANSITION", `cannot abandon workspace from ${instance.lifecycleState}`, transition.reasons);
+    }
+    const abandoned = ctx.deps.store.upsert({
+        ...instance,
+        lifecycleState: "abandoned",
+        health: "unknown",
+        lock: null,
+        driftMarkers: [],
+        recoveryHints: [],
+        updatedAt: isoFrom(nowMs),
+    });
+    if (ctx.deps.activePointerStore.get()?.workspaceId === abandoned.workspaceId) {
+        ctx.deps.activePointerStore.clear();
+    }
+    return abandoned;
+}
+// recreate-worktree / reconcile-pointer: delegate to the #445 provisioning re-materialization path,
+// which rebuilds a missing worktree from the existing branch (or resume-completes an existing one and
+// refreshes its pointer identity), with its own rollback + evidence. Reuse, not a second git engine.
+//
+// An EXTERNALLY deleted worktree directory leaves a stale entry in git's worktree admin metadata that
+// still claims the task branch is "checked out" at the missing path, so a fresh `git worktree add`
+// would be rejected. Pruning first (an allowlisted verb on the same narrow adapter) clears only the
+// admin entries whose working directory is already gone — a still-present worktree is untouched — so
+// the subsequent re-materialization can re-attach the branch.
+async function applyProvisioningRepair(ctx, instance, requestedBy) {
+    await ctx.deps.createAdapter(detectWorkspaceAt(instance.repositoryRoot)).pruneWorktrees();
+    const result = await ctx.deps.provisioning.provision({
+        repositoryRequestPath: instance.repositoryRoot,
+        taskId: instance.taskId,
+        baseBranch: instance.baseBranch,
+        requestedBy,
+    });
+    return result.instance;
+}
+async function executeStrategy(ctx, instance, strategy, requestedBy, nowMs) {
+    switch (strategy) {
+        case "recreate-worktree":
+        case "reconcile-pointer":
+            return applyProvisioningRepair(ctx, instance, requestedBy);
+        case "release-stale-lock":
+            return applyReleaseStaleLock(ctx, instance, requestedBy, nowMs);
+        case "abandon-and-cleanup":
+            return applyAbandon(ctx, instance, nowMs);
+        default:
+            // reattach-branch / operator-repair / commit-or-stash-required never reach here (they are
+            // operator-required and short-circuit earlier); this is a defensive guard.
+            throw new TaskWorkspaceError("REPAIR_NOT_APPLICABLE", `strategy ${strategy} is not an automatic repair`);
+    }
+}
+function validateRequest(request) {
+    if (!isBoundedNonEmpty(request.workspaceId) || !isBoundedNonEmpty(request.requestedBy)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "invalid repair request");
+    }
+    // requestedBy becomes the repair advisory-lock owner; reject control/zero-width/bidi code points.
+    assertSafeFieldValue(request.requestedBy, "requestedBy");
+    if (!isWorkspaceRecoveryStrategy(request.strategy)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "unknown recovery strategy");
+    }
+    return request.strategy;
+}
+// Whether the requested strategy needs a human regardless of approval: either it is one of the
+// inherently operator-guided strategies, or reconciliation mapped its drift to an operator-required
+// hint (e.g. a deleted branch).
+function needsOperator(outcome, strategy) {
+    if (strategy === "operator-repair" ||
+        strategy === "commit-or-stash-required" ||
+        strategy === "reattach-branch") {
+        return true;
+    }
+    const hint = outcome.recoveryHints.find((candidate) => candidate.strategy === strategy);
+    return hint?.operatorActionRequired === true;
+}
+// Emits the operator-required evidence and returns the no-mutation result for a recovery that needs a
+// human (corrupt pointer, moved HEAD, uncommitted work, deleted branch).
+function reportOperatorRequired(ctx, reconciled, strategy) {
+    emitRepair(ctx, reconciled, reconciled.lifecycleState, "operator-required", "transition-rejected", ctx.deps.now());
+    return resultFor(reconciled, strategy, false);
+}
+// The authorization gates before any mutation: operator approval (the #444 `repair` operation requires
+// it), applicability of the requested strategy to the reconciled state, and — for abandon — that the
+// current lifecycle can LEGALLY reach `abandoned` (an active/provisioning workspace must be paused or
+// fail/recover first), refused cleanly as not-applicable rather than as a downstream illegal transition.
+function assertRepairAuthorized(request, reconciled, outcome, strategy) {
+    if (!request.operatorApproved) {
+        throw new TaskWorkspaceError("OPERATOR_APPROVAL_REQUIRED", "repair requires operator approval");
+    }
+    if (!isWorkspaceRepairStrategyApplicable({
+        status: outcome.status,
+        recoveryHints: outcome.recoveryHints,
+        strategy,
+    })) {
+        throw new TaskWorkspaceError("REPAIR_NOT_APPLICABLE", `strategy ${strategy} is not applicable to a ${outcome.status} workspace`);
+    }
+    if (strategy === "abandon-and-cleanup" &&
+        !isLegalTaskWorkspaceTransition(reconciled.lifecycleState, "abandoned")) {
+        throw new TaskWorkspaceError("REPAIR_NOT_APPLICABLE", `a ${reconciled.lifecycleState} workspace must be paused or flagged for recovery before it can be abandoned`);
+    }
+}
+async function repairLocked(ctx, request) {
+    const strategy = validateRequest(request);
+    const existing = ctx.deps.store.getById(request.workspaceId);
+    if (existing === undefined) {
+        throw new TaskWorkspaceError("WORKSPACE_NOT_FOUND", "workspace not found");
+    }
+    const nowMs = ctx.deps.now();
+    if (lockIsLive(existing.lock, nowMs, ctx.lockTtlMs) &&
+        existing.lock?.owner !== request.requestedBy) {
+        throw new TaskWorkspaceError("LOCK_CONTENTION", "workspace is locked by another actor");
+    }
+    // Ground truth: re-reconcile this instance live before deciding anything (the persisted state may be
+    // stale — the worktree may have been fixed or drifted further since the last pass).
+    const { instance: reconciled, outcome } = await reconcileSingleInstance(reconDeps(ctx.deps), existing, nowMs, request.requestedBy);
+    // No automatic mutation is safe: report the operator requirement without touching Git/filesystem.
+    if (needsOperator(outcome, strategy)) {
+        return reportOperatorRequired(ctx, reconciled, strategy);
+    }
+    assertRepairAuthorized(request, reconciled, outcome, strategy);
+    // Acquire the workspace lock for the requesting actor before mutating (the #444 `repair` operation is
+    // requiresLock:true). executeStrategy persists its own terminal lock state (provision clears it,
+    // release-stale-lock/abandon set it null); the finally releases the repair lock only if it is still
+    // ours — so an error mid-repair never leaves the workspace locked.
+    const fromState = reconciled.lifecycleState;
+    const locked = ctx.deps.store.upsert({
+        ...reconciled,
+        lock: makeRepairLock(ctx, request.requestedBy, nowMs),
+        updatedAt: isoFrom(nowMs),
+    });
+    try {
+        const repaired = await executeStrategy(ctx, locked, strategy, request.requestedBy, nowMs);
+        // Read back the authoritative post-repair instance (the provisioning path persists its own state).
+        const finalInstance = ctx.deps.store.getById(repaired.workspaceId) ?? repaired;
+        emitRepair(ctx, finalInstance, fromState, "repaired", "repaired", ctx.deps.now());
+        return resultFor(finalInstance, strategy, true);
+    }
+    finally {
+        releaseRepairLock(ctx, request.workspaceId, request.requestedBy);
+    }
+}
+// Serializes the whole repair (advisory check → live reconcile → lock acquire → strategy mutation) under
+// the workspace's `ws:` key (#449, ADR-0093 D1). The nested provisioning re-materialization runs under
+// the distinct `prov:` key, so there is no self-deadlock against this `ws:` hold.
+function repairImpl(ctx, request) {
+    return ctx.deps.mutex.runExclusive([workspaceKey(request.workspaceId)], () => repairLocked(ctx, request));
+}
+export function createWorkspaceRepairService(deps) {
+    const ctx = { deps, lockTtlMs: resolveLockTtl(deps.lockTtlMs) };
+    return {
+        repair: (request) => repairImpl(ctx, request),
+    };
+}

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

@@ -0,0 +1,19 @@
+import { type RouteContext, type RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+export declare function handleProvisionTaskWorkspace(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleGetTaskWorkspace(ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleActivateTaskWorkspace(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleListTaskWorkspaces(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleGetActiveTaskWorkspace(_ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handleSetActiveTaskWorkspace(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleClearActiveTaskWorkspace(_ctx: RouteContext, deps: UiHandlerDeps): RouteResult;
+export declare function handlePauseTaskWorkspace(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleResumeTaskWorkspace(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleHandoffTaskWorkspace(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleGetTaskWorkspaceReconciliation(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleReconcileTaskWorkspaces(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleRepairTaskWorkspace(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleGetTaskWorkspaceHealth(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleCleanupTaskWorkspace(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleCleanupOrphanTaskWorkspaces(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+//# sourceMappingURL=routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/task-workspace/routes.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAa,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA6OhD,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAGD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAS1F;AAGD,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAqBtB;AAgBD,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAStB;AAGD,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,GAAG,WAAW,CAIjG;AAGD,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAyBtB;AAGD,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,YAAY,EAClB,IAAI,EAAE,aAAa,GAClB,WAAW,CAKb;AA0BD,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAEtB;AAGD,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAEtB;AAGD,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAEtB;AAiBD,wBAAsB,oCAAoC,CACxD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAID,wBAAsB,6BAA6B,CACjD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAStB;AAUD,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CA2BtB;AASD,wBAAsB,4BAA4B,CAChD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAQtB;AAYD,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAID,wBAAsB,iCAAiC,CACrD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAiBtB"}