@deksden-com/dd-flow-cli 0.9.0-beta.9 → 0.9.0-beta.91

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/dist/storage/work-references.js

@@ -0,0 +1,23 @@
+import { AppError } from "../shared/errors.js";
+/** Read-only lookup; scope applies to exact IDs as well as short aliases. */
+export function resolveWorkReference(context, id, scope = {}) {
+    const clauses = ["1 = 1"];
+    const params = [];
+    if (scope.projectId) {
+        clauses.push("project_id = ?");
+        params.push(scope.projectId);
+    }
+    if (scope.runId) {
+        clauses.push("run_id = ?");
+        params.push(scope.runId);
+    }
+    const where = clauses.join(" AND ");
+    const exact = context.db.get(`SELECT * FROM works WHERE ${where} AND work_id = ?`, [...params, id]);
+    if (exact)
+        return exact;
+    const matches = /^WRK-\d{3,}$/.test(id)
+        ? context.db.all(`SELECT * FROM works WHERE ${where} AND work_id LIKE ? ORDER BY work_id`, [...params, `${id}-%`]) : [];
+    if (matches.length !== 1)
+        throw new AppError(matches.length ? "ambiguous_work_alias" : "not_found", matches.length ? "Short Work alias is ambiguous in the current RUN" : "Work is not registered in the current RUN", 1, { work_id: id, matches: matches.map(work => work.work_id) });
+    return matches[0];
+}

package/dist/storage/writer-contract.js

@@ -0,0 +1,77 @@
+import crypto from "node:crypto";
+import { AppError } from "../shared/errors.js";
+export const STORE_WRITER_VERSION = 2;
+const version = STORE_WRITER_VERSION;
+const table = "dd_flow_writer_contract";
+const quote = (name) => `"${name.replaceAll('"', '""')}"`;
+/** Publish additive schema and its writer fences in the same transaction. */
+export function executeStoreSchema(db, sql, initialize = false) {
+    const ownsTransaction = !db.isTransaction;
+    db.exec(ownsTransaction ? "BEGIN IMMEDIATE" : "SAVEPOINT dd_flow_schema_change");
+    try {
+        const protectedStore = readStoreWriterContract(db) !== null;
+        if (initialize && !protectedStore && db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%' LIMIT 1").get()) {
+            throw new AppError("store_initialization_conflict", "Another writer initialized this store; explicit migration is required", 1);
+        }
+        const before = db.prepare("PRAGMA schema_version").get();
+        if (typeof sql === "string")
+            db.exec(sql);
+        else
+            sql();
+        const after = db.prepare("PRAGMA schema_version").get();
+        if (initialize || (protectedStore && before.schema_version !== after.schema_version))
+            installStoreWriterContract(db);
+        db.exec(ownsTransaction ? "COMMIT" : "RELEASE dd_flow_schema_change");
+    }
+    catch (error) {
+        db.exec(ownsTransaction ? "ROLLBACK" : "ROLLBACK TO dd_flow_schema_change; RELEASE dd_flow_schema_change");
+        throw error;
+    }
+}
+/** Registration is connection-local and never changes historical input bytes. */
+export function registerStoreWriter(db) {
+    const current = readStoreWriterContract(db);
+    if (current !== null && current !== version)
+        throw new AppError("store_writer_incompatible", "This CLI cannot write the store's required contract", 1, { required: current, supported: version });
+    db.function("dd_flow_writer_version", () => version);
+}
+export function readStoreWriterContract(db) {
+    if (!db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = ?").get(table))
+        return null;
+    const rows = db.prepare(`SELECT id, version FROM ${table}`).all();
+    if (rows.length !== 1 || rows[0]?.id !== 1 || !Number.isSafeInteger(rows[0].version) || rows[0].version < 1)
+        throw new AppError("store_writer_contract_invalid", "Store writer contract is malformed", 1);
+    return rows[0].version;
+}
+/** Install only at an explicit migration boundary; ordinary reads never call it. */
+export function installStoreWriterContract(db) {
+    registerStoreWriter(db);
+    const ownsTransaction = !db.isTransaction;
+    if (ownsTransaction)
+        db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(`CREATE TABLE IF NOT EXISTS ${table} (id INTEGER PRIMARY KEY CHECK (id = 1), version INTEGER NOT NULL);
+      INSERT OR IGNORE INTO ${table} (id, version) VALUES (1, ${version});`);
+        if (readStoreWriterContract(db) !== version)
+            throw new AppError("store_writer_incompatible", "Store writer contract changed before migration", 1);
+        const tables = db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all();
+        for (const target of tables) {
+            const key = crypto.createHash("sha256").update(target.name).digest("hex").slice(0, 24);
+            for (const action of ["INSERT", "UPDATE", "DELETE"]) {
+                const trigger = quote(`dd_flow_writer_${key}_${action.toLowerCase()}`);
+                db.exec(`DROP TRIGGER IF EXISTS ${trigger};
+          CREATE TRIGGER ${trigger} BEFORE ${action} ON ${quote(target.name)} BEGIN
+          SELECT CASE WHEN dd_flow_writer_version() <> (SELECT version FROM ${table} WHERE id = 1)
+            OR (SELECT COUNT(*) FROM ${table}) <> 1 THEN RAISE(ABORT, 'store_writer_incompatible') END;
+        END;`);
+            }
+        }
+        if (ownsTransaction)
+            db.exec("COMMIT");
+    }
+    catch (error) {
+        if (ownsTransaction)
+            db.exec("ROLLBACK");
+        throw error;
+    }
+}

package/dist/storage/writer-migration.js

@@ -0,0 +1,102 @@
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { AppError } from "../shared/errors.js";
+import { installStoreWriterContract, readStoreWriterContract, registerStoreWriter, STORE_WRITER_VERSION } from "./writer-contract.js";
+/** Explicit one-store cutover. The caller must separately drain external owners. */
+export function migrateStoreWriter(file, backup) {
+    if (!path.isAbsolute(file) || !path.isAbsolute(backup) || file === backup || !fs.existsSync(file) || !fs.statSync(file).isFile())
+        throw new AppError("store_migration_path_invalid", "Migration requires an existing database and a new absolute backup path", 1);
+    const source = fs.realpathSync(file);
+    const destination = path.join(fs.realpathSync(path.dirname(backup)), path.basename(backup));
+    if (fs.lstatSync(file).isSymbolicLink() || [source, `${source}-wal`, `${source}-shm`, `${source}-journal`].includes(destination))
+        throw new AppError("store_migration_path_invalid", "Backup cannot alias the source database or its SQLite sidecars", 1);
+    try {
+        const existing = fs.lstatSync(backup);
+        if (!existing.isFile() || existing.isSymbolicLink())
+            throw new AppError("store_migration_path_invalid", "Backup path already exists", 1);
+        const reader = new DatabaseSync(file, { readOnly: true });
+        try {
+            const recorded = reader.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'dd_flow_writer_migrations'").get()
+                ? reader.prepare("SELECT receipt_json FROM dd_flow_writer_migrations WHERE backup_path = ?").get(destination) : null;
+            const receipt = recorded ? JSON.parse(String(recorded.receipt_json)) : null;
+            if (!receipt || receipt.database !== file || receipt.backup !== backup || receipt.writer_version !== readStoreWriterContract(reader) || receipt.backup_sha256 !== crypto.createHash("sha256").update(fs.readFileSync(backup)).digest("hex")) {
+                throw new AppError("store_migration_path_invalid", "Existing backup has no matching committed migration receipt", 1);
+            }
+            return receipt;
+        }
+        finally {
+            reader.close();
+        }
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const db = new DatabaseSync(file);
+    try {
+        db.exec("PRAGMA busy_timeout = 1000");
+        registerStoreWriter(db);
+        db.exec("BEGIN IMMEDIATE");
+        try {
+            const previous = readStoreWriterContract(db);
+            const tables = new Set(db.prepare("SELECT name FROM sqlite_schema WHERE type = 'table'").all().map(row => row.name));
+            const gates = [
+                ["managed_processes", "state IS NULL OR state NOT IN ('stopped','failed')"],
+                ["run_controllers", "status IS NULL OR status NOT IN ('completed','stop_target_reached','cancelled','superseded')"],
+                ["run_control_workers", "status IS NULL OR status NOT IN ('completed','failed','superseded')"],
+                ["work_sessions", "status IS NULL OR status NOT IN ('completed','failed','cancelled')"]
+            ];
+            for (const [table, predicate] of gates) {
+                if (tables.has(table) && db.prepare(`SELECT 1 FROM ${table} WHERE ${predicate} LIMIT 1`).get())
+                    throw new AppError("store_migration_not_drained", "Store still contains unresolved writer ownership", 1, { table });
+            }
+            // A separate reader sees committed WAL while this connection prevents new writes.
+            const reader = new DatabaseSync(file, { readOnly: true });
+            try {
+                reader.exec(`VACUUM INTO '${backup.replaceAll("'", "''")}'`);
+            }
+            finally {
+                reader.close();
+            }
+            const descriptor = fs.openSync(backup, "r");
+            try {
+                fs.fsyncSync(descriptor);
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
+            const directory = fs.openSync(path.dirname(backup), "r");
+            try {
+                fs.fsyncSync(directory);
+            }
+            finally {
+                fs.closeSync(directory);
+            }
+            const verification = new DatabaseSync(backup, { readOnly: true });
+            try {
+                const check = verification.prepare("PRAGMA integrity_check").get();
+                if (Object.values(check)[0] !== "ok" || readStoreWriterContract(verification) !== previous)
+                    throw new AppError("store_migration_backup_invalid", "Backup failed integrity or contract verification", 1);
+            }
+            finally {
+                verification.close();
+            }
+            const receipt = { database: file, backup, backup_sha256: crypto.createHash("sha256").update(fs.readFileSync(backup)).digest("hex"), previous_version: previous, writer_version: STORE_WRITER_VERSION };
+            db.exec("CREATE TABLE IF NOT EXISTS dd_flow_writer_migrations (backup_path TEXT PRIMARY KEY, receipt_json TEXT NOT NULL)");
+            db.prepare("INSERT INTO dd_flow_writer_migrations VALUES (?, ?)").run(destination, JSON.stringify(receipt));
+            installStoreWriterContract(db);
+            db.exec("COMMIT");
+            return receipt;
+        }
+        catch (error) {
+            if (db.isTransaction)
+                db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    finally {
+        db.close();
+    }
+}

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.9",
+  "version": "0.9.0-beta.91",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {
-    "dd-flow": "./dist/cli.js"
+    "dd-flow": "dist/cli.js",
+    "dd-codex": "dist/harness-runtime/bin/dd-codex.mjs",
+    "dd-zcode": "dist/harness-runtime/bin/dd-zcode.mjs",
+    "dd-grok": "dist/harness-runtime/bin/dd-grok.mjs",
+    "dd-opencode": "dist/harness-runtime/bin/dd-opencode.mjs",
+    "dd-agy": "dist/harness-runtime/bin/dd-agy.mjs",
+    "dd-droid": "dist/harness-runtime/bin/dd-droid.mjs"
   },
   "files": [
     "dist",
@@ -16,6 +22,20 @@
     "node": ">=26.0.0",
     "pnpm": ">=10.0.0"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/generate-build-info.mjs && node scripts/copy-assets.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --max-warnings=0",
+    "test": "pnpm test:release && pnpm test:integration && pnpm test:runtime-sensitive",
+    "test:release": "node --test scripts/verify-release-build.test.mjs && vitest run --pool=forks --no-file-parallelism test/publish-release.test.ts",
+    "test:integration": "vitest run --pool=forks --no-file-parallelism --exclude test/publish-release.test.ts --exclude test/run-control-worker.test.ts --exclude test/native-adapter-contracts.test.ts",
+    "test:runtime-sensitive": "vitest run --pool=forks --no-file-parallelism test/run-control-worker.test.ts test/native-adapter-contracts.test.ts",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release:candidate:pack": "node scripts/release-candidate.mjs pack",
+    "release:candidate:accept": "node scripts/release-candidate.mjs accept",
+    "release:publish": "node scripts/publish-release.mjs"
+  },
   "devDependencies": {
     "@changesets/cli": "^2.31.0",
     "@eslint/js": "^9.39.1",
@@ -34,14 +54,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT",
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json && node scripts/generate-build-info.mjs && node scripts/copy-assets.mjs",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint . --max-warnings=0",
-    "test": "vitest run",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm run build && changeset publish"
-  }
-}
+  "license": "MIT"
+}

package/tools/repair-paused-run-status.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/* global process, console */
+// Explicit repair of legacy fenced RUN projections; no migrations or process control.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { DatabaseSync } from 'node:sqlite';
+import { registerStoreWriter } from '../dist/storage/writer-contract.js';
+import { setFlowRunRecoveryPaused, completeFlowRun } from '../dist/services/runs.js';
+
+const { values } = parseArgs({ options: { home: { type: 'string' }, run: { type: 'string' }, project: { type: 'string' }, apply: { type: 'boolean', default: false }, 'cancel-abandoned': { type: 'boolean', default: false } } });
+if (!values.home || !values.run || !values.project) throw new Error('Usage: --home <runtime> --project <project-id> --run <run-id> [--apply]');
+const home = fs.realpathSync(values.home), file = path.join(home, 'db.sqlite');
+const db = new DatabaseSync(file, { readOnly: !values.apply });
+let runtimePath, original, backup, report, changed = false;
+try {
+  db.exec('PRAGMA busy_timeout=4000');
+  if (values.apply) { registerStoreWriter(db); db.exec('BEGIN IMMEDIATE'); }
+  const run = db.prepare('SELECT * FROM runs WHERE project_id=? AND id=?').get(values.project, values.run);
+  if (!run) throw new Error('RUN not found');
+  const guard = db.prepare('SELECT * FROM run_recovery_guards WHERE project_id=? AND run_id=? ORDER BY generation DESC LIMIT 1').get(values.project, values.run);
+  const cancel = values['cancel-abandoned'];
+  if (cancel) {
+    if (fs.existsSync(run.project_root)) throw new Error('Abandoned-fixture cancellation requires an absent project directory');
+    for (const table of ['works', 'sessions', 'run_controllers']) {
+      if (!db.prepare("SELECT 1 FROM sqlite_schema WHERE type='table' AND name=?").get(table)) continue;
+      if (db.prepare(`SELECT 1 FROM ${table} WHERE project_id=? AND run_id=? LIMIT 1`).get(values.project, values.run)) throw new Error('Abandoned-fixture cancellation requires no Work, Session or controller history');
+    }
+    if (guard) throw new Error('A recovery-owned RUN requires recovery reconciliation');
+  }
+  if (!cancel && !["draining", "sealed", "resuming"].includes(guard?.status)) throw new Error("Repair requires the current recovery to fence productive admission");
+  if (run.status !== 'running') {
+    report = { run_id: run.id, status: run.status, changed: false };
+  } else {
+    runtimePath = fs.realpathSync(run.runtime_path);
+    const relative = path.relative(home, runtimePath);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('Runtime file is outside the selected home');
+    original = fs.readFileSync(runtimePath);
+    if (JSON.parse(original).status !== 'running' || JSON.parse(run.index_json).status !== 'running') throw new Error('RUN projections disagree; manual review required');
+    if (values.apply) {
+      backup = `${runtimePath}.status-repair-${crypto.randomUUID()}.json`;
+      fs.writeFileSync(backup, JSON.stringify({ recovery_id: guard?.recovery_id ?? null, row: run, runtime: original.toString('utf8') }), { flag: 'wx', mode: 0o600 });
+      const context = { ddFlowHome: home, env: { ...process.env, DD_FLOW_HOME: home }, now: () => new Date().toISOString(), db: {
+        path: file, writable: true, get: (sql, params = []) => db.prepare(sql).get(...params), all: (sql, params = []) => db.prepare(sql).all(...params), run: (sql, params = []) => db.prepare(sql).run(...params), exec: sql => db.exec(sql)
+      } };
+      changed = true;
+      if (cancel) completeFlowRun(context, { projectRoot: run.project_root, runId: run.id, status: 'cancelled', manualOverrideReason: 'Operator requested cleanup of abandoned fixture: project removed; no Work, Session or controller history.' });
+      else setFlowRunRecoveryPaused(context, values.project, values.run, true);
+    }
+    report = { run_id: run.id, from: 'running', to: cancel ? 'cancelled' : 'paused', recovery_id: guard?.recovery_id ?? null, applied: values.apply, backup };
+  }
+  if (values.apply) db.exec('COMMIT');
+  console.log(JSON.stringify(report));
+} catch (error) {
+  if (values.apply && db.isTransaction) db.exec('ROLLBACK');
+  if (changed && original) { const temporary = `${runtimePath}.repair-rollback`; fs.writeFileSync(temporary, original); fs.renameSync(temporary, runtimePath); }
+  throw error;
+} finally { db.close(); }