@deksden-com/dd-flow-cli 0.9.0-beta.74 → 0.9.0-beta.79

package/dist/services/worktrees.js

@@ -4,7 +4,7 @@ import { spawnSync } from "node:child_process";
 import { flowContractForState } from "../domain/flow-contract.js";
 import { requireStage } from "../domain/validation.js";
 import { AppError } from "../shared/errors.js";
-import { projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
+import { canonicalPath, projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { persistProtocolState, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { requireProjectByRoot } from "./projects.js";
@@ -28,7 +28,7 @@ export function planWorktree(context, input) {
         worktrunk: inspectManagedWorktrunk(context)
     };
 }
-export function createWorktreeRecord(context, input) {
+export function prepareWorktreeCreate(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     const existing = activeWorktreeRecord(context, protocol.project_id, protocol.id);
     if (existing) {
@@ -37,17 +37,56 @@ export function createWorktreeRecord(context, input) {
             worktree_path: existing.worktree_path
         });
     }
-    const created = createManagedWorktree(context, { projectRoot: protocol.project_root, branch: input.branch, base: input.base, path: input.path });
-    recordManagedWorktree(context, { protocolId: protocol.id, projectRoot: protocol.project_root, branch: input.branch, base: input.base, created });
+    return prepareManagedWorktree({ ...input, projectRoot: protocol.project_root });
+}
+export function createWorktreeRecord(context, input, prepared = prepareWorktreeCreate(context, input)) {
+    const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
+    if (activeWorktreeRecord(context, protocol.project_id, protocol.id))
+        throw new AppError("worktree_already_exists", "Protocol already has an active worktree record", 1);
+    const created = createManagedWorktree(context, prepared, prepared);
+    recordManagedWorktree(context, { protocolId: protocol.id, projectRoot: protocol.project_root, branch: prepared.branch, base: prepared.base, created });
     return { ok: true, worktree: activeWorktreeRecord(context, protocol.project_id, protocol.id) };
 }
-/** Creates the checkout before a PRT exists. PROTOCOLIZE materializes the PRT only inside this checkout. */
-export function createManagedWorktree(context, input) {
+export function prepareManagedWorktree(input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
+    const invalid = (message) => { throw new AppError("validation", message, 2, { phase: "prepare", effect: "no_effect", recoverable: true }); };
+    for (const key of ["branch", "base", "path"])
+        if (typeof input[key] !== "string" || !input[key].trim() || input[key].includes("\0"))
+            invalid(`--${key} must be a non-empty value without NUL`);
+    const git = (args) => {
+        const result = spawnSync("git", ["-C", projectRoot, ...args], { encoding: "utf8", env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } });
+        if (result.error)
+            throw result.error;
+        return result;
+    };
+    const branch = git(["check-ref-format", "--branch", input.branch]);
+    if (input.branch.startsWith("-") || branch.status !== 0 || branch.stdout.trim() !== input.branch)
+        invalid("--branch must be a literal valid Git branch name");
+    const base = git(["rev-parse", "--verify", "--end-of-options", `${input.base}^{commit}`]);
+    if (base.status !== 0)
+        invalid("--base must resolve to an existing Git commit");
+    if (git(["show-ref", "--verify", "--quiet", `refs/heads/${input.branch}`]).status === 0)
+        invalid("--branch already exists; choose a new feature branch");
+    const destination = canonicalPath(input.path, false);
+    if (isTrackedProjectPath(canonicalPath(projectRoot), destination))
+        invalid("--path must be outside the project checkout");
+    if (fs.existsSync(destination) && (!fs.statSync(destination).isDirectory() || fs.readdirSync(destination).length))
+        invalid("--path must be an absent or empty directory");
+    let parent = path.dirname(destination);
+    while (!fs.existsSync(parent) && path.dirname(parent) !== parent)
+        parent = path.dirname(parent);
+    if (!fs.statSync(parent).isDirectory())
+        invalid("--path has a parent that is not a directory");
+    fs.accessSync(parent, fs.constants.W_OK | fs.constants.X_OK);
+    return { projectRoot, branch: input.branch, base: base.stdout.trim(), path: destination };
+}
+/** Creates the checkout before a PRT exists. PROTOCOLIZE materializes the PRT only inside this checkout. */
+export function createManagedWorktree(context, input, prepared = prepareManagedWorktree(input)) {
+    const { projectRoot } = prepared;
     const worktrunk = ensureManagedWorktrunk(context);
     // Worktrunk owns creation; the CLI supplies its project-scoped service path
     // as a one-shot config override rather than relying on a developer's user config.
-    const command = [worktrunk.bin, "-C", projectRoot, "--config-set", `worktree-path = ${JSON.stringify(path.resolve(input.path))}`, "switch", "--create", input.branch, "--base", input.base, "--no-cd", "--format=json", "-y"];
+    const command = [worktrunk.bin, "-C", projectRoot, "--config-set", `worktree-path = ${JSON.stringify(prepared.path)}`, "switch", "--create", prepared.branch, "--base", prepared.base, "--no-cd", "--format=json", "-y"];
     const result = runExternal(command);
     if (result.exit_code !== 0)
         throw new AppError("worktrunk_command_unavailable", "Worktrunk switch failed", 1, { command: sanitizeCommand(command), result });
@@ -76,14 +115,29 @@ export function recordManagedWorktree(context, input) {
     appendAudit(context, { protocolId: protocol.id, projectId: protocol.project_id, eventType: "worktree.created", payload: { protocol_id: protocol.id, feature_branch: input.branch, base: input.base, path: input.created.worktreePath } });
 }
 /** Bootstrap a just-created RUN workspace before a durable PRT exists. */
-export function bootstrapManagedWorktree(context, input) {
-    const projectRoot = resolveProjectRoot(input.projectRoot);
-    const worktreePath = path.resolve(input.worktreePath);
+export function prepareManagedWorktreeBootstrapSources(root) {
+    const projectRoot = resolveProjectRoot(root);
     const includeFile = path.join(projectRoot, ".worktreeinclude");
     const configFile = path.join(projectRoot, ".config", "wt.toml");
     if (!fs.existsSync(includeFile) || !fs.existsSync(configFile)) {
         throw new AppError("bootstrap_unavailable", "Project-owned Worktrunk bootstrap files are required", 1, { include_file: includeFile, config_file: configFile });
     }
+    for (const file of [includeFile, configFile]) {
+        if (!fs.statSync(file).isFile())
+            throw new AppError("bootstrap_unavailable", "Project-owned bootstrap inputs must be regular files", 1, { file });
+        fs.accessSync(file, fs.constants.R_OK);
+    }
+    return projectRoot;
+}
+export function prepareManagedWorktreeBootstrap(input) {
+    const projectRoot = prepareManagedWorktreeBootstrapSources(input.projectRoot);
+    const worktreePath = path.resolve(input.worktreePath);
+    if (!fs.statSync(worktreePath).isDirectory())
+        throw new AppError("bootstrap_unavailable", "Bootstrap worktree must be a directory", 1, { worktree_path: worktreePath });
+    return { projectRoot, worktreePath };
+}
+export function bootstrapManagedWorktree(context, input, prepared = prepareManagedWorktreeBootstrap(input)) {
+    const { worktreePath } = prepared;
     const worktrunk = ensureManagedWorktrunk(context);
     const commands = [
         [worktrunk.bin, "-C", worktreePath, "step", "copy-ignored", "--require-include"],
@@ -103,38 +157,30 @@ export function getWorktreeStatus(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     return { ok: true, protocol_id: protocol.id, worktree: worktreeRecord(context, protocol.project_id, protocol.id), worktrunk: inspectManagedWorktrunk(context) };
 }
-export function bootstrapWorktree(context, input) {
+export function prepareWorktreeBootstrap(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     const record = activeWorktreeRecord(context, protocol.project_id, protocol.id);
     if (!record) {
         throw new AppError("not_found", `Worktree record is not active for protocol: ${protocol.id}`, 1);
     }
-    const includeFile = path.join(protocol.project_root, ".worktreeinclude");
-    const configFile = path.join(protocol.project_root, ".config", "wt.toml");
-    if (!fs.existsSync(includeFile) || !fs.existsSync(configFile)) {
-        throw new AppError("bootstrap_unavailable", "Project-owned Worktrunk bootstrap files are required", 1, {
-            include_file: includeFile,
-            config_file: configFile,
-            next_action: "Add .worktreeinclude and .config/wt.toml before bootstrapping the workspace."
-        });
+    return { protocol, record, managed: prepareManagedWorktreeBootstrap({ projectRoot: protocol.project_root, worktreePath: record.worktree_path }) };
+}
+export function bootstrapWorktree(context, input, prepared = prepareWorktreeBootstrap(context, input)) {
+    const { protocol, record } = prepared;
+    const active = activeWorktreeRecord(context, protocol.project_id, protocol.id);
+    if (!active || active.worktree_path !== record.worktree_path)
+        throw new AppError("worktree_active", "Worktree changed after bootstrap preparation", 1);
+    let result;
+    try {
+        result = bootstrapManagedWorktree(context, prepared.managed, prepared.managed);
     }
-    const worktrunk = ensureManagedWorktrunk(context);
-    const commands = [
-        [worktrunk.bin, "-C", record.worktree_path, "step", "copy-ignored", "--require-include"],
-        [worktrunk.bin, "-C", record.worktree_path, "hook", "pre-start", "--yes"]
-    ];
-    const results = [];
-    for (const command of commands) {
-        const result = runExternal(command);
-        results.push({ command: sanitizeCommand(command), ...result });
-        if (result.exit_code !== 0) {
-            const failed = { command: sanitizeCommand(command), result, results };
-            markBootstrapFailed(context, protocol, record, failed);
-            throw new AppError("bootstrap_failed", "Project-owned Worktrunk bootstrap failed", 1, failed);
-        }
+    catch (error) {
+        if (error instanceof AppError && error.code === "bootstrap_failed")
+            markBootstrapFailed(context, protocol, record, error.details);
+        throw error;
     }
     const now = context.now();
-    const result = { commands: results, status: "succeeded" };
+    const results = result.commands;
     context.db.run(`UPDATE worktree_records
      SET bootstrap_status = 'succeeded', last_command_result_json = ?, updated_at = ?
      WHERE project_id = ? AND protocol_id = ?`, [JSON.stringify(result), now, protocol.project_id, protocol.id]);
@@ -155,7 +201,7 @@ export function bootstrapWorktree(context, input) {
     });
     return { ok: true, worktree: worktreeRecord(context, protocol.project_id, protocol.id) };
 }
-export function closeWorktree(context, input) {
+export function prepareWorktreeClose(context, input) {
     if (!["keep", "remove"].includes(input.mode)) {
         throw new AppError("validation", "--mode must be keep or remove", 2);
     }
@@ -171,6 +217,10 @@ export function closeWorktree(context, input) {
             stage: state.stage
         });
     }
+    return { protocol, record };
+}
+export function closeWorktree(context, input) {
+    const { protocol, record } = prepareWorktreeClose(context, input);
     const now = context.now();
     const nextStatus = input.mode === "keep" ? "kept" : fs.existsSync(record.worktree_path) ? "kept" : "removed";
     context.db.run(`UPDATE worktree_records SET status = ?, updated_at = ?, closed_at = ? WHERE project_id = ? AND protocol_id = ?`, [nextStatus, now, now, protocol.project_id, protocol.id]);

package/dist/storage/database.js

@@ -8,6 +8,20 @@ import { executeStoreSchema, readStoreWriterContract, registerStoreWriter } from
 const require = createRequire(import.meta.url);
 const { DatabaseSync } = require("node:sqlite");
 const resourceDatabases = new Map();
+/** Invocation authority is prepared once with the runtime schema. Native
+ * hooks must only verify this table; they never create it on the hot path. */
+export function ensureLifecycleInvocationStorage(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS lifecycle_invocations (
+      id TEXT PRIMARY KEY, scope_json TEXT NOT NULL, command TEXT NOT NULL,
+      fingerprint TEXT NOT NULL, status TEXT NOT NULL,
+      event_key TEXT UNIQUE, identity_json TEXT, deadline INTEGER, outcome_json TEXT,
+      created_at TEXT NOT NULL, updated_at TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_lifecycle_invocations_scope
+      ON lifecycle_invocations(scope_json, fingerprint, created_at);
+  `);
+}
 /** RUN authority stays in its existing store; process leases stay in runtime.sqlite. */
 export function ensureRunControlStorage(db) {
     db.execSchema(`
@@ -232,6 +246,8 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
     if (mode === "read_existing" && !exists) {
         return emptyReadOnlyDatabase(dbPath);
     }
+    if (mode === "hook" && !exists)
+        throw new AppError("hook_storage_unprepared", "Prepare the runtime store before starting native hooks", 1);
     if (!exists || mode === "migrate")
         ensureDir(ddFlowHome);
     const db = mode === "read_existing" ? new DatabaseSync(dbPath, { readOnly: true }) : new DatabaseSync(dbPath);
@@ -256,14 +272,19 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
     // Higher-level Memory Bank migrations remain explicit in services/migrations.
     if (mode !== "read_existing") {
         try {
-            const initialize = () => { migrate(db); ensureRecoveryStorage(db); };
-            const fresh = !db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get();
-            if (fresh || readStoreWriterContract(db) !== null)
-                executeStoreSchema(db, initialize, fresh);
-            else
-                initialize();
-            // This migration owns a VACUUM backup and a separate data transaction.
-            migrateSessionStorageKeys(db, dbPath);
+            const initialize = () => { migrate(db); ensureRecoveryStorage(db); ensureLifecycleInvocationStorage(db); };
+            if (mode !== "hook") {
+                const fresh = !db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get();
+                if (fresh || readStoreWriterContract(db) !== null)
+                    executeStoreSchema(db, initialize, fresh);
+                else
+                    initialize();
+                // This migration owns a VACUUM backup and a separate data transaction.
+                migrateSessionStorageKeys(db, dbPath);
+            }
+            else {
+                assertHookStoreReady(db);
+            }
         }
         catch (error) {
             db.close();
@@ -275,15 +296,88 @@ export function getDatabase(ddFlowHome, mode = "initialize") {
     db.exec("PRAGMA foreign_keys = ON");
     return databaseFacade(dbPath, mode !== "read_existing", db);
 }
+/**
+ * Hook ingress is a hot, synchronous path.  It may write receipts, but it
+ * must never perform schema migration or VACUUM while the native host waits.
+ * Startup/migration owns this contract; a missing table is an explicit
+ * preparation error instead of an implicit migration race.
+ */
+function assertHookStoreReady(db) {
+    const required = ["projects", "hook_events", "codex_session_bindings", "sessions", "flow_session_segments", "lifecycle_invocations"];
+    const missing = required.filter((table) => !db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table));
+    if (missing.length)
+        throw new AppError("hook_storage_unprepared", "Managed store is not prepared for synchronous hook admission", 1, { missing_tables: missing, next_action: "Open the runtime with a normal dd-flow command and complete migration before starting the native Session." });
+    // Table presence alone does not establish compatibility with an older home.
+    const receiptColumns = {
+        hook_events: "id, project_id, harness, provider_session_id, parent_session_id, daemon_id, session_id, agent_id, turn_id, event_name, tool_name, event_key, cwd, match_key, transcript_path, status, sanitized_summary, outcome_json, created_at",
+        lifecycle_invocations: "id, scope_json, command, fingerprint, status, event_key, identity_json, deadline, outcome_json, created_at, updated_at",
+        codex_session_bindings: "session_id, project_id, protocol_id, handshake_id, cwd, transcript_path, status, created_at, updated_at"
+    };
+    for (const [table, columns] of Object.entries(receiptColumns)) {
+        try {
+            db.prepare(`SELECT ${columns} FROM ${table} LIMIT 0`);
+        }
+        catch {
+            throw new AppError("hook_storage_unprepared", "Managed receipt schema needs preparation before native hooks start", 1, { table });
+        }
+    }
+}
 /**
  * Opens the small host-wide resource registry.  It is intentionally separate
  * from a RUN database: a process or a port can outlive the CLI client that
  * created it, while a RUN database belongs to one flow home.
  */
-export function getResourceDatabase(resourceHome) {
-    ensureDir(resourceHome);
+export function withResourceReadSnapshot(resourceHome, read) {
+    const dbPath = path.join(resourceHome, "runtime.sqlite");
+    const cached = resourceDatabases.get(dbPath);
+    if (!cached && !fs.existsSync(dbPath))
+        return read(emptyReadOnlyDatabase(dbPath));
+    const db = cached ?? new DatabaseSync(dbPath, { readOnly: true });
+    try {
+        if (!cached)
+            db.exec("PRAGMA busy_timeout = 4000; PRAGMA query_only = ON");
+        const reader = cached
+            ? { ...emptyReadOnlyDatabase(dbPath), get: cached.get, all: cached.all }
+            : databaseFacade(dbPath, false, db);
+        // SAVEPOINT also composes with an existing owner's transaction. The
+        // callback sees its uncommitted state but never receives write capability.
+        db.exec("SAVEPOINT resource_read_snapshot");
+        try {
+            const result = read(reader);
+            db.exec("RELEASE resource_read_snapshot");
+            return result;
+        }
+        catch (error) {
+            db.exec("ROLLBACK TO resource_read_snapshot");
+            db.exec("RELEASE resource_read_snapshot");
+            throw error;
+        }
+    }
+    finally {
+        if (!cached)
+            db.close?.();
+    }
+}
+export function getResourceDatabase(resourceHome, mode = "initialize") {
     const dbPath = path.join(resourceHome, "runtime.sqlite");
     const cached = resourceDatabases.get(dbPath);
+    if (mode === "read_existing") {
+        // Reuse a current transaction's view without exposing its write capability.
+        if (cached)
+            return { ...emptyReadOnlyDatabase(dbPath), get: cached.get, all: cached.all };
+        if (!fs.existsSync(dbPath))
+            return emptyReadOnlyDatabase(dbPath);
+        const db = new DatabaseSync(dbPath, { readOnly: true });
+        try {
+            db.exec("PRAGMA busy_timeout = 4000; PRAGMA query_only = ON");
+        }
+        catch (error) {
+            db.close();
+            throw error;
+        }
+        return databaseFacade(dbPath, false, db);
+    }
+    ensureDir(resourceHome);
     if (cached)
         return cached;
     const db = new DatabaseSync(dbPath);

package/dist/storage/paths.js

@@ -15,6 +15,8 @@ export function resolveProjectRoot(root) {
     if (!fs.existsSync(absolute)) {
         throw new AppError("not_found", `Project root does not exist: ${absolute}`, 1);
     }
+    if (!fs.statSync(absolute).isDirectory())
+        throw new AppError("validation", "Project root must be a directory", 2, { project_root: absolute });
     return fs.realpathSync(absolute);
 }
 /** Resolve an existing path to its filesystem identity, or normalize a future path. */
@@ -24,10 +26,16 @@ export function canonicalPath(value, mustExist = true) {
         return fs.realpathSync(absolute);
     if (mustExist)
         throw new AppError("not_found", `Path does not exist: ${absolute}`, 1, { path: absolute });
-    const parent = path.dirname(absolute);
-    if (!fs.existsSync(parent))
-        return absolute;
-    return path.join(fs.realpathSync(parent), path.basename(absolute));
+    const missing = [];
+    let parent = absolute;
+    while (!fs.existsSync(parent)) {
+        missing.unshift(path.basename(parent));
+        const next = path.dirname(parent);
+        if (next === parent)
+            return absolute;
+        parent = next;
+    }
+    return path.join(fs.realpathSync(parent), ...missing);
 }
 export function assertPathWithin(root, candidate, label = "path") {
     const canonicalRoot = canonicalPath(root);
@@ -100,6 +108,11 @@ export function stateJsonPath(projectRoot, protocolId) {
 export function planJsonPath(projectRoot, protocolId) {
     return path.join(protocolDir(projectRoot, protocolId), "plan.json");
 }
+/** Project canonical plan takes precedence over a retained workspace location. */
+export function resolveProtocolPlanPath(projectRoot, protocolId, recordedPath) {
+    const canonical = planJsonPath(projectRoot, protocolId);
+    return fs.existsSync(canonical) ? canonical : recordedPath;
+}
 export function projectHome(ddFlowHome, projectId) {
     return path.join(ddFlowHome, "projects", projectId);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.74",
+  "version": "0.9.0-beta.79",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {