@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.151

package/dist/services/installed-flow-source.js

@@ -0,0 +1,226 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { readSetupStatus } from "./setup.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { hybridDigest, validateHybridShape } from "./hybrid-contracts.js";
+import { admitBundledFlow } from "./stage-handlers.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+const limit = 1024 * 1024;
+const flowIds = ["mb-init", "mb-upgrade", "mb-audit", "project-review"];
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("installed_flow_source_invalid", "Installed flow source is not the selected verified canon", 1, { reason, phase: "prepare", effect: "no_effect" });
+}
+function directory(target) {
+    if (!fs.lstatSync(target).isDirectory())
+        refuse("unsafe_source_directory");
+}
+function containedFile(root, logical) {
+    if (!/^[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/.test(logical)
+        || logical.split("/").some(part => part === "." || part === ".."))
+        refuse("unsafe_source_path");
+    let current = root;
+    for (const part of logical.split("/").slice(0, -1)) {
+        current = path.join(current, part);
+        directory(current);
+    }
+    return path.join(root, logical);
+}
+/** Initial RUN materialization input, not handler/engine/storage admission.
+ * Built-in memory flows live in the global canon, not the curated project pack.
+ * Existing RUNs must restore their retained bundle rather than call this reader.
+ */
+export class PreparedInstalledFlowSource {
+    sha256;
+    #home;
+    #installationSha256;
+    #flowId;
+    #descriptor;
+    #canon;
+    #blobs;
+    constructor(home, installationSha256, flowId, descriptor, canon, blobs) {
+        this.#home = home;
+        this.#installationSha256 = installationSha256;
+        this.#flowId = flowId;
+        this.#descriptor = descriptor;
+        this.#canon = canon;
+        this.#blobs = blobs;
+        this.sha256 = hybridDigest({ installation_sha256: installationSha256, canon, inventory: this.inventory() });
+        Object.freeze(this);
+    }
+    static fromInstalledRelease(home, expectedInstallationSha256, flowId) {
+        try {
+            if (!path.isAbsolute(home) || !/^[a-f0-9]{64}$/.test(expectedInstallationSha256) || !flowIds.includes(flowId))
+                refuse("invalid_selection");
+            const selected = readSetupStatus(home);
+            if (!selected.installation || selected.installation_readiness !== "installed")
+                refuse("installed_release_unavailable");
+            const installation = selected.installation;
+            if (installation.manifest_sha256 !== expectedInstallationSha256)
+                refuse("installation_selection_changed");
+            directory(installation.canon_root);
+            const roots = fs.readdirSync(installation.canon_root);
+            if (roots.length !== 1)
+                refuse("ambiguous_archive_root");
+            const canonRoot = path.join(installation.canon_root, roots[0]);
+            directory(canonRoot);
+            const dotRoot = path.join(canonRoot, ".memory-bank"), memoryRoot = fs.existsSync(dotRoot) ? dotRoot : canonRoot;
+            directory(memoryRoot);
+            const flowRoot = path.join(memoryRoot, "dd-flow");
+            directory(flowRoot);
+            const descriptorPath = `${flowId}/flow-descriptor.json`;
+            const bytes = readBoundedReleaseFile(containedFile(flowRoot, descriptorPath), limit);
+            const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+            if (validateHybridShape("flow-descriptor", value).length || value.id !== flowId || value.origin !== "canon"
+                || value.stages.length > 64)
+                refuse("invalid_descriptor");
+            const blobs = new Map([[descriptorPath, Buffer.from(bytes)]]), folded = new Map([[descriptorPath.toLowerCase(), descriptorPath]]);
+            let total = bytes.length;
+            for (const stage of value.stages)
+                for (const kind of ["instruction", "result_schema"]) {
+                    const reference = stage[kind], existing = blobs.get(reference.path);
+                    if (existing) {
+                        if (hash(existing) !== reference.sha256)
+                            refuse("conflicting_source_reference");
+                        continue;
+                    }
+                    if (folded.has(reference.path.toLowerCase()))
+                        refuse("conflicting_source_path");
+                    const content = readBoundedReleaseFile(containedFile(flowRoot, reference.path), limit);
+                    if (!content.length || (total += content.length) > 32 * limit || hash(content) !== reference.sha256)
+                        refuse("source_bytes_changed");
+                    new TextDecoder("utf-8", { fatal: true }).decode(content);
+                    if (kind === "result_schema")
+                        JSON.parse(content.toString("utf8"));
+                    folded.set(reference.path.toLowerCase(), reference.path);
+                    blobs.set(reference.path, Buffer.from(content));
+                }
+            if (isDiagnosticFlow(flowId)) {
+                const support = ["mbb/index.md", "mbb/memory-bank-structure.md", "mbb/frontmatter-standards.md", "mbb/cross-references.md", "mbb/named-deferrals-guide.md",
+                    ...fs.readdirSync(path.join(memoryRoot, "mbb/aspects")).filter(name => name.endsWith(".md")).map(name => `mbb/aspects/${name}`),
+                    "dd-flow/mb-sdlc/review/aspects.md", "dd-flow/mb-sdlc/review/critics/universal.md", "dd-flow/mb-sdlc/review/critics/architectural-harmonization.md",
+                    ...fs.readdirSync(path.join(flowRoot, "mb-audit/aspects")).filter(name => name.endsWith(".md")).map(name => `dd-flow/mb-audit/aspects/${name}`)];
+                for (const logical of support) {
+                    const content = readBoundedReleaseFile(containedFile(memoryRoot, logical), limit), name = `support/${logical}`;
+                    if (!content.length || (total += content.length) > 32 * limit || folded.has(name.toLowerCase()))
+                        refuse("invalid_support_inventory");
+                    new TextDecoder("utf-8", { fatal: true }).decode(content);
+                    folded.set(name.toLowerCase(), name);
+                    blobs.set(name, Buffer.from(content));
+                }
+                const workSchema = "schemas/diagnostic-work-result.schema.json";
+                const content = readBoundedReleaseFile(containedFile(flowRoot, workSchema), limit);
+                if (!content.length || (total += content.length) > 32 * limit || folded.has(workSchema.toLowerCase()))
+                    refuse("invalid_support_inventory");
+                JSON.parse(content.toString("utf8"));
+                blobs.set(workSchema, Buffer.from(content));
+            }
+            // Verify compressed/expanded archive identity again after collecting bytes.
+            // A coherent descriptor+prompt edit cannot become a new trusted selection.
+            const final = readSetupStatus(home);
+            if (final.installation_readiness !== "installed" || hybridDigest(final.installation) !== hybridDigest(installation))
+                refuse("source_changed_during_preparation");
+            return new PreparedInstalledFlowSource(home, expectedInstallationSha256, flowId, { path: descriptorPath, sha256: hash(bytes) }, { version: installation.manifest.canon.version, commit: installation.manifest.canon.commit, archive_sha256: installation.manifest.canon.archive.sha256 }, blobs);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "installed_flow_source_invalid")
+                throw error;
+            return refuse("source_unavailable_or_changed");
+        }
+    }
+    descriptorReference() { return { ...this.#descriptor }; }
+    installationSha256() { return this.#installationSha256; }
+    snapshot() {
+        return { schema_id: "dd-flow/installed-flow-source@1", installation_sha256: this.#installationSha256,
+            descriptor: this.descriptorReference(), canon: this.canonProvenance(),
+            blobs: [...this.#blobs].map(([logical, bytes]) => ({ path: logical, base64: bytes.toString("base64") })) };
+    }
+    /** Copied source restoration only. expectedSha256 must come from independent
+     * request custody, not from the same input. This does not verify a new release
+     * or admit its engine/storage; those remain the bootstrap owner's duties.
+     */
+    static restoreRetained(input, expectedSha256) {
+        const result = this.restoreRetainedData(input, expectedSha256);
+        try {
+            result.resolveRegisteredFlow();
+            return result;
+        }
+        catch {
+            return refuse("invalid_retained_source");
+        }
+    }
+    /** Data recovery before storage/engine admission. This cannot register a
+     * handler; productive restoration still uses restoreRetained above. */
+    static restoreRetainedData(input, expectedSha256) {
+        try {
+            if (!input || typeof input !== "object" || Array.isArray(input) || typeof expectedSha256 !== "string"
+                || !/^[a-f0-9]{64}$/.test(expectedSha256))
+                refuse("invalid_retained_source");
+            const value = input;
+            if (Object.keys(value).sort().join() !== "blobs,canon,descriptor,installation_sha256,schema_id"
+                || value.schema_id !== "dd-flow/installed-flow-source@1" || typeof value.installation_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.installation_sha256)
+                || !value.canon || Object.keys(value.canon).sort().join() !== "archive_sha256,commit,version"
+                || typeof value.canon.commit !== "string" || !/^[a-f0-9]{40}$/.test(value.canon.commit)
+                || typeof value.canon.archive_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.canon.archive_sha256)
+                || typeof value.canon.version !== "string" || !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value.canon.version)
+                || !value.descriptor || Object.keys(value.descriptor).sort().join() !== "path,sha256"
+                || !flowIds.some(id => value.descriptor.path === `${id}/flow-descriptor.json`) || typeof value.descriptor.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.descriptor.sha256)
+                || !Array.isArray(value.blobs) || value.blobs.length < 1 || value.blobs.length > 129)
+                refuse("invalid_retained_source");
+            const blobs = new Map(), folded = new Set();
+            let total = 0;
+            for (const entry of value.blobs) {
+                if (!entry || Object.keys(entry).sort().join() !== "base64,path" || typeof entry.path !== "string"
+                    || !/^[A-Za-z0-9_-][A-Za-z0-9_.-]*(\/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*$/.test(entry.path)
+                    || entry.path.split("/").some(part => part === "." || part === "..")
+                    || folded.has(entry.path.toLowerCase()) || typeof entry.base64 !== "string" || entry.base64.length > 2 * limit)
+                    refuse("invalid_retained_source");
+                const content = Buffer.from(entry.base64, "base64");
+                if (!content.length || content.length > limit || content.toString("base64") !== entry.base64
+                    || (total += content.length) > 32 * limit)
+                    refuse("invalid_retained_source");
+                new TextDecoder("utf-8", { fatal: true }).decode(content);
+                folded.add(entry.path.toLowerCase());
+                blobs.set(entry.path, content);
+            }
+            const descriptor = blobs.get(value.descriptor.path);
+            if (!descriptor || hash(descriptor) !== value.descriptor.sha256)
+                refuse("retained_source_changed");
+            const flowId = value.descriptor.path.slice(0, -"/flow-descriptor.json".length);
+            const declared = JSON.parse(descriptor.toString("utf8"));
+            if (validateHybridShape("flow-descriptor", declared).length || declared.id !== flowId || declared.origin !== "canon")
+                refuse("invalid_retained_source");
+            for (const stage of declared.stages)
+                for (const kind of ["instruction", "result_schema"]) {
+                    const reference = stage[kind], content = blobs.get(reference.path);
+                    if (!content || hash(content) !== reference.sha256)
+                        refuse("retained_source_changed");
+                }
+            const result = new PreparedInstalledFlowSource(null, value.installation_sha256, flowId, { ...value.descriptor }, { ...value.canon }, blobs);
+            if (result.sha256 !== expectedSha256)
+                refuse("retained_source_changed");
+            return result;
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "installed_flow_source_invalid")
+                throw error;
+            return refuse("invalid_retained_source");
+        }
+    }
+    canonProvenance() { return { ...this.#canon }; }
+    blobs() { return new Map([...this.#blobs].map(([logical, bytes]) => [logical, Buffer.from(bytes)])); }
+    inventory() { return [...this.#blobs].map(([logical, bytes]) => ({ path: logical, sha256: hash(bytes) })).sort((a, b) => a.path.localeCompare(b.path, "en")); }
+    /** Production handler registry only: source declarations cannot register code. */
+    resolveRegisteredFlow() { return admitBundledFlow(this.#blobs.get(this.#descriptor.path), this.#descriptor.sha256, this.#blobs); }
+    /** Initial materialization only, outside SQL writers. */
+    revalidate() {
+        if (this.#home === null) {
+            PreparedInstalledFlowSource.restoreRetained(this.snapshot(), this.sha256);
+            return;
+        }
+        if (PreparedInstalledFlowSource.fromInstalledRelease(this.#home, this.#installationSha256, this.#flowId).sha256 !== this.sha256)
+            refuse("source_changed_after_preparation");
+    }
+}

package/dist/services/lanes.js

@@ -1,6 +1,4 @@
 import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { AppError } from "../shared/errors.js";
 import { appendAudit } from "./audit.js";
@@ -8,6 +6,31 @@ import { requireProjectByRoot } from "./projects.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 const defaultTtlSeconds = 300;
 const defaultPollIntervalSeconds = 10;
+export function prepareLaneWaitTiming(input) {
+    return {
+        timeoutSeconds: normalizeNonNegativeNumber(input.timeoutSeconds, 0, "timeout"),
+        pollIntervalSeconds: normalizePositiveNumber(input.pollIntervalSeconds, defaultPollIntervalSeconds, "poll-interval")
+    };
+}
+export function prepareLaneLock(context, input, action) {
+    if (typeof input.workerId !== "string" || !input.workerId.trim())
+        throw new AppError("validation", "Lane lock requires a nonempty worker ID", 2);
+    if (["acquire", "release", "wait-acquire"].includes(action) && (typeof input.reason !== "string" || !input.reason.trim()))
+        throw new AppError("validation", "Lane lock requires a nonempty reason", 2);
+    if (input.leaseToken !== undefined && (typeof input.leaseToken !== "string" || !input.leaseToken.trim()))
+        throw new AppError("validation", "Lease token must be nonempty text", 2);
+    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    const { timeoutSeconds, pollIntervalSeconds } = prepareLaneWaitTiming(input);
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const lane = normalizeLane(input.lane);
+    const workspace = input.workspacePath !== undefined ? requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath) : undefined;
+    if (input.workspacePath === undefined && ["acquire", "wait", "wait-acquire"].includes(action))
+        throw new AppError("validation", "Lane lock requires a workspace path", 2);
+    if (action === "acquire" || action === "wait-acquire")
+        assertWorkerMayAcquireLaneLock(context, project.id, lane, input.workerId);
+    const lock = action === "heartbeat" || action === "release" ? requireOwnedActiveLock(context, project.id, lane, input.workerId, input.leaseToken) : undefined;
+    return { project, lane, ttlSeconds, timeoutSeconds, pollIntervalSeconds, lock, workspace };
+}
 export function getLaneStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     return {
@@ -23,10 +46,16 @@ export function expireProjectLaneLocks(context, projectId) {
 export function expireProjectLaneWaiters(context, projectId) {
     expireStaleWaiters(context, projectId);
 }
-export function setLaneWorkspace(context, input) {
+export function prepareLaneWorkspace(context, input) {
+    if (input.branch !== undefined && (typeof input.branch !== "string" || !input.branch.trim()))
+        throw new AppError("validation", "Expected branch must be nonempty text", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const lane = normalizeLane(input.lane);
     const workspacePath = resolveExistingPath(input.workspacePath);
+    return { project, lane, workspacePath };
+}
+export function setLaneWorkspace(context, input) {
+    const { project, lane, workspacePath } = prepareLaneWorkspace(context, input);
     const now = context.now();
     const existing = laneRecord(context, project.id, lane);
     context.db.run(`INSERT INTO lanes
@@ -69,11 +98,12 @@ export function checkLaneWorkspace(context, input) {
     };
 }
 export function acquireLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    assertWorkerMayAcquireLaneLock(context, project.id, lane, input.workerId);
-    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    const prepared = prepareLaneLock(context, input, "acquire");
+    return context.db.writeTransaction(() => acquirePreparedLaneLock(context, input, prepared));
+}
+function acquirePreparedLaneLock(context, input, prepared) {
+    const { project, lane, ttlSeconds } = prepared;
+    assertPreparedLaneLock(context, prepared, input.workerId);
     expireStaleLocks(context, project.id);
     const active = activeLaneLock(context, project.id, lane);
     if (active) {
@@ -115,14 +145,15 @@ export function acquireLaneLock(context, input) {
         ...(expired ? { expired_lock_id: expired.id } : {})
     };
 }
+function assertPreparedLaneLock(context, prepared, workerId) {
+    if (JSON.stringify(laneRecord(context, prepared.project.id, prepared.lane)) !== JSON.stringify(prepared.workspace)
+        || context.db.get("SELECT root FROM projects WHERE id = ?", [prepared.project.id])?.root !== prepared.project.root)
+        throw new AppError("lane_workspace_changed", "Lane registration changed after workspace preparation", 1);
+    assertWorkerMayAcquireLaneLock(context, prepared.project.id, prepared.lane, workerId);
+}
 export function heartbeatLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    if (input.workspacePath) {
-        requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    }
-    const lock = requireOwnedActiveLock(context, project.id, lane, input.workerId, input.leaseToken);
-    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    const { project, lock: preparedLock, ttlSeconds } = prepareLaneLock(context, input, "heartbeat");
+    const lock = preparedLock;
     const now = context.now();
     context.db.run(`UPDATE lane_locks SET heartbeat_at = ?, expires_at = ?, updated_at = ? WHERE id = ?`, [now, expiresAt(now, ttlSeconds), now, lock.id]);
     appendAudit(context, {
@@ -133,12 +164,8 @@ export function heartbeatLaneLock(context, input) {
     return { ok: true, lock: activeLaneLock(context, project.id, lock.lane) };
 }
 export function releaseLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    if (input.workspacePath) {
-        requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    }
-    const lock = requireOwnedActiveLock(context, project.id, lane, input.workerId, input.leaseToken);
+    const { project, lock: preparedLock } = prepareLaneLock(context, input, "release");
+    const lock = preparedLock;
     const now = context.now();
     context.db.run(`UPDATE lane_locks
      SET status = 'released', released_at = ?, reason = ?, updated_at = ?
@@ -152,11 +179,7 @@ export function releaseLaneLock(context, input) {
     return { ok: true, lock: laneLockById(context, lock.id) };
 }
 export async function waitForLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    const timeoutSeconds = normalizeNonNegativeNumber(input.timeoutSeconds, 0, "timeout");
-    const pollIntervalSeconds = normalizePositiveNumber(input.pollIntervalSeconds, defaultPollIntervalSeconds, "poll-interval");
+    const { project, lane, timeoutSeconds, pollIntervalSeconds } = prepareLaneLock(context, input, "wait");
     const start = Date.now();
     while (true) {
         expireStaleLocks(context, project.id);
@@ -186,13 +209,18 @@ export function getLaneWaiters(context, input) {
         }))
     };
 }
-export function cancelLaneWaiter(context, input) {
+export function prepareLaneWaiterCancellation(context, input) {
+    if (typeof input.workerId !== "string" || !input.workerId.trim())
+        throw new AppError("validation", "Lane waiter requires a nonempty worker ID", 2);
+    if (typeof input.reason !== "string" || !input.reason.trim())
+        throw new AppError("validation", "lane waiter cancel requires --reason", 2);
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const lane = normalizeLane(input.lane);
     const reason = input.reason.trim();
-    if (!reason) {
-        throw new AppError("validation", "lane waiter cancel requires --reason", 2);
-    }
+    return { project, lane, reason };
+}
+export function cancelLaneWaiter(context, input) {
+    const { project, lane, reason } = prepareLaneWaiterCancellation(context, input);
     expireStaleWaiters(context, project.id);
     const now = context.now();
     const waiter = activeLaneWaiterForWorker(context, project.id, lane, input.workerId);
@@ -245,13 +273,7 @@ export function expireLaneWaiterById(context, input) {
     return { ok: true, expired: result.changes === 1, waiter_id: input.waiterId };
 }
 export async function waitAcquireLaneLock(context, input) {
-    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
-    const lane = normalizeLane(input.lane);
-    requireMatchingLaneWorkspace(context, project.id, lane, input.workspacePath);
-    assertWorkerMayAcquireLaneLock(context, project.id, lane, input.workerId);
-    const timeoutSeconds = normalizeNonNegativeNumber(input.timeoutSeconds, 0, "timeout");
-    const pollIntervalSeconds = normalizePositiveNumber(input.pollIntervalSeconds, defaultPollIntervalSeconds, "poll-interval");
-    const ttlSeconds = normalizePositiveNumber(input.ttlSeconds, defaultTtlSeconds, "ttl");
+    const { project, lane, timeoutSeconds, pollIntervalSeconds, ttlSeconds } = prepareLaneLock(context, input, "wait-acquire");
     const startedAt = Date.now();
     const waiterDeadline = timeoutSeconds > 0 ? new Date(startedAt + timeoutSeconds * 1000).toISOString() : null;
     while (true) {
@@ -375,10 +397,9 @@ function laneWaitersForProject(context, projectId, lane) {
      LIMIT 100`, [projectId]);
 }
 function activeLaneLock(context, projectId, lane) {
-    expireStaleLocks(context, projectId);
     return context.db.get(`SELECT * FROM lane_locks
-     WHERE project_id = ? AND lane = ? AND status = 'active'
-     ORDER BY updated_at DESC, id DESC LIMIT 1`, [projectId, lane]);
+     WHERE project_id = ? AND lane = ? AND status = 'active' AND expires_at > ?
+     ORDER BY updated_at DESC, id DESC LIMIT 1`, [projectId, lane, context.now()]);
 }
 function activeLaneWaiterForWorker(context, projectId, lane, workerId) {
     return context.db.get(`SELECT * FROM lane_waiters
@@ -513,13 +534,15 @@ function ensureQueuedLaneWaiter(context, input) {
     return waiter;
 }
 function tryAcquireQueuedLaneLock(context, input) {
-    expireStaleLocks(context, input.projectId);
-    expireStaleWaiters(context, input.projectId);
-    context.db.exec("BEGIN IMMEDIATE");
-    try {
+    const prepared = prepareLaneLock(context, input, "wait-acquire");
+    if (prepared.project.id !== input.projectId || prepared.lane !== input.lane)
+        throw new AppError("lane_workspace_changed", "Lane identity changed while waiting", 1);
+    return context.db.writeTransaction(() => {
+        assertPreparedLaneLock(context, prepared, input.workerId);
+        expireStaleLocks(context, input.projectId);
+        expireStaleWaiters(context, input.projectId);
         const existingLock = activeLaneLock(context, input.projectId, input.lane);
         if (existingLock?.worker_id === input.workerId) {
-            context.db.exec("COMMIT");
             return {
                 acquired: true,
                 payload: {
@@ -537,7 +560,6 @@ function tryAcquireQueuedLaneLock(context, input) {
         }
         const latest = latestLaneWaiterForWorker(context, input.projectId, input.lane, input.workerId);
         if (latest && ["cancelled", "expired"].includes(latest.status) && latest.updated_at >= input.invocationStartedAt) {
-            context.db.exec("COMMIT");
             return {
                 acquired: false,
                 payload: {
@@ -561,14 +583,14 @@ function tryAcquireQueuedLaneLock(context, input) {
         });
         const head = firstQueuedLaneWaiter(context, input.projectId, input.lane);
         if (!existingLock && head?.id === waiter.id) {
-            const lockResult = acquireLaneLock(context, {
+            const lockResult = acquirePreparedLaneLock(context, {
                 projectRoot: input.projectRoot,
                 lane: input.lane,
                 workerId: input.workerId,
                 workspacePath: input.workspacePath,
                 ttlSeconds: input.ttlSeconds,
                 reason: input.reason
-            });
+            }, prepared);
             const now = context.now();
             context.db.run(`UPDATE lane_waiters
          SET status = 'acquired', acquired_at = ?, updated_at = ?
@@ -580,7 +602,6 @@ function tryAcquireQueuedLaneLock(context, input) {
                 reason: input.reason,
                 payload: { project_id: input.projectId, lane: input.lane, worker_id: input.workerId, waiter_id: waiter.id }
             });
-            context.db.exec("COMMIT");
             return {
                 acquired: true,
                 payload: {
@@ -597,7 +618,6 @@ function tryAcquireQueuedLaneLock(context, input) {
             };
         }
         const position = queuedWaiterPosition(context, input.projectId, input.lane, waiter.id);
-        context.db.exec("COMMIT");
         return {
             acquired: false,
             payload: {
@@ -611,18 +631,10 @@ function tryAcquireQueuedLaneLock(context, input) {
                 position
             }
         };
-    }
-    catch (error) {
-        context.db.exec("ROLLBACK");
-        throw error;
-    }
+    });
 }
 function resolveExistingPath(value) {
-    const absolute = path.resolve(value);
-    if (!fs.existsSync(absolute)) {
-        throw new AppError("not_found", `Workspace path does not exist: ${absolute}`, 1);
-    }
-    return fs.realpathSync(absolute);
+    return resolveProjectRoot(value);
 }
 function detectBranch(workspacePath) {
     const result = spawnSync("git", ["-C", workspacePath, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
@@ -635,7 +647,7 @@ function expiresAt(now, ttlSeconds) {
     return new Date(new Date(now).getTime() + ttlSeconds * 1000).toISOString();
 }
 function normalizeLane(value) {
-    const normalized = value.trim().toLowerCase();
+    const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
     if (!normalized || !/^[a-z0-9._-]+$/.test(normalized)) {
         throw new AppError("validation", "Lane name must contain only lowercase letters, numbers, dot, underscore, or hyphen", 2);
     }
@@ -643,15 +655,16 @@ function normalizeLane(value) {
 }
 function normalizePositiveNumber(value, fallback, label) {
     const normalized = value ?? fallback;
-    if (!Number.isFinite(normalized) || normalized <= 0) {
-        throw new AppError("validation", `--${label} must be a positive number`, 2);
+    if (!Number.isFinite(normalized) || normalized <= 0 ||
+        (label === "poll-interval" ? normalized * 1000 > 2 ** 31 - 1 : !Number.isFinite(new Date(Date.now() + normalized * 1000).getTime()))) {
+        throw new AppError("validation", `--${label} must be a positive number within the supported timer/date range`, 2);
     }
     return normalized;
 }
 function normalizeNonNegativeNumber(value, fallback, label) {
     const normalized = value ?? fallback;
-    if (!Number.isFinite(normalized) || normalized < 0) {
-        throw new AppError("validation", `--${label} must be zero or a positive number`, 2);
+    if (!Number.isFinite(normalized) || normalized < 0 || !Number.isFinite(new Date(Date.now() + normalized * 1000).getTime())) {
+        throw new AppError("validation", `--${label} must be zero or a positive number within the supported date range`, 2);
     }
     return normalized;
 }