@oscharko-dev/keiko-server 0.2.8 → 0.2.9

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

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