@oscharko-dev/keiko-server 0.2.7 → 0.2.9

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)),
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { WorkspaceLock, WorkspaceLockReason } from "@oscharko-dev/keiko-contracts";
+export declare const DEFAULT_LOCK_TTL_MS: number;
+export declare function lockIsLive(lock: WorkspaceLock | null, nowMs: number, ttlMs: number): boolean;
+export interface MakeWorkspaceLockArgs {
+    readonly newId: () => string;
+    readonly owner: string;
+    readonly reason: WorkspaceLockReason;
+    readonly nowMs: number;
+    readonly ttlMs: number;
+}
+export declare function makeWorkspaceLock(args: MakeWorkspaceLockArgs): WorkspaceLock;
+export declare function resolveLockTtl(lockTtlMs?: number): number;
+//# sourceMappingURL=locks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../src/task-workspace/locks.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAIxF,eAAO,MAAM,mBAAmB,QAAa,CAAC;AAI9C,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQ5F;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAKD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,aAAa,CAQ5E;AAID,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD"}

package/dist/task-workspace/locks.js

@@ -0,0 +1,44 @@
+// Consolidated advisory-lock model for managed task workspaces (Issue #449, Epic #443, ADR-0093 D2).
+//
+// Before #449 the lock-liveness predicate, the default TTL, and the lock builder were copied verbatim
+// into provisioning.ts, lifecycle.ts, reconciliation.ts, cleanup.ts, and repair.ts — five places a TTL
+// or expiry-parsing fix could silently diverge. This module is the single home: the behaviour is
+// byte-for-byte the previous copies (an explicit `expiresAt` wins; otherwise the TTL since
+// `acquiredAt`; a non-finite timestamp fails closed → treated as not live), now defined once.
+//
+// The advisory `WorkspaceLock` is the ACROSS-RESTART / ACROSS-ACTOR coordination record persisted on the
+// instance row; it is checked optimistically and is NOT an intra-process serializer (that is the
+// in-process `WorkspaceMutexRegistry`, ADR-0093 D1). On a process crash a held advisory lock TTL-expires
+// here and #447 reconciliation/repair clears it.
+// The default span a provisioning/activation/mutation/repair/cleanup lock stays valid before it is
+// treated as stale. Mirrors the value the five services each previously declared.
+export const DEFAULT_LOCK_TTL_MS = 5 * 60_000;
+// Whether an advisory lock is still live at `nowMs`. An explicit expiry wins; otherwise the TTL since
+// acquisition; a non-finite timestamp fails closed (treated as not live). `null` is never live.
+export function lockIsLive(lock, nowMs, ttlMs) {
+    if (lock === null)
+        return false;
+    if (lock.expiresAt !== undefined) {
+        const expiry = Date.parse(lock.expiresAt);
+        return Number.isFinite(expiry) ? nowMs < expiry : false;
+    }
+    const acquired = Date.parse(lock.acquiredAt);
+    return Number.isFinite(acquired) ? nowMs - acquired < ttlMs : false;
+}
+// Builds an advisory lock with a content-free id, the requesting actor as owner, the reason, and an
+// explicit expiry `ttlMs` after acquisition. Generalizes the previous per-service `makeLock` /
+// `makeRepairLock` / `cleanupLock` builders over the lock reason.
+export function makeWorkspaceLock(args) {
+    return {
+        lockId: args.newId(),
+        owner: args.owner,
+        reason: args.reason,
+        acquiredAt: new Date(args.nowMs).toISOString(),
+        expiresAt: new Date(args.nowMs + args.ttlMs).toISOString(),
+    };
+}
+// Applies the single default-TTL fallback the five services each inlined as `deps.lockTtlMs ??
+// DEFAULT_LOCK_TTL_MS`, so the default lives in exactly one place.
+export function resolveLockTtl(lockTtlMs) {
+    return lockTtlMs ?? DEFAULT_LOCK_TTL_MS;
+}

package/dist/task-workspace/managed-root.d.ts

@@ -0,0 +1,7 @@
+export declare function assertManagedRootOwned(managedRoot: string): void;
+export declare function assertManagedTargetContained(managedRoot: string, worktreePath: string): void;
+export declare function ensureManagedWorktreeParent(worktreePath: string): void;
+export declare function managedTargetExists(worktreePath: string): boolean;
+export declare function isManagedRootOwned(managedRoot: string): boolean;
+export declare function isManagedTargetContained(managedRoot: string, target: string): boolean;
+//# sourceMappingURL=managed-root.d.ts.map

package/dist/task-workspace/managed-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed-root.d.ts","sourceRoot":"","sources":["../../src/task-workspace/managed-root.ts"],"names":[],"mappings":"AAkCA,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAmBhE;AAKD,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAU5F;AAID,wBAAgB,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEtE;AAID,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAEjE;AAMD,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAO/D;AAMD,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAOrF"}

package/dist/task-workspace/managed-root.js

@@ -0,0 +1,98 @@
+// Keiko-owned managed-worktree root: ownership proof + realpath containment (Issue #445, Epic #443).
+//
+// Before any worktree is written, the server must PROVE it owns the managed root (SC2) and that the
+// derived worktree path stays inside it even after symlink resolution (AC2). Ownership is proven by a
+// marker file Keiko creates with restrictive permissions; containment delegates entirely to
+// @oscharko-dev/keiko-workspace (no second containment engine, ADR-0088 D5): a lexical check followed
+// by a realpath check that walks the existing parent chain, so a symlinked ancestor that escapes the
+// root is rejected even though the leaf worktree directory does not yet exist.
+import { chmodSync, existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertContainedRealPath, PathEscapeError, resolveWithinWorkspace, } from "@oscharko-dev/keiko-workspace";
+import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
+import { MANAGED_ROOT_MARKER_FILENAME } from "./naming.js";
+import { TaskWorkspaceError } from "./errors.js";
+const MARKER_CONTENT = JSON.stringify({ keikoManagedRoot: true, schemaVersion: "1" });
+function chmodBestEffort(target, mode) {
+    if (process.platform === "win32")
+        return;
+    try {
+        chmodSync(target, mode);
+    }
+    catch {
+        // best-effort permission hardening; ownership is proven by the marker, not by perms alone.
+    }
+}
+// Creates (if absent) and proves ownership of the managed-worktree root. The marker file is the
+// ownership proof: provisioning refuses to write under a root Keiko cannot establish and mark as its
+// own (SC2). Throws a content-free UNSAFE_PATH error when ownership cannot be proven.
+export function assertManagedRootOwned(managedRoot) {
+    try {
+        mkdirSync(managedRoot, { recursive: true, mode: 0o700 });
+        chmodBestEffort(managedRoot, 0o700);
+        const markerPath = join(managedRoot, MANAGED_ROOT_MARKER_FILENAME);
+        if (!existsSync(markerPath)) {
+            writeFileSync(markerPath, MARKER_CONTENT, { mode: 0o600 });
+        }
+        chmodBestEffort(markerPath, 0o600);
+        if (!statSync(managedRoot).isDirectory() || !existsSync(markerPath)) {
+            throw new Error("marker absent after creation");
+        }
+    }
+    catch (error) {
+        if (error instanceof TaskWorkspaceError)
+            throw error;
+        throw new TaskWorkspaceError("UNSAFE_PATH", "managed worktree root ownership could not be established");
+    }
+}
+// Asserts the derived worktree path is contained inside the managed root lexically AND after realpath
+// resolution. Delegates to keiko-workspace; any escape (parent traversal, NUL, symlinked ancestor,
+// absolute outside-root target) becomes a content-free UNSAFE_PATH error.
+export function assertManagedTargetContained(managedRoot, worktreePath) {
+    try {
+        resolveWithinWorkspace(managedRoot, worktreePath);
+        assertContainedRealPath(nodeWorkspaceFs, managedRoot, worktreePath, "managed worktree path");
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError) {
+            throw new TaskWorkspaceError("UNSAFE_PATH", "worktree path escapes the managed root");
+        }
+        throw new TaskWorkspaceError("UNSAFE_PATH", "worktree path failed containment validation");
+    }
+}
+// Ensures the worktree's PARENT directory (`<managedRoot>/<repositoryId>`) exists before `git worktree
+// add`, which creates only the leaf directory. Must run AFTER containment is asserted.
+export function ensureManagedWorktreeParent(worktreePath) {
+    mkdirSync(dirname(worktreePath), { recursive: true, mode: 0o700 });
+}
+// Whether the managed worktree directory currently exists on disk. Combined with the store lookup by
+// the service to classify a target as managed (resume) vs. unmanaged (reject).
+export function managedTargetExists(worktreePath) {
+    return existsSync(worktreePath);
+}
+// Non-throwing, read-only ownership check (#448): the managed root is a directory AND Keiko's marker
+// file is present. Unlike assertManagedRootOwned it never creates the root or the marker, so it is the
+// correct gate for read-only health evaluation and for cleanup (which must REFUSE when ownership cannot
+// be proven rather than establish it). Any IO error fails closed (not owned).
+export function isManagedRootOwned(managedRoot) {
+    try {
+        const markerPath = join(managedRoot, MANAGED_ROOT_MARKER_FILENAME);
+        return statSync(managedRoot).isDirectory() && existsSync(markerPath);
+    }
+    catch {
+        return false;
+    }
+}
+// Non-throwing containment check (#448): true iff `target` resolves inside the managed root lexically
+// AND after realpath resolution. Delegates to the same keiko-workspace engine as the throwing assert
+// (no second containment engine); any escape — parent traversal, NUL, symlinked ancestor, out-of-root
+// absolute path — or an unverifiable parent chain fails closed (not contained).
+export function isManagedTargetContained(managedRoot, target) {
+    try {
+        assertManagedTargetContained(managedRoot, target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,8 @@
+export interface WorkspaceMutexRegistry {
+    readonly runExclusive: <T>(keys: readonly string[], fn: () => Promise<T> | T) => Promise<T>;
+}
+export declare function activePointerKey(repositoryId: string): string;
+export declare function workspaceKey(workspaceId: string): string;
+export declare function provisionKey(repositoryId: string, taskId: string): string;
+export declare function createWorkspaceMutexRegistry(): WorkspaceMutexRegistry;
+//# sourceMappingURL=mutex.d.ts.map