@oscharko-dev/keiko-server 0.2.7 → 0.2.9

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

@@ -0,0 +1 @@
+{"version":3,"file":"mutex.d.ts","sourceRoot":"","sources":["../../src/task-workspace/mutex.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,sBAAsB;IAKrC,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CAC7F;AAMD,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEzE;AAeD,wBAAgB,4BAA4B,IAAI,sBAAsB,CAoCrE"}

package/dist/task-workspace/mutex.js

@@ -0,0 +1,82 @@
+// In-process keyed async mutex for managed task-workspace mutations (Issue #449, Epic #443, ADR-0093 D1).
+//
+// Every mutating workspace flow is optimistic check-then-write: it reads the instance, evaluates the
+// advisory lock, `await`s a Git-adapter spawn, then `store.upsert`s. The window between the live check
+// and the persisted write is a TOCTOU gap — two concurrent `provision()` calls for the same (repo, task)
+// both pass the gates and both race `git worktree add`. This registry closes that window by SERIALIZING
+// the whole critical section within the single server process: `runExclusive(keys, fn)` queues a flow
+// behind any in-flight holder of an overlapping key and runs it only once it has exclusive access.
+//
+// It composes with — never replaces — the persisted advisory `WorkspaceLock`. The mutex grants TURN
+// ORDER (same-process serialization); the advisory lock grants OWNERSHIP (across-restart / across-actor).
+// The existing cross-actor `LOCK_CONTENTION` rejection therefore stays INSIDE the wrapped section: two
+// requests from the same process queue and run one at a time, while a request from a different actor
+// still hits the advisory check after the queue drains and is still rejected. The mutex is pure
+// in-process JavaScript: no spawn, no filesystem, no new adapter verb, no allowlist entry (SC3). On a
+// process crash it simply vanishes — nothing it protected survives either, and the durable record is the
+// persisted advisory lock + visible lifecycle state (#447 reconciliation/repair resolve any stale lock).
+// ─── key scheme ────────────────────────────────────────────────────────────────────────────────────
+// Three contended resources, three key prefixes. The canonical acquisition order is the tier order
+// below (active → ws → prov), then lexicographic, so a multi-key flow never deadlocks against another.
+export function activePointerKey(repositoryId) {
+    return `active:${repositoryId}`;
+}
+export function workspaceKey(workspaceId) {
+    return `ws:${workspaceId}`;
+}
+export function provisionKey(repositoryId, taskId) {
+    return `prov:${repositoryId}:${taskId}`;
+}
+function keyTier(key) {
+    if (key.startsWith("active:"))
+        return 0;
+    if (key.startsWith("ws:"))
+        return 1;
+    if (key.startsWith("prov:"))
+        return 2;
+    return 3;
+}
+function compareKeys(a, b) {
+    const tierDelta = keyTier(a) - keyTier(b);
+    if (tierDelta !== 0)
+        return tierDelta;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export function createWorkspaceMutexRegistry() {
+    // One tail promise per held key. The tail resolves when the current holder of that key releases. The
+    // map only holds keys with an active or queued holder; a key's entry is deleted once its chain drains,
+    // so the map can never grow unbounded.
+    const tails = new Map();
+    const runExclusive = (keys, fn) => {
+        const ordered = [...new Set(keys)].sort(compareKeys);
+        // Synchronous critical region: capture the predecessor tails of every requested key and install our
+        // release gate as their new tail in ONE uninterrupted step (no `await` here), so two concurrent
+        // callers cannot interleave their capture/install and both think they acquired the same key. The
+        // Promise executor runs synchronously, so `releaseGate` is assigned before any use (definite-assign).
+        let releaseGate;
+        const gate = new Promise((resolve) => {
+            releaseGate = resolve;
+        });
+        const predecessors = [];
+        for (const key of ordered) {
+            const prev = tails.get(key);
+            if (prev !== undefined)
+                predecessors.push(prev);
+            tails.set(key, gate);
+        }
+        return (async () => {
+            try {
+                await Promise.all(predecessors);
+                return await fn();
+            }
+            finally {
+                releaseGate();
+                for (const key of ordered) {
+                    if (tails.get(key) === gate)
+                        tails.delete(key);
+                }
+            }
+        })();
+    };
+    return { runExclusive };
+}

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

@@ -0,0 +1,15 @@
+export declare const MANAGED_ROOT_MARKER_FILENAME = ".keiko-managed-root";
+export declare function deriveRepositoryId(repositoryRoot: string): string;
+export declare function deriveWorkspaceId(input: {
+    readonly repositoryId: string;
+    readonly taskId: string;
+}): string;
+export declare function deriveTaskBranchName(input: {
+    readonly taskId: string;
+}): string;
+export declare function deriveManagedWorktreePath(input: {
+    readonly managedRoot: string;
+    readonly repositoryId: string;
+    readonly workspaceId: string;
+}): string;
+//# sourceMappingURL=naming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/task-workspace/naming.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,4BAA4B,wBAAwB,CAAC;AAQlE,wBAAgB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAEjE;AAID,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAKT;AAmBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAG/E;AAKD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GAAG,MAAM,CAET"}

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

@@ -0,0 +1,3 @@
+import type { WorkspaceProvisioningService, WorkspaceProvisioningServiceDeps } from "./types.js";
+export declare function createWorkspaceProvisioningService(deps: WorkspaceProvisioningServiceDeps): WorkspaceProvisioningService;
+//# sourceMappingURL=provisioning.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning.d.ts","sourceRoot":"","sources":["../../src/task-workspace/provisioning.ts"],"names":[],"mappings":"AAuDA,OAAO,KAAK,EAGV,4BAA4B,EAC5B,gCAAgC,EAGjC,MAAM,YAAY,CAAC;AA2qBpB,wBAAgB,kCAAkC,CAChD,IAAI,EAAE,gCAAgC,GACrC,4BAA4B,CAU9B"}

package/dist/task-workspace/provisioning.js

@@ -0,0 +1,528 @@
+// Managed task-workspace provisioning + activation service (Issue #445, Epic #443).
+//
+// This is the missing `git worktree` lifecycle AUTHORITY: it creates a dedicated task branch and a
+// managed worktree from an approved base branch, walks the #444 lifecycle (provisioning → active),
+// persists the durable WorkspaceInstance, and yields the WorkspaceBinding that Studio/editor/runtime/
+// Git-Delivery surfaces bind to (#446 consumes it). It REUSES, never duplicates: Git mutation runs
+// through the narrow keiko-tools worktree adapter (the single governed runCommand spawn boundary),
+// path containment is delegated to @oscharko-dev/keiko-workspace, and branch/commit/publish/PR/merge
+// stay owned by #470. No generic shell, no generic Git runner (SC1).
+//
+// Failure handling is deterministic and leaves a CLASSIFIED, visible state (SC4): pre-write rejections
+// (invalid base, conflict, unsafe path, existing-unmanaged, lock contention) throw BEFORE any worktree
+// or instance row is created; a failure DURING the worktree mutation transitions the persisted
+// instance to `failed`/`recovery-required`, rolls the partial worktree back, and emits the matching
+// content-free evidence.
+import { readFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { detectWorkspaceAt } from "@oscharko-dev/keiko-workspace";
+import { isSafeGitRefName } from "@oscharko-dev/keiko-tools/internal/git-mutation";
+import { TASK_WORKSPACE_SCHEMA_VERSION, validateTaskWorkspaceTransition, } from "@oscharko-dev/keiko-contracts";
+import { buildBinding } from "./binding.js";
+import { assertSafeFieldValue, containsUnsafeFieldChars } from "./field-safety.js";
+import { lockIsLive, makeWorkspaceLock, resolveLockTtl } from "./locks.js";
+import { provisionKey, workspaceKey } from "./mutex.js";
+import { deriveManagedWorktreePath, deriveRepositoryId, deriveTaskBranchName, deriveWorkspaceId, } from "./naming.js";
+import { assertManagedRootOwned, assertManagedTargetContained, ensureManagedWorktreeParent, managedTargetExists, } from "./managed-root.js";
+import { TaskWorkspaceError } from "./errors.js";
+import { appendWorkspaceLifecycleEvidence, buildWorkspaceEvent, WORKSPACE_LIFECYCLE_EVIDENCE_KIND, } from "./evidence.js";
+const MAX_FIELD_LENGTH = 512;
+const RESUMABLE_STATES = [
+    "active",
+    "paused",
+    "handoff-ready",
+];
+const COMPLETABLE_STATES = [
+    "provisioning",
+    "failed",
+    "recovery-required",
+];
+// ─── pure helpers ────────────────────────────────────────────────────────────────────────────────
+function isBoundedNonEmpty(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= MAX_FIELD_LENGTH;
+}
+function isoFrom(nowMs) {
+    return new Date(nowMs).toISOString();
+}
+function gitdirIdentity(worktreePath) {
+    let raw;
+    try {
+        const dotGit = join(worktreePath, ".git");
+        if (statSync(dotGit).isDirectory()) {
+            throw new Error("`.git` is a directory, not a linked-worktree pointer");
+        }
+        raw = readFileSync(dotGit, "utf8");
+    }
+    catch {
+        throw new TaskWorkspaceError("POINTER_DRIFT", "managed worktree git pointer is missing");
+    }
+    const match = /^gitdir:\s*(.+)\s*$/mu.exec(raw);
+    if (match?.[1] === undefined || match[1].length === 0) {
+        throw new TaskWorkspaceError("POINTER_DRIFT", "managed worktree git pointer is malformed");
+    }
+    // Content-free, stable identity of the worktree's admin dir. The raw target stays in-process.
+    return createHash("sha256").update(match[1].trim(), "utf8").digest("hex").slice(0, 32);
+}
+function assertPersistedManagedPath(ctx, instance) {
+    assertManagedTargetContained(ctx.deps.managedRoot, instance.managedWorktreePath);
+    const expected = deriveManagedWorktreePath({
+        managedRoot: ctx.deps.managedRoot,
+        repositoryId: instance.repositoryId,
+        workspaceId: instance.workspaceId,
+    });
+    if (instance.managedWorktreePath !== expected) {
+        throw new TaskWorkspaceError("POINTER_DRIFT", "persisted managed worktree path does not match its workspace identity");
+    }
+}
+// ─── lock helpers ──────────────────────────────────────────────────────────────────────────────
+// Lock liveness + the advisory-lock builder are the consolidated #449 helpers (locks.ts); this thin
+// wrapper binds the provisioning ctx's TTL so the call sites stay terse.
+function provisioningLockLive(ctx, lock, nowMs) {
+    return lockIsLive(lock, nowMs, ctx.lockTtlMs);
+}
+function makeLock(ctx, owner, reason, nowMs) {
+    return makeWorkspaceLock({ newId: ctx.deps.newId, owner, reason, nowMs, ttlMs: ctx.lockTtlMs });
+}
+// ─── evidence ───────────────────────────────────────────────────────────────────────────────────
+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.workspaceId,
+        ...(input.fromState !== undefined ? { fromState: input.fromState } : {}),
+        ...(input.toState !== undefined ? { toState: input.toState } : {}),
+        ...(input.lockId !== undefined ? { lockId: input.lockId } : {}),
+    });
+    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 emitOutcomeForCode(ctx, operation, outcome, workspaceId, taskId, nowMs) {
+    emit(ctx, { operation, outcome, type: "transition-rejected", workspaceId, taskId, nowMs });
+}
+// ─── repository resolution ─────────────────────────────────────────────────────────────────────
+function validateProvisionRequest(request) {
+    const reasons = [];
+    if (!isBoundedNonEmpty(request.repositoryRequestPath))
+        reasons.push("repository path required");
+    if (!isBoundedNonEmpty(request.taskId))
+        reasons.push("taskId required");
+    else if (containsUnsafeFieldChars(request.taskId))
+        reasons.push("taskId contains forbidden characters");
+    if (!isBoundedNonEmpty(request.requestedBy))
+        reasons.push("requestedBy required");
+    else if (containsUnsafeFieldChars(request.requestedBy)) {
+        reasons.push("requestedBy contains forbidden characters");
+    }
+    if (!isBoundedNonEmpty(request.baseBranch) || !isSafeGitRefName(request.baseBranch)) {
+        reasons.push("baseBranch must be a safe git ref name");
+    }
+    if (reasons.length > 0) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "invalid provision request", reasons);
+    }
+}
+async function resolveRepositoryContext(ctx, request) {
+    const requestWorkspace = detectWorkspaceAt(request.repositoryRequestPath);
+    const repositoryRoot = await ctx.deps.createAdapter(requestWorkspace).resolveRepositoryRoot();
+    if (repositoryRoot === undefined) {
+        throw new TaskWorkspaceError("MISSING_REPOSITORY", "path is not inside a git repository");
+    }
+    const repositoryId = deriveRepositoryId(repositoryRoot);
+    const workspaceId = deriveWorkspaceId({ repositoryId, taskId: request.taskId });
+    const repoWorkspace = repositoryRoot === requestWorkspace.root ? requestWorkspace : detectWorkspaceAt(repositoryRoot);
+    return {
+        repositoryRoot,
+        repositoryId,
+        workspaceId,
+        taskBranch: deriveTaskBranchName({ taskId: request.taskId }),
+        worktreePath: deriveManagedWorktreePath({
+            managedRoot: ctx.deps.managedRoot,
+            repositoryId,
+            workspaceId,
+        }),
+        adapter: ctx.deps.createAdapter(repoWorkspace),
+    };
+}
+// ─── instance shaping ──────────────────────────────────────────────────────────────────────────
+function freshInstance(ctx, request, existing, lock, nowMs) {
+    const iso = isoFrom(nowMs);
+    return {
+        schemaVersion: TASK_WORKSPACE_SCHEMA_VERSION,
+        workspaceId: ctx.workspaceId,
+        taskId: request.taskId,
+        repositoryId: ctx.repositoryId,
+        repositoryRoot: ctx.repositoryRoot,
+        baseBranch: request.baseBranch,
+        taskBranch: ctx.taskBranch,
+        managedWorktreePath: ctx.worktreePath,
+        gitdirIdentity: existing?.gitdirIdentity ?? ctx.workspaceId,
+        lifecycleState: "provisioning",
+        health: "unknown",
+        lock,
+        createdAt: existing?.createdAt ?? iso,
+        updatedAt: iso,
+        driftMarkers: [],
+        recoveryHints: [],
+        auditCorrelationId: existing?.auditCorrelationId ?? ctx.workspaceId,
+    };
+}
+function finalizeActive(ctx, provisioning, identity, nowMs) {
+    const transition = validateTaskWorkspaceTransition({
+        from: "provisioning",
+        to: "active",
+        context: {
+            lockHeldByActor: true,
+            pathContained: true,
+            worktreeClean: true,
+            branchReady: true,
+            providerReady: true,
+            operatorApproved: false,
+        },
+    });
+    if (!transition.ok) {
+        throw new TaskWorkspaceError("PROVISIONING_FAILED", "provisioning to active transition rejected", transition.reasons);
+    }
+    const iso = isoFrom(nowMs);
+    return ctx.deps.store.upsert({
+        ...provisioning,
+        lifecycleState: "active",
+        health: "healthy",
+        lock: null,
+        gitdirIdentity: identity,
+        lastVerifiedAt: iso,
+        updatedAt: iso,
+        driftMarkers: [],
+        recoveryHints: [],
+    });
+}
+// ─── pre-write gates ────────────────────────────────────────────────────────────────────────────
+function assertNotLocked(ctx, existing, request, nowMs) {
+    if (existing !== undefined &&
+        provisioningLockLive(ctx, existing.lock, nowMs) &&
+        existing.lock?.owner !== request.requestedBy) {
+        throw new TaskWorkspaceError("LOCK_CONTENTION", "workspace is locked by another actor");
+    }
+}
+async function assertNoTargetOrBranchConflict(ctx, existing) {
+    const ours = existing?.managedWorktreePath === ctx.worktreePath;
+    if (managedTargetExists(ctx.worktreePath)) {
+        if (!ours) {
+            throw new TaskWorkspaceError("EXISTING_UNMANAGED_PATH", "target worktree path exists and is not Keiko-managed");
+        }
+        return;
+    }
+    if (!ours && (await ctx.adapter.localBranchExists(ctx.taskBranch))) {
+        throw new TaskWorkspaceError("BRANCH_CONFLICT", "task branch already exists");
+    }
+}
+// Detects the pre-write rejections. Throws WITHOUT persisting an instance — nothing was created, so
+// there is no partial state to classify.
+async function assertProvisionable(ctx, repo, request, existing, nowMs) {
+    assertNotLocked(ctx, existing, request, nowMs);
+    if (!(await repo.adapter.refResolves(request.baseBranch))) {
+        throw new TaskWorkspaceError("INVALID_BASE_BRANCH", "base branch does not resolve");
+    }
+    await assertNoTargetOrBranchConflict(repo, existing);
+}
+// ─── worktree materialization ────────────────────────────────────────────────────────────────────
+async function materializeWorktree(repo, request) {
+    if (managedTargetExists(repo.worktreePath)) {
+        return false; // our managed worktree already present — resume-complete without re-adding
+    }
+    ensureManagedWorktreeParent(repo.worktreePath);
+    const branchExists = await repo.adapter.localBranchExists(repo.taskBranch);
+    const result = branchExists
+        ? await repo.adapter.addWorktreeForExistingBranch({
+            worktreePath: repo.worktreePath,
+            branch: repo.taskBranch,
+        })
+        : await repo.adapter.addWorktree({
+            worktreePath: repo.worktreePath,
+            taskBranch: repo.taskBranch,
+            baseRef: request.baseBranch,
+        });
+    if (!result.ok) {
+        throw new TaskWorkspaceError("PROVISIONING_FAILED", "git worktree add failed");
+    }
+    return true;
+}
+// Persists the partial-failure state visibly (SC4): the instance moves to `failed`/`recovery-required`
+// with the lock released so a retry is unblocked, and a best-effort rollback removes the half-created
+// worktree.
+async function failProvisioning(repo, ctx, provisioning, error, nowMs) {
+    const target = error.outcome === "retry-required" ? "recovery-required" : "failed";
+    try {
+        await repo.adapter.removeWorktree({ worktreePath: repo.worktreePath, force: true });
+        await repo.adapter.pruneWorktrees();
+    }
+    catch {
+        // Rollback is best-effort; the visible state plus drift markers drive #447 repair.
+    }
+    ctx.deps.store.upsert({
+        ...provisioning,
+        lifecycleState: target,
+        health: error.outcome === "retry-required" ? "drifted" : "degraded",
+        lock: null,
+        updatedAt: isoFrom(nowMs),
+        driftMarkers: error.code === "POINTER_DRIFT" ? ["pointer-stale"] : [],
+    });
+    emit(ctx, {
+        operation: "provision",
+        outcome: error.outcome,
+        type: error.code === "POINTER_DRIFT" ? "drift-detected" : "transition-rejected",
+        workspaceId: provisioning.workspaceId,
+        taskId: provisioning.taskId,
+        nowMs,
+        fromState: "provisioning",
+        toState: target,
+    });
+    throw error;
+}
+// ─── resume / drift ──────────────────────────────────────────────────────────────────────────────
+function resumeExisting(ctx, repo, existing, nowMs) {
+    assertPersistedManagedPath(ctx, existing);
+    const identity = gitdirIdentity(repo.worktreePath);
+    const refreshed = ctx.deps.store.upsert({
+        ...existing,
+        health: "healthy",
+        gitdirIdentity: identity,
+        lastVerifiedAt: isoFrom(nowMs),
+        updatedAt: isoFrom(nowMs),
+    });
+    emit(ctx, {
+        operation: "provision",
+        outcome: "resumed",
+        type: "activated",
+        workspaceId: refreshed.workspaceId,
+        taskId: refreshed.taskId,
+        nowMs,
+        toState: refreshed.lifecycleState,
+    });
+    return { instance: refreshed, binding: buildBinding(refreshed), created: false };
+}
+// An active/paused workspace whose managed worktree has vanished is drift, not a re-provision: the
+// contract forbids re-entering `provisioning`, so it transitions to `recovery-required` (a legal move)
+// and #447 owns the repair.
+function flagResumableDrift(ctx, existing, nowMs) {
+    const drifted = ctx.deps.store.upsert({
+        ...existing,
+        lifecycleState: "recovery-required",
+        health: "missing",
+        lock: null,
+        updatedAt: isoFrom(nowMs),
+        driftMarkers: ["worktree-missing"],
+    });
+    emit(ctx, {
+        operation: "provision",
+        outcome: "retry-required",
+        type: "drift-detected",
+        workspaceId: drifted.workspaceId,
+        taskId: drifted.taskId,
+        nowMs,
+        fromState: existing.lifecycleState,
+        toState: "recovery-required",
+    });
+    throw new TaskWorkspaceError("POINTER_DRIFT", "managed worktree is missing");
+}
+function reuseExistingOrUndefined(ctx, repo, existing, nowMs) {
+    if (existing === undefined)
+        return undefined;
+    if (RESUMABLE_STATES.includes(existing.lifecycleState)) {
+        return managedTargetExists(repo.worktreePath)
+            ? resumeExisting(ctx, repo, existing, nowMs)
+            : flagResumableDrift(ctx, existing, nowMs);
+    }
+    if (!COMPLETABLE_STATES.includes(existing.lifecycleState)) {
+        // Terminal state (archived/merged/abandoned/cleanup-pending): idempotent no-op, return as-is.
+        assertPersistedManagedPath(ctx, existing);
+        return { instance: existing, binding: buildBinding(existing), created: false };
+    }
+    return undefined; // COMPLETABLE: fall through to (re)provision/complete.
+}
+// ─── provision orchestration ─────────────────────────────────────────────────────────────────────
+async function runWorktreeMutation(ctx, repo, request, provisioning) {
+    let created;
+    let identity;
+    try {
+        created = await materializeWorktree(repo, request);
+        identity = gitdirIdentity(repo.worktreePath);
+    }
+    catch (error) {
+        const failure = error instanceof TaskWorkspaceError
+            ? error
+            : new TaskWorkspaceError("PROVISIONING_FAILED", "unexpected provisioning failure");
+        return failProvisioning(repo, ctx, provisioning, failure, ctx.deps.now());
+    }
+    const active = finalizeActive(ctx, provisioning, identity, ctx.deps.now());
+    emit(ctx, {
+        operation: "provision",
+        outcome: "provisioned",
+        type: "provisioned",
+        workspaceId: active.workspaceId,
+        taskId: active.taskId,
+        nowMs: ctx.deps.now(),
+        fromState: "provisioning",
+        toState: "active",
+    });
+    return { instance: active, binding: buildBinding(active), created };
+}
+// The gated provisioning critical section. Runs under the `prov:<repositoryId>:<taskId>` mutex key
+// (#449, ADR-0093 D1) so two concurrent provisions of the SAME (repo, task) serialize instead of both
+// passing the check-then-write gates and racing `git worktree add`. The advisory cross-actor
+// LOCK_CONTENTION check (assertProvisionable → assertNotLocked) stays INSIDE this section, preserving the
+// across-actor rejection while the mutex only serializes same-process callers.
+async function provisionLocked(ctx, request, repo) {
+    assertManagedRootOwned(ctx.deps.managedRoot);
+    assertManagedTargetContained(ctx.deps.managedRoot, repo.worktreePath);
+    const nowMs = ctx.deps.now();
+    const existing = ctx.deps.store.findByRepositoryAndTask(repo.repositoryId, request.taskId);
+    const reused = reuseExistingOrUndefined(ctx, repo, existing, nowMs);
+    if (reused !== undefined)
+        return reused;
+    try {
+        await assertProvisionable(ctx, repo, request, existing, nowMs);
+    }
+    catch (error) {
+        if (error instanceof TaskWorkspaceError) {
+            emitOutcomeForCode(ctx, "provision", error.outcome, repo.workspaceId, request.taskId, nowMs);
+        }
+        throw error;
+    }
+    const lock = makeLock(ctx, request.requestedBy, "provisioning", nowMs);
+    const provisioning = ctx.deps.store.upsert(freshInstance(repo, request, existing, lock, nowMs));
+    return runWorktreeMutation(ctx, repo, request, provisioning);
+}
+async function provisionImpl(ctx, request) {
+    validateProvisionRequest(request);
+    // Resolve the repository identity (read-only git-root resolution) BEFORE acquiring the key — the key
+    // is derived from (repositoryId, taskId) and serialization must cover only the mutating gated section.
+    const repo = await resolveRepositoryContext(ctx, request);
+    return ctx.deps.mutex.runExclusive([provisionKey(repo.repositoryId, request.taskId)], () => provisionLocked(ctx, request, repo));
+}
+// ─── activate orchestration ──────────────────────────────────────────────────────────────────────
+function activateActiveOrResume(instance) {
+    if (instance.lifecycleState === "active") {
+        return { next: instance, type: "activated" };
+    }
+    const transition = validateTaskWorkspaceTransition({
+        from: instance.lifecycleState,
+        to: "active",
+        context: {
+            lockHeldByActor: true,
+            pathContained: true,
+            worktreeClean: true,
+            branchReady: true,
+            providerReady: true,
+            operatorApproved: false,
+        },
+    });
+    if (!transition.ok) {
+        throw new TaskWorkspaceError("ILLEGAL_TRANSITION", "cannot resume workspace", transition.reasons);
+    }
+    return { next: { ...instance, lifecycleState: "active" }, type: "resumed" };
+}
+function assertActivatable(ctx, instance, request, nowMs) {
+    if (isBoundedNonEmpty(request.taskId) && instance.taskId !== request.taskId) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "taskId does not match workspace");
+    }
+    if (request.expectedLifecycleState !== undefined &&
+        request.expectedLifecycleState !== instance.lifecycleState) {
+        throw new TaskWorkspaceError("LOCK_CONTENTION", "workspace state changed; retry");
+    }
+    if (provisioningLockLive(ctx, instance.lock, nowMs) &&
+        instance.lock?.owner !== request.requestedBy) {
+        throw new TaskWorkspaceError("LOCK_CONTENTION", "workspace is locked by another actor");
+    }
+    if (!RESUMABLE_STATES.includes(instance.lifecycleState)) {
+        throw new TaskWorkspaceError("ILLEGAL_TRANSITION", `cannot activate from ${instance.lifecycleState}`);
+    }
+}
+function flagActivateDrift(ctx, instance, nowMs) {
+    const drifted = ctx.deps.store.upsert({
+        ...instance,
+        lifecycleState: "recovery-required",
+        health: "missing",
+        lock: null,
+        updatedAt: isoFrom(nowMs),
+        driftMarkers: ["worktree-missing"],
+    });
+    emit(ctx, {
+        operation: "activate",
+        outcome: "retry-required",
+        type: "drift-detected",
+        workspaceId: drifted.workspaceId,
+        taskId: drifted.taskId,
+        nowMs,
+        fromState: instance.lifecycleState,
+        toState: "recovery-required",
+    });
+    throw new TaskWorkspaceError("POINTER_DRIFT", "managed worktree is missing");
+}
+// The gated activation critical section, run under the `ws:<workspaceId>` mutex key (#449, ADR-0093 D1)
+// so a concurrent activate/pause/repair/cleanup of the same workspace serializes. The advisory
+// cross-actor LOCK_CONTENTION check (assertActivatable) stays INSIDE.
+function activateLocked(ctx, request) {
+    const instance = ctx.deps.store.getById(request.workspaceId);
+    if (instance === undefined) {
+        throw new TaskWorkspaceError("WORKSPACE_NOT_FOUND", "workspace not found");
+    }
+    const nowMs = ctx.deps.now();
+    assertActivatable(ctx, instance, request, nowMs);
+    assertPersistedManagedPath(ctx, instance);
+    if (!managedTargetExists(instance.managedWorktreePath)) {
+        flagActivateDrift(ctx, instance, nowMs);
+    }
+    const { next, type } = activateActiveOrResume(instance);
+    const lock = request.acquireLock ? makeLock(ctx, request.requestedBy, "activation", nowMs) : null;
+    const persisted = ctx.deps.store.upsert({
+        ...next,
+        health: "healthy",
+        lock,
+        lastVerifiedAt: isoFrom(nowMs),
+        updatedAt: isoFrom(nowMs),
+    });
+    emit(ctx, {
+        operation: "activate",
+        outcome: type === "resumed" ? "resumed" : "activated",
+        type,
+        workspaceId: persisted.workspaceId,
+        taskId: persisted.taskId,
+        nowMs,
+        ...(type === "resumed" ? { fromState: instance.lifecycleState } : {}),
+        toState: "active",
+        ...(lock !== null ? { lockId: lock.lockId } : {}),
+    });
+    return { instance: persisted, binding: buildBinding(persisted) };
+}
+function activateImpl(ctx, request) {
+    if (!isBoundedNonEmpty(request.workspaceId) || !isBoundedNonEmpty(request.requestedBy)) {
+        throw new TaskWorkspaceError("INVALID_REQUEST", "invalid activation request");
+    }
+    // requestedBy becomes the activation advisory-lock owner; a provided taskId is the cross-check key.
+    // Both flow into operator-visible state, so reject control/zero-width/bidi code points here too.
+    assertSafeFieldValue(request.requestedBy, "requestedBy");
+    if (isBoundedNonEmpty(request.taskId))
+        assertSafeFieldValue(request.taskId, "taskId");
+    return ctx.deps.mutex.runExclusive([workspaceKey(request.workspaceId)], () => activateLocked(ctx, request));
+}
+// ─── factory ─────────────────────────────────────────────────────────────────────────────────────
+export function createWorkspaceProvisioningService(deps) {
+    const ctx = { deps, lockTtlMs: resolveLockTtl(deps.lockTtlMs) };
+    return {
+        provision: (request) => provisionImpl(ctx, request),
+        activate: (request) => activateImpl(ctx, request),
+        getInstance: (workspaceId) => deps.store.getById(workspaceId),
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { GitWorktreeAdapter, WorktreeListEntry } from "@oscharko-dev/keiko-tools/internal/git-mutation";
+import { type WorkspaceInstance, type WorkspaceReconciliationFacts, type WorkspaceReconciliationOutcome } from "@oscharko-dev/keiko-contracts";
+import type { WorkspaceReconciliationService, WorkspaceReconciliationServiceDeps } from "./types.js";
+export interface ReconcileInstanceResult {
+    readonly instance: WorkspaceInstance;
+    readonly outcome: WorkspaceReconciliationOutcome;
+}
+export interface FactsAndHead {
+    readonly facts: WorkspaceReconciliationFacts;
+    readonly observedHead: string | undefined;
+}
+export declare function gatherInstanceReconciliationFacts(deps: WorkspaceReconciliationServiceDeps, adapter: GitWorktreeAdapter, worktrees: readonly WorktreeListEntry[], instance: WorkspaceInstance, nowMs: number, actor?: string): Promise<FactsAndHead>;
+export declare function reconcileSingleInstance(deps: WorkspaceReconciliationServiceDeps, instance: WorkspaceInstance, nowMs: number, actor?: string): Promise<ReconcileInstanceResult>;
+export declare function createWorkspaceReconciliationService(deps: WorkspaceReconciliationServiceDeps): WorkspaceReconciliationService;
+//# sourceMappingURL=reconciliation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reconciliation.d.ts","sourceRoot":"","sources":["../../src/task-workspace/reconciliation.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAUL,KAAK,iBAAiB,EAEtB,KAAK,4BAA4B,EACjC,KAAK,8BAA8B,EAEpC,MAAM,+BAA+B,CAAC;AAQvC,OAAO,KAAK,EACV,8BAA8B,EAC9B,kCAAkC,EACnC,MAAM,YAAY,CAAC;AAQpB,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,8BAA8B,CAAC;CAClD;AAwDD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,4BAA4B,CAAC;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAmKD,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,kCAAkC,EACxC,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,SAAS,iBAAiB,EAAE,EACvC,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,YAAY,CAAC,CAGvB;AAID,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,kCAAkC,EACxC,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,MAAM,EACb,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,uBAAuB,CAAC,CAalC;AA8ED,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,kCAAkC,GACvC,8BAA8B,CAQhC"}