@deksden-com/dd-flow-cli 0.6.0 → 0.8.0-beta.135

package/dist/services/worktrees.js

@@ -37,53 +37,67 @@ 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 { 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) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
     const worktrunk = ensureManagedWorktrunk(context);
-    const command = [worktrunk.bin, "-C", protocol.project_root, "switch", "--create", input.branch, "--base", input.base, "--no-cd", "--format=json", "-y"];
+    // 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 result = runExternal(command);
-    if (result.exit_code !== 0) {
+    if (result.exit_code !== 0)
         throw new AppError("worktrunk_command_unavailable", "Worktrunk switch failed", 1, { command: sanitizeCommand(command), result });
-    }
     const response = parseWorktrunkResponse(result.stdout, command);
-    const worktreePath = response.workspace_path;
-    if (isTrackedProjectPath(protocol.project_root, worktreePath)) {
-        throw new AppError("worktree_active", "Worktrunk returned a workspace inside tracked project files", 1, { path: worktreePath });
-    }
+    if (isTrackedProjectPath(projectRoot, response.workspace_path))
+        throw new AppError("worktree_active", "Worktrunk returned a workspace inside tracked project files", 1, { path: response.workspace_path });
+    return { worktreePath: response.workspace_path, worktrunk, command, result, response };
+}
+/** Attaches an already-created managed checkout to a newly materialized PRT. */
+export function recordManagedWorktree(context, input) {
+    const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
+    const existing = activeWorktreeRecord(context, protocol.project_id, protocol.id);
+    if (existing)
+        throw new AppError("worktree_already_exists", "Protocol already has an active worktree record", 1, { protocol_id: protocol.id, worktree_path: existing.worktree_path });
     const now = context.now();
     const state = readProtocolRuntimeState(context, protocol).state;
     context.db.run(`INSERT INTO worktree_records
       (protocol_id, project_id, integration_branch, feature_branch, base_ref, worktree_path,
        worktrunk_metadata_json, bootstrap_status, status, last_command_result_json, created_at, updated_at, closed_at)
-     VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 'active', ?, ?, ?, NULL)`, [
-        protocol.id,
-        protocol.project_id,
-        typeof state.workspace.integration_branch === "string" ? state.workspace.integration_branch : null,
-        input.branch,
-        input.base,
-        worktreePath,
-        JSON.stringify({ bin: worktrunk.bin, version: worktrunk.version, command, response }),
-        JSON.stringify(result),
-        now,
-        now
-    ]);
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, NULL)`, [protocol.id, protocol.project_id, typeof state.workspace.integration_branch === "string" ? state.workspace.integration_branch : null, input.branch, input.base, input.created.worktreePath, JSON.stringify({ bin: input.created.worktrunk.bin, version: input.created.worktrunk.version, command: input.created.command, response: input.created.response }), input.bootstrap?.status ?? "pending", JSON.stringify(input.bootstrap ?? input.created.result), now, now]);
     persistProtocolState(context, protocol, {
         ...state,
-        workspace: {
-            ...state.workspace,
-            feature_branch: input.branch,
-            worktree_path: worktreePath,
-            base_commit: input.base,
-            worktrunk: { bin: worktrunk.bin, version: worktrunk.version, response },
-            bootstrap: { status: typeof response.bootstrap_status === "string" ? response.bootstrap_status : "pending" }
-        },
+        workspace: { ...state.workspace, feature_branch: input.branch, worktree_path: input.created.worktreePath, base_commit: input.base, worktrunk: { bin: input.created.worktrunk.bin, version: input.created.worktrunk.version, response: input.created.response }, bootstrap: input.bootstrap ?? { status: typeof input.created.response.bootstrap_status === "string" ? input.created.response.bootstrap_status : "pending" } },
         updated_at: now
     });
-    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: worktreePath }
-    });
-    return { ok: true, worktree: activeWorktreeRecord(context, protocol.project_id, protocol.id) };
+    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);
+    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 });
+    }
+    const worktrunk = ensureManagedWorktrunk(context);
+    const commands = [
+        [worktrunk.bin, "-C", worktreePath, "step", "copy-ignored", "--require-include"],
+        [worktrunk.bin, "-C", worktreePath, "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) {
+            throw new AppError("bootstrap_failed", "Project-owned Worktrunk bootstrap failed", 1, { command: sanitizeCommand(command), result, results });
+        }
+    }
+    return { status: "succeeded", commands: results };
 }
 export function getWorktreeStatus(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
@@ -222,13 +236,20 @@ function parseWorktrunkResponse(stdout, command) {
         throw new AppError("worktrunk_invalid_response", "Worktrunk JSON response must be an object", 1, { command: sanitizeCommand(command) });
     }
     const response = parsed;
-    if (typeof response.workspace_path !== "string" || !path.isAbsolute(response.workspace_path)) {
-        throw new AppError("worktrunk_invalid_response", "Worktrunk response must contain an absolute workspace_path", 1, {
+    // `wt switch --format=json` returns `path` in the pinned 0.72 release.
+    // Normalize provider output once; the rest of dd-flow uses workspace_path.
+    const workspacePath = typeof response.workspace_path === "string"
+        ? response.workspace_path
+        : typeof response.path === "string"
+            ? response.path
+            : null;
+    if (!workspacePath || !path.isAbsolute(workspacePath)) {
+        throw new AppError("worktrunk_invalid_response", "Worktrunk response must contain an absolute path or workspace_path", 1, {
             command: sanitizeCommand(command),
             response
         });
     }
-    return { ...response, workspace_path: path.resolve(response.workspace_path) };
+    return { ...response, workspace_path: path.resolve(workspacePath) };
 }
 function markBootstrapFailed(context, protocol, record, failure) {
     const now = context.now();

package/dist/storage/database.js

@@ -5,27 +5,117 @@ import { ensureDir } from "./paths.js";
 import { AppError } from "../shared/errors.js";
 const require = createRequire(import.meta.url);
 const { DatabaseSync } = require("node:sqlite");
-export function getDatabase(ddFlowHome) {
-    ensureDir(ddFlowHome);
+/** Creates the single Work/Session authority used by a fresh vNext beta runtime. */
+export function ensureVnextWorkStorage(db) {
+    const legacy = db.get("SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('vnext_works', 'vnext_agent_turns', 'flow_agent_turns') LIMIT 1");
+    if (legacy)
+        throw new AppError("beta_storage_recreate_required", "This beta requires a fresh DD_FLOW_HOME; the previous Work runtime storage is not compatible", 1);
+    const existing = db.get("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'works'");
+    if (existing && (!/task TEXT NOT NULL/.test(existing.sql) || /launch_token|adapter_session_id/.test(existing.sql))) {
+        throw new AppError("beta_storage_recreate_required", "This beta requires a fresh DD_FLOW_HOME; the existing works schema is not compatible", 1);
+    }
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS works (
+      work_id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      run_id TEXT NOT NULL,
+      parent_work_id TEXT,
+      task TEXT NOT NULL,
+      launch_policy TEXT NOT NULL DEFAULT 'reuse_allowed',
+      result_schema TEXT,
+      payload_json TEXT,
+      depends_on_json TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL,
+      result TEXT,
+      created_at TEXT NOT NULL,
+      started_at TEXT,
+      updated_at TEXT NOT NULL,
+      completed_at TEXT,
+      FOREIGN KEY(project_id) REFERENCES projects(id),
+      FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id),
+      FOREIGN KEY(parent_work_id) REFERENCES works(work_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_works_run ON works(project_id, run_id, updated_at DESC);
+    CREATE TABLE IF NOT EXISTS work_sessions (
+      id TEXT PRIMARY KEY,
+      work_id TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      hook_event_id TEXT,
+      status TEXT NOT NULL,
+      prompt_path TEXT NOT NULL,
+      result_path TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      completed_at TEXT,
+      FOREIGN KEY(work_id) REFERENCES works(work_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_work_sessions_work ON work_sessions(work_id, created_at DESC);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_work_sessions_open ON work_sessions(work_id) WHERE status = 'running';
+    CREATE TABLE IF NOT EXISTS check_receipts (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      run_id TEXT NOT NULL,
+      work_id TEXT,
+      scope TEXT NOT NULL,
+      declaration_id TEXT NOT NULL,
+      command TEXT NOT NULL,
+      status TEXT NOT NULL,
+      exit_code INTEGER,
+      stdout_path TEXT NOT NULL,
+      stderr_path TEXT NOT NULL,
+      receipt_path TEXT NOT NULL,
+      workspace_fingerprint TEXT NOT NULL,
+      artifacts_json TEXT NOT NULL,
+      started_at TEXT NOT NULL,
+      finished_at TEXT NOT NULL,
+      FOREIGN KEY(work_id) REFERENCES works(work_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_check_receipts_run ON check_receipts(project_id, run_id, started_at);
+  `);
+}
+export function getDatabase(ddFlowHome, mode = "initialize") {
     const dbPath = path.join(ddFlowHome, "db.sqlite");
-    const db = new DatabaseSync(dbPath);
-    configureDatabase(db);
-    migrate(db);
+    const exists = fs.existsSync(dbPath);
+    if (mode === "read_existing" && !exists) {
+        return emptyReadOnlyDatabase(dbPath);
+    }
+    if (!exists || mode === "migrate")
+        ensureDir(ddFlowHome);
+    const db = mode === "read_existing" ? new DatabaseSync(dbPath, { readOnly: true }) : new DatabaseSync(dbPath);
+    configureDatabase(db, mode);
+    // Internal additive schema changes must be available to every write command.
+    // Higher-level Memory Bank migrations remain explicit in services/migrations.
+    if (mode !== "read_existing")
+        migrate(db);
+    if (mode === "read_existing")
+        db.exec("PRAGMA query_only = ON");
     db.exec("PRAGMA foreign_keys = ON");
     return {
         path: dbPath,
+        writable: mode !== "read_existing",
+        close: () => db.close?.(),
         exec: (sql) => db.exec(sql),
         run: (sql, params = []) => db.prepare(sql).run(...params),
         get: (sql, params = []) => db.prepare(sql).get(...params),
         all: (sql, params = []) => db.prepare(sql).all(...params)
     };
 }
-function configureDatabase(db) {
-    db.exec(`
-    PRAGMA busy_timeout = 4000;
-    PRAGMA journal_mode = WAL;
-    PRAGMA synchronous = NORMAL;
-  `);
+function emptyReadOnlyDatabase(dbPath) {
+    return {
+        path: dbPath,
+        writable: false,
+        exec: () => { throw new AppError("read_only_storage", "Read-only access cannot write absent dd-flow storage", 1, { path: dbPath }); },
+        run: () => { throw new AppError("read_only_storage", "Read-only access cannot write absent dd-flow storage", 1, { path: dbPath }); },
+        get: () => undefined,
+        all: () => []
+    };
+}
+function configureDatabase(db, mode) {
+    db.exec("PRAGMA busy_timeout = 4000");
+    if (mode !== "read_existing") {
+        db.exec("PRAGMA journal_mode = WAL");
+        db.exec("PRAGMA synchronous = NORMAL");
+    }
 }
 function migrate(db) {
     db.exec(`
@@ -248,9 +338,18 @@ function migrate(db) {
       updated_at TEXT NOT NULL
     );
 
-    CREATE TABLE IF NOT EXISTS flow_sessions (
+    CREATE TABLE IF NOT EXISTS sessions (
       session_id TEXT NOT NULL,
       project_id TEXT NOT NULL,
+      harness TEXT NOT NULL DEFAULT 'codex-desktop',
+      provider_session_id TEXT,
+      agent_id TEXT,
+      parent_id TEXT,
+      provider TEXT,
+      model TEXT,
+      reasoning TEXT,
+      mode TEXT,
+      agent_type TEXT,
       project_root TEXT NOT NULL,
       flow_kind TEXT NOT NULL,
       status TEXT NOT NULL,
@@ -275,7 +374,7 @@ function migrate(db) {
       FOREIGN KEY(project_id) REFERENCES projects(id)
     );
 
-    CREATE TABLE IF NOT EXISTS flow_runs (
+    CREATE TABLE IF NOT EXISTS runs (
       id TEXT NOT NULL,
       short_id TEXT NOT NULL,
       slug TEXT NOT NULL,
@@ -292,6 +391,7 @@ function migrate(db) {
       run_dir TEXT NOT NULL,
       run_index_path TEXT NOT NULL,
       run_home_path TEXT,
+      run_root TEXT,
       layout_version TEXT,
       artifact_root_kind TEXT,
       index_json TEXT NOT NULL,
@@ -303,10 +403,76 @@ function migrate(db) {
     );
 
     CREATE INDEX IF NOT EXISTS idx_flow_runs_project_updated
-      ON flow_runs(project_id, updated_at DESC);
+      ON runs(project_id, updated_at DESC);
 
     CREATE INDEX IF NOT EXISTS idx_flow_runs_short_id
-      ON flow_runs(short_id);
+      ON runs(short_id);
+
+    CREATE TABLE IF NOT EXISTS works (
+      work_id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      run_id TEXT NOT NULL,
+      parent_work_id TEXT,
+      task TEXT NOT NULL,
+      launch_policy TEXT NOT NULL DEFAULT 'reuse_allowed',
+      result_schema TEXT,
+      payload_json TEXT,
+      depends_on_json TEXT NOT NULL DEFAULT '[]',
+      status TEXT NOT NULL,
+      result TEXT,
+      created_at TEXT NOT NULL,
+      started_at TEXT,
+      updated_at TEXT NOT NULL,
+      completed_at TEXT,
+      FOREIGN KEY(project_id) REFERENCES projects(id),
+      FOREIGN KEY(project_id, run_id) REFERENCES runs(project_id, id),
+      FOREIGN KEY(parent_work_id) REFERENCES works(work_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_works_run
+      ON works(project_id, run_id, updated_at DESC);
+
+    CREATE TABLE IF NOT EXISTS work_sessions (
+      id TEXT PRIMARY KEY,
+      work_id TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      hook_event_id TEXT,
+      status TEXT NOT NULL,
+      prompt_path TEXT NOT NULL,
+      result_path TEXT,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      completed_at TEXT,
+      FOREIGN KEY(work_id) REFERENCES works(work_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_work_sessions_work
+      ON work_sessions(work_id, created_at DESC);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_work_sessions_open
+      ON work_sessions(work_id) WHERE status = 'running';
+
+    CREATE TABLE IF NOT EXISTS check_receipts (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      run_id TEXT NOT NULL,
+      work_id TEXT,
+      scope TEXT NOT NULL,
+      declaration_id TEXT NOT NULL,
+      command TEXT NOT NULL,
+      status TEXT NOT NULL,
+      exit_code INTEGER,
+      stdout_path TEXT NOT NULL,
+      stderr_path TEXT NOT NULL,
+      receipt_path TEXT NOT NULL,
+      workspace_fingerprint TEXT NOT NULL,
+      artifacts_json TEXT NOT NULL,
+      started_at TEXT NOT NULL,
+      finished_at TEXT NOT NULL,
+      FOREIGN KEY(work_id) REFERENCES works(work_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_check_receipts_run
+      ON check_receipts(project_id, run_id, started_at);
 
     CREATE TABLE IF NOT EXISTS flow_run_flag_mutations (
       project_id TEXT NOT NULL,
@@ -320,7 +486,7 @@ function migrate(db) {
       FOREIGN KEY(project_id) REFERENCES projects(id)
     );
 
-    CREATE TABLE IF NOT EXISTS flow_run_usage_snapshots (
+    CREATE TABLE IF NOT EXISTS usage (
       id TEXT PRIMARY KEY,
       project_id TEXT NOT NULL,
       run_id TEXT NOT NULL,
@@ -338,6 +504,10 @@ function migrate(db) {
       output_tokens INTEGER,
       reasoning_output_tokens INTEGER,
       source_kind TEXT NOT NULL,
+      source_locator TEXT,
+      source_sha256 TEXT,
+      source_size_bytes INTEGER,
+      source_mtime_ms INTEGER,
       token_event_at TEXT,
       turn_id TEXT,
       turn_attribution TEXT NOT NULL,
@@ -349,14 +519,55 @@ function migrate(db) {
     );
 
     CREATE INDEX IF NOT EXISTS idx_flow_run_usage_snapshots_run
-      ON flow_run_usage_snapshots(project_id, run_id, session_id, observed_at, id);
+      ON usage(project_id, run_id, session_id, observed_at, id);
 
-    CREATE TABLE IF NOT EXISTS codex_hook_events (
+    CREATE TABLE IF NOT EXISTS harness_usage_snapshots (
+      id TEXT PRIMARY KEY,
+      project_id TEXT NOT NULL,
+      harness TEXT NOT NULL,
+      provider_session_id TEXT NOT NULL,
+      daemon_id TEXT,
+      observed_at TEXT NOT NULL,
+      total_tokens INTEGER NOT NULL,
+      input_tokens INTEGER,
+      cache_read_input_tokens INTEGER,
+      cache_write_input_tokens INTEGER,
+      output_tokens INTEGER,
+      reasoning_output_tokens INTEGER,
+      request_count INTEGER,
+      error_count INTEGER,
+      tool_calls INTEGER,
+      tool_failures INTEGER,
+      tool_by_name_json TEXT,
+      source_kind TEXT NOT NULL DEFAULT 'zcode_session_usage_v1',
+      usage_scope TEXT NOT NULL DEFAULT 'physical_session',
+      completeness TEXT NOT NULL DEFAULT 'complete',
+      created_at TEXT NOT NULL,
+      UNIQUE(project_id, harness, provider_session_id, observed_at),
+      FOREIGN KEY(project_id) REFERENCES projects(id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_harness_usage_provider
+      ON harness_usage_snapshots(project_id, harness, provider_session_id, observed_at, id);
+
+    CREATE TABLE IF NOT EXISTS hook_events (
       id INTEGER PRIMARY KEY AUTOINCREMENT,
       project_id TEXT NOT NULL,
       protocol_id TEXT,
+      harness TEXT NOT NULL DEFAULT 'codex-desktop',
+      provider_session_id TEXT,
+      parent_session_id TEXT,
+      daemon_id TEXT,
       session_id TEXT,
+      agent_id TEXT,
       turn_id TEXT,
+      transcript_path TEXT,
+      provider TEXT,
+      model TEXT,
+      reasoning TEXT,
+      mode TEXT,
+      agent_type TEXT,
+      cwd TEXT,
       event_key TEXT,
       event_name TEXT NOT NULL,
       tool_name TEXT,
@@ -439,32 +650,71 @@ function migrate(db) {
     ensureColumn(db, "merge_queue", "completed_at", "ALTER TABLE merge_queue ADD COLUMN completed_at TEXT");
     ensureColumn(db, "codex_session_bindings", "continuation_count", "ALTER TABLE codex_session_bindings ADD COLUMN continuation_count INTEGER NOT NULL DEFAULT 0");
     ensureColumn(db, "codex_session_bindings", "last_action_hash", "ALTER TABLE codex_session_bindings ADD COLUMN last_action_hash TEXT");
-    ensureColumn(db, "flow_sessions", "current_stage", "ALTER TABLE flow_sessions ADD COLUMN current_stage TEXT");
-    ensureColumn(db, "flow_sessions", "next_action", "ALTER TABLE flow_sessions ADD COLUMN next_action TEXT");
-    ensureColumn(db, "flow_sessions", "metadata_json", "ALTER TABLE flow_sessions ADD COLUMN metadata_json TEXT NOT NULL DEFAULT '{}'");
-    ensureColumn(db, "flow_sessions", "run_id", "ALTER TABLE flow_sessions ADD COLUMN run_id TEXT");
-    ensureColumn(db, "flow_sessions", "parent_session_id", "ALTER TABLE flow_sessions ADD COLUMN parent_session_id TEXT");
-    ensureColumn(db, "flow_sessions", "role", "ALTER TABLE flow_sessions ADD COLUMN role TEXT");
-    ensureColumn(db, "flow_sessions", "aspect_id", "ALTER TABLE flow_sessions ADD COLUMN aspect_id TEXT");
-    ensureColumn(db, "flow_sessions", "plan_item_id", "ALTER TABLE flow_sessions ADD COLUMN plan_item_id TEXT");
-    ensureColumn(db, "flow_sessions", "session_kind", "ALTER TABLE flow_sessions ADD COLUMN session_kind TEXT");
-    ensureColumn(db, "flow_sessions", "coverage_units_json", "ALTER TABLE flow_sessions ADD COLUMN coverage_units_json TEXT NOT NULL DEFAULT '[]'");
-    ensureColumn(db, "flow_run_usage_snapshots", "cache_read_input_tokens", "ALTER TABLE flow_run_usage_snapshots ADD COLUMN cache_read_input_tokens INTEGER");
-    ensureColumn(db, "flow_run_usage_snapshots", "cache_write_input_tokens", "ALTER TABLE flow_run_usage_snapshots ADD COLUMN cache_write_input_tokens INTEGER");
-    ensureColumn(db, "flow_run_usage_snapshots", "uncached_input_tokens", "ALTER TABLE flow_run_usage_snapshots ADD COLUMN uncached_input_tokens INTEGER");
-    db.prepare("UPDATE flow_run_usage_snapshots SET cache_read_input_tokens = cached_input_tokens WHERE cache_read_input_tokens IS NULL AND cached_input_tokens IS NOT NULL").run();
-    ensureColumn(db, "flow_runs", "run_home_path", "ALTER TABLE flow_runs ADD COLUMN run_home_path TEXT");
-    ensureColumn(db, "flow_runs", "layout_version", "ALTER TABLE flow_runs ADD COLUMN layout_version TEXT");
-    ensureColumn(db, "flow_runs", "artifact_root_kind", "ALTER TABLE flow_runs ADD COLUMN artifact_root_kind TEXT");
-    ensureColumn(db, "codex_hook_events", "event_key", "ALTER TABLE codex_hook_events ADD COLUMN event_key TEXT");
+    ensureColumn(db, "sessions", "current_stage", "ALTER TABLE sessions ADD COLUMN current_stage TEXT");
+    ensureColumn(db, "sessions", "next_action", "ALTER TABLE sessions ADD COLUMN next_action TEXT");
+    ensureColumn(db, "sessions", "metadata_json", "ALTER TABLE sessions ADD COLUMN metadata_json TEXT NOT NULL DEFAULT '{}'");
+    ensureColumn(db, "sessions", "run_id", "ALTER TABLE sessions ADD COLUMN run_id TEXT");
+    ensureColumn(db, "sessions", "provider_session_id", "ALTER TABLE sessions ADD COLUMN provider_session_id TEXT");
+    ensureColumn(db, "sessions", "harness", "ALTER TABLE sessions ADD COLUMN harness TEXT NOT NULL DEFAULT 'codex-desktop'");
+    ensureColumn(db, "sessions", "agent_id", "ALTER TABLE sessions ADD COLUMN agent_id TEXT");
+    ensureColumn(db, "sessions", "provider", "ALTER TABLE sessions ADD COLUMN provider TEXT");
+    ensureColumn(db, "sessions", "parent_id", "ALTER TABLE sessions ADD COLUMN parent_id TEXT");
+    ensureColumn(db, "sessions", "model", "ALTER TABLE sessions ADD COLUMN model TEXT");
+    ensureColumn(db, "sessions", "reasoning", "ALTER TABLE sessions ADD COLUMN reasoning TEXT");
+    ensureColumn(db, "sessions", "mode", "ALTER TABLE sessions ADD COLUMN mode TEXT");
+    ensureColumn(db, "sessions", "agent_type", "ALTER TABLE sessions ADD COLUMN agent_type TEXT");
+    ensureColumn(db, "sessions", "parent_session_id", "ALTER TABLE sessions ADD COLUMN parent_session_id TEXT");
+    ensureColumn(db, "sessions", "role", "ALTER TABLE sessions ADD COLUMN role TEXT");
+    ensureColumn(db, "sessions", "aspect_id", "ALTER TABLE sessions ADD COLUMN aspect_id TEXT");
+    ensureColumn(db, "sessions", "plan_item_id", "ALTER TABLE sessions ADD COLUMN plan_item_id TEXT");
+    ensureColumn(db, "sessions", "session_kind", "ALTER TABLE sessions ADD COLUMN session_kind TEXT");
+    ensureColumn(db, "sessions", "coverage_units_json", "ALTER TABLE sessions ADD COLUMN coverage_units_json TEXT NOT NULL DEFAULT '[]'");
+    ensureColumn(db, "usage", "cache_read_input_tokens", "ALTER TABLE usage ADD COLUMN cache_read_input_tokens INTEGER");
+    ensureColumn(db, "usage", "cache_write_input_tokens", "ALTER TABLE usage ADD COLUMN cache_write_input_tokens INTEGER");
+    ensureColumn(db, "usage", "uncached_input_tokens", "ALTER TABLE usage ADD COLUMN uncached_input_tokens INTEGER");
+    ensureColumn(db, "usage", "source_locator", "ALTER TABLE usage ADD COLUMN source_locator TEXT");
+    ensureColumn(db, "usage", "source_sha256", "ALTER TABLE usage ADD COLUMN source_sha256 TEXT");
+    ensureColumn(db, "usage", "source_size_bytes", "ALTER TABLE usage ADD COLUMN source_size_bytes INTEGER");
+    ensureColumn(db, "usage", "source_mtime_ms", "ALTER TABLE usage ADD COLUMN source_mtime_ms INTEGER");
+    db.prepare("UPDATE usage SET cache_read_input_tokens = cached_input_tokens WHERE cache_read_input_tokens IS NULL AND cached_input_tokens IS NOT NULL").run();
+    ensureColumn(db, "runs", "run_home_path", "ALTER TABLE runs ADD COLUMN run_home_path TEXT");
+    ensureColumn(db, "runs", "run_root", "ALTER TABLE runs ADD COLUMN run_root TEXT");
+    ensureColumn(db, "runs", "layout_version", "ALTER TABLE runs ADD COLUMN layout_version TEXT");
+    ensureColumn(db, "runs", "artifact_root_kind", "ALTER TABLE runs ADD COLUMN artifact_root_kind TEXT");
+    ensureColumn(db, "works", "payload_json", "ALTER TABLE works ADD COLUMN payload_json TEXT");
+    ensureColumn(db, "check_receipts", "declaration_id", "ALTER TABLE check_receipts ADD COLUMN declaration_id TEXT NOT NULL DEFAULT 'CHK-LEGACY'");
+    ensureColumn(db, "check_receipts", "workspace_fingerprint", "ALTER TABLE check_receipts ADD COLUMN workspace_fingerprint TEXT NOT NULL DEFAULT ''");
+    ensureColumn(db, "check_receipts", "artifacts_json", "ALTER TABLE check_receipts ADD COLUMN artifacts_json TEXT NOT NULL DEFAULT '[]'");
+    ensureColumn(db, "hook_events", "event_key", "ALTER TABLE hook_events ADD COLUMN event_key TEXT");
+    ensureColumn(db, "hook_events", "match_key", "ALTER TABLE hook_events ADD COLUMN match_key TEXT");
+    ensureColumn(db, "hook_events", "claimed_at", "ALTER TABLE hook_events ADD COLUMN claimed_at TEXT");
+    ensureColumn(db, "hook_events", "agent_id", "ALTER TABLE hook_events ADD COLUMN agent_id TEXT");
+    ensureColumn(db, "hook_events", "transcript_path", "ALTER TABLE hook_events ADD COLUMN transcript_path TEXT");
+    ensureColumn(db, "hook_events", "provider", "ALTER TABLE hook_events ADD COLUMN provider TEXT");
+    ensureColumn(db, "hook_events", "model", "ALTER TABLE hook_events ADD COLUMN model TEXT");
+    ensureColumn(db, "hook_events", "reasoning", "ALTER TABLE hook_events ADD COLUMN reasoning TEXT");
+    ensureColumn(db, "hook_events", "mode", "ALTER TABLE hook_events ADD COLUMN mode TEXT");
+    ensureColumn(db, "hook_events", "agent_type", "ALTER TABLE hook_events ADD COLUMN agent_type TEXT");
+    ensureColumn(db, "hook_events", "harness", "ALTER TABLE hook_events ADD COLUMN harness TEXT NOT NULL DEFAULT 'codex-desktop'");
+    ensureColumn(db, "hook_events", "provider_session_id", "ALTER TABLE hook_events ADD COLUMN provider_session_id TEXT");
+    ensureColumn(db, "hook_events", "parent_session_id", "ALTER TABLE hook_events ADD COLUMN parent_session_id TEXT");
+    ensureColumn(db, "hook_events", "daemon_id", "ALTER TABLE hook_events ADD COLUMN daemon_id TEXT");
+    ensureColumn(db, "hook_events", "cwd", "ALTER TABLE hook_events ADD COLUMN cwd TEXT");
+    ensureColumn(db, "harness_usage_snapshots", "tool_calls", "ALTER TABLE harness_usage_snapshots ADD COLUMN tool_calls INTEGER");
+    ensureColumn(db, "harness_usage_snapshots", "tool_failures", "ALTER TABLE harness_usage_snapshots ADD COLUMN tool_failures INTEGER");
+    ensureColumn(db, "harness_usage_snapshots", "tool_by_name_json", "ALTER TABLE harness_usage_snapshots ADD COLUMN tool_by_name_json TEXT");
+    ensureColumn(db, "harness_usage_snapshots", "source_kind", "ALTER TABLE harness_usage_snapshots ADD COLUMN source_kind TEXT NOT NULL DEFAULT 'zcode_session_usage_v1'");
+    ensureColumn(db, "harness_usage_snapshots", "usage_scope", "ALTER TABLE harness_usage_snapshots ADD COLUMN usage_scope TEXT NOT NULL DEFAULT 'physical_session'");
+    ensureColumn(db, "harness_usage_snapshots", "completeness", "ALTER TABLE harness_usage_snapshots ADD COLUMN completeness TEXT NOT NULL DEFAULT 'complete'");
     ensureColumn(db, "flow_jobs", "updated_at", "ALTER TABLE flow_jobs ADD COLUMN updated_at TEXT NOT NULL DEFAULT ''");
-    db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_codex_hook_events_event_key ON codex_hook_events(project_id, event_key) WHERE event_key IS NOT NULL");
+    db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_codex_hook_events_event_key ON hook_events(project_id, event_key) WHERE event_key IS NOT NULL");
+    db.exec("CREATE INDEX IF NOT EXISTS idx_codex_hook_events_bootstrap_claim ON hook_events(project_id, session_id, match_key, status, created_at DESC)");
     ensureColumn(db, "lane_waiters", "expires_at", "ALTER TABLE lane_waiters ADD COLUMN expires_at TEXT");
     db.exec(`
     CREATE INDEX IF NOT EXISTS idx_flow_runs_project_updated
-      ON flow_runs(project_id, updated_at DESC);
+      ON runs(project_id, updated_at DESC);
     CREATE INDEX IF NOT EXISTS idx_flow_runs_short_id
-      ON flow_runs(short_id);
+      ON runs(short_id);
   `);
 }
 function migrateProjectScopedIdentity(db) {
@@ -479,7 +729,7 @@ function migrateProjectScopedIdentity(db) {
 
     ALTER TABLE merge_queue RENAME TO merge_queue_legacy_global_identity;
     ALTER TABLE worktree_records RENAME TO worktree_records_legacy_global_identity;
-    ALTER TABLE flow_runs RENAME TO flow_runs_legacy_global_identity;
+    ALTER TABLE runs RENAME TO flow_runs_legacy_global_identity;
     ALTER TABLE protocols RENAME TO protocols_legacy_global_identity;
 
     CREATE TABLE protocols (
@@ -560,7 +810,7 @@ function migrateProjectScopedIdentity(db) {
         status, last_command_result_json, created_at, updated_at, closed_at
       FROM worktree_records_legacy_global_identity;
 
-    CREATE TABLE flow_runs (
+    CREATE TABLE runs (
       id TEXT NOT NULL,
       short_id TEXT NOT NULL,
       slug TEXT NOT NULL,
@@ -586,7 +836,7 @@ function migrateProjectScopedIdentity(db) {
       PRIMARY KEY(project_id, id),
       FOREIGN KEY(project_id) REFERENCES projects(id)
     );
-    INSERT INTO flow_runs
+    INSERT INTO runs
       (id, short_id, slug, project_id, project_root, workspace_root, flow_kind,
        subject_type, subject_id, status, verdict, next_action, runtime_path,
        run_dir, run_index_path, run_home_path, layout_version,

package/dist/storage/paths.js

@@ -3,18 +3,64 @@ import os from "node:os";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
 export function resolveDdFlowHome(env) {
+    // Keep the operator spelling stable in generated commands; containment checks
+    // canonicalize paths separately when filesystem identity matters.
     return path.resolve(env.DD_FLOW_HOME ?? path.join(os.homedir(), ".dd-flow"));
 }
 export function ensureDir(dir) {
     fs.mkdirSync(dir, { recursive: true });
 }
 export function resolveProjectRoot(root) {
-    const absolute = path.resolve(root);
+    const absolute = canonicalPath(root, false);
     if (!fs.existsSync(absolute)) {
         throw new AppError("not_found", `Project root does not exist: ${absolute}`, 1);
     }
     return fs.realpathSync(absolute);
 }
+/** Resolve an existing path to its filesystem identity, or normalize a future path. */
+export function canonicalPath(value, mustExist = true) {
+    const absolute = path.resolve(value);
+    if (fs.existsSync(absolute))
+        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));
+}
+export function assertPathWithin(root, candidate, label = "path") {
+    const canonicalRoot = canonicalPath(root);
+    const canonicalCandidate = canonicalPath(candidate, false);
+    const relative = path.relative(canonicalRoot, canonicalCandidate);
+    if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)))
+        return canonicalCandidate;
+    throw new AppError("validation", `${label} must stay inside ${canonicalRoot}`, 2, { root: canonicalRoot, [label]: canonicalCandidate });
+}
+export function runReference(runId, relativePath) {
+    const normalized = relativePath.replaceAll(path.sep, "/").replace(/^\/+/, "");
+    if (!normalized || normalized.split("/").includes(".."))
+        throw new AppError("validation", "RUN reference must be a safe relative path", 2, { relative_path: relativePath });
+    return `run://${runId}/${normalized}`;
+}
+export function resolveRunReference(value, runId, runRoot) {
+    const prefix = `run://${runId}/`;
+    if (!value.startsWith(prefix))
+        return value;
+    return assertPathWithin(runRoot, path.join(runRoot, value.slice(prefix.length)), "run_reference");
+}
+export function resolveRunReferences(value, runId, runRoot) {
+    return value.replace(new RegExp(`run://${escapeRegExp(runId)}/([^\\s)]+)`, "g"), (reference) => resolveRunReference(reference, runId, runRoot));
+}
+export function writeJsonAtomic(file, value) {
+    ensureDir(path.dirname(file));
+    const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
+    fs.renameSync(temporary, file);
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 export function protocolDir(projectRoot, protocolId) {
     return path.join(projectRoot, ".memory-bank", "protocol", protocolId);
 }