@deksden-com/dd-flow-cli 0.4.2 → 0.5.0

package/dist/services/protocols.js

@@ -8,10 +8,11 @@ import { requireStage } from "../domain/validation.js";
 import { AppError } from "../shared/errors.js";
 import { parseJsonObject } from "../shared/json.js";
 import { ensureReadableFile } from "../storage/database.js";
-import { ensureDir, resolveProjectRoot, runtimePlanJsonPath, runtimeProtocolDir, runtimeStateJsonPath } from "../storage/paths.js";
+import { ensureDir, planJsonPath, resolveProjectRoot, runtimeProtocolDir, runtimeStateJsonPath } from "../storage/paths.js";
 import { appendAudit, getAuditEvents } from "./audit.js";
 import { requireProjectByRoot } from "./projects.js";
-import { ensureRuntimeProtocolFiles, readPlanFile, readStateFile, writeState } from "../protocol/local-files.js";
+import { ensureRuntimeProtocolFiles, readStateFile, writeState } from "../protocol/local-files.js";
+import { planSummary, planWithProgress, readCanonicalPlan } from "./plan-runtime.js";
 import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProject, codexHomeProfilesForProject, codexHookEventsForProject, hookStatusForProject } from "./hooks.js";
 import { buildProtocolFlowGuidance } from "./flow-guidance.js";
 import { lifecycleIsTerminalFailure, lifecycleIsTerminalSuccess, normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
@@ -46,7 +47,7 @@ export function registerProtocol(context, input) {
         JSON.stringify(state.blockers),
         JSON.stringify(state.active_def),
         runtimeStateJsonPath(context.ddFlowHome, project.id, protocolId),
-        runtimePlanJsonPath(context.ddFlowHome, project.id, protocolId),
+        planJsonPath(projectRoot, protocolId),
         existing?.created_at ?? now,
         now
     ];
@@ -88,7 +89,7 @@ export function getProtocolStatus(context, input) {
     const protocol = requireProtocol(context, input.protocolId, project.id);
     const runtime = readProtocolRuntimeState(context, protocol);
     const state = runtime.state;
-    const plan = readPlanFile(protocol.plan_path);
+    const plan = canonicalPlanIfPresent(context, protocol);
     const runDiagnostics = protocolRunDiagnostics(context, protocol, state);
     const queue = context.db.get("SELECT * FROM merge_queue WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]);
     const lifecycle = normalizeProtocolLifecycle({ state, queueStatus: queue?.status ?? null });
@@ -99,7 +100,7 @@ export function getProtocolStatus(context, input) {
         diagnostics: [...runtime.diagnostics, ...runDiagnostics.diagnostics, ...lifecycle.diagnostics],
         latest_run: runDiagnostics.latest_run,
         state,
-        plan: plan ? summarizePlan(plan) : state.plan,
+        plan: plan ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }) : state.plan,
         merge_queue: queue,
         branch_context: getProtocolBranchContext(context, { protocolId: protocol.id, projectRoot: project.root }).branch_context,
         flow_guidance: buildProtocolFlowGuidance({ state, latestRun: runDiagnostics.latest_run, queueStatus: queue?.status ?? null }),
@@ -334,11 +335,15 @@ export function readyForMerge(context, input) {
     if (missing.length > 0) {
         throw new AppError("readiness_missing_fields", "Protocol is missing explicit readiness fields", 1, { missing });
     }
-    if (state.active_def.length > 0) {
-        throw new AppError("readiness_blocked", "Protocol has open deferrals", 1, { active_def: state.active_def });
+    const blockingDefs = state.active_def.filter(isBlockingDeferral);
+    if (blockingDefs.length > 0) {
+        throw new AppError("readiness_blocked", "Protocol has open blocking deferrals", 1, { active_def: blockingDefs });
     }
-    const plan = readPlanFile(protocol.plan_path);
-    const openRequired = plan?.items.filter((item) => item.required && !["done", "skipped"].includes(item.status)) ?? [];
+    const plan = canonicalPlanIfPresent(context, protocol);
+    const openRequired = plan
+        ? planWithProgress(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }).plan.items
+            .filter((item) => item.required && !["done", "skipped"].includes(item.status))
+        : [];
     if (openRequired.length > 0) {
         throw new AppError("readiness_plan_open", "Protocol has open required plan items", 1, {
             items: openRequired.map((item) => ({ id: item.id, status: item.status }))
@@ -374,6 +379,11 @@ export function readyForMerge(context, input) {
         flow_guidance: buildProtocolFlowGuidance({ state: nextState, latestRun: runDiagnostics.latest_run, queueStatus: "ready" })
     };
 }
+function isBlockingDeferral(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return true;
+    return value.blocking !== false;
+}
 export function syncProtocolFromRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const protocol = requireProtocol(context, input.protocolId, project.id);
@@ -738,7 +748,7 @@ export function readProtocolRuntimeState(context, protocol) {
                 source: "stable_runtime_state",
                 recommended_action: "legacy protocol state_path was moved to stable runtime storage"
             });
-            const stablePlanPath = runtimePlanJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+            const stablePlanPath = planJsonPath(protocol.project_root, protocol.id);
             context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [stableStatePath, stablePlanPath, protocol.project_id, protocol.id]);
             protocol.state_path = stableStatePath;
             protocol.plan_path = stablePlanPath;
@@ -752,9 +762,9 @@ export function readProtocolRuntimeState(context, protocol) {
             recommended_action: "runtime state reconstructed from SQLite; run cleanup scan/apply if this persists"
         });
     }
-    const plan = context.db.get("SELECT plan_json FROM plans WHERE project_id = ? AND protocol_id = ?", [protocol.project_id, protocol.id]);
-    const planSummary = plan
-        ? planSummaryForState(JSON.parse(plan.plan_json))
+    const plan = canonicalPlanIfPresent(context, protocol);
+    const summary = plan
+        ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path })
         : { plan_id: null, total: 0, done: 0, blocked: 0 };
     const flowContract = loadProjectFlowContract(protocol.project_root);
     const state = {
@@ -766,14 +776,14 @@ export function readProtocolRuntimeState(context, protocol) {
         next_action: protocol.next_action,
         route: JSON.parse(protocol.route_json),
         workspace: JSON.parse(protocol.workspace_json),
-        plan: planSummary,
+        plan: summary,
         blockers: JSON.parse(protocol.blockers_json),
         active_def: JSON.parse(protocol.active_def_json),
         flow_contract: flowContract,
         updated_at: protocol.updated_at
     };
     const stableStatePath = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
-    const stablePlanPath = runtimePlanJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
+    const stablePlanPath = planJsonPath(protocol.project_root, protocol.id);
     ensureDir(path.dirname(stableStatePath));
     writeState(stableStatePath, state);
     context.db.run("UPDATE protocols SET state_path = ?, plan_path = ? WHERE project_id = ? AND id = ?", [stableStatePath, stablePlanPath, protocol.project_id, protocol.id]);
@@ -1162,16 +1172,10 @@ function protocolStatusPayload(protocol) {
         updated_at: protocol.updated_at
     };
 }
-function summarizePlan(plan) {
-    return planSummaryForState(plan);
-}
-function planSummaryForState(plan) {
-    return {
-        plan_id: plan.plan_id,
-        total: plan.items.length,
-        done: plan.items.filter((item) => item.status === "done").length,
-        blocked: plan.items.filter((item) => item.status === "blocked").length
-    };
+function canonicalPlanIfPresent(context, protocol) {
+    if (!fs.existsSync(protocol.plan_path))
+        return undefined;
+    return readCanonicalPlan(protocol.plan_path, protocol.id).plan;
 }
 function readinessMissingFields(state) {
     const missing = [];

package/dist/services/run-projection.js

@@ -1,29 +1,95 @@
 import fs from "node:fs";
 import path from "node:path";
 export function refreshRunSessionProjection(context, projectId, runId) {
-    const run = context.db.get("SELECT id, runtime_path, run_index_path, index_json FROM flow_runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const run = context.db.get("SELECT id, project_root, subject_type, subject_id, runtime_path, run_index_path, index_json FROM flow_runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     if (!run)
         return;
     const index = JSON.parse(run.index_json);
     const sessions = context.db.all(`SELECT session_id, parent_session_id, role, session_kind, worker_id, current_stage, status,
             created_at, updated_at, stopped_at, coverage_units_json
        FROM flow_sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id`, [projectId, runId]).map(sessionProjection);
-    if (JSON.stringify(index.sessions ?? []) === JSON.stringify(sessions))
+    const plan = run.subject_type === "protocol" ? planProjection(context, projectId, run.subject_id, run.project_root) : {};
+    const workers = workerProjection(context, projectId, runId);
+    if (JSON.stringify(index.sessions ?? []) === JSON.stringify(sessions)
+        && JSON.stringify(index.plan_ref) === JSON.stringify(plan.plan_ref)
+        && JSON.stringify(index.plan_progress) === JSON.stringify(plan.plan_progress)
+        && JSON.stringify(index.workers ?? {}) === JSON.stringify(workers))
         return;
     index.sessions = sessions;
+    if (plan.plan_ref)
+        index.plan_ref = plan.plan_ref;
+    if (plan.plan_progress)
+        index.plan_progress = plan.plan_progress;
+    index.workers = workers;
     index.updated_at = context.now();
-    const runtimeRevision = typeof index.runtime_revision === "number" ? index.runtime_revision + 1 : 1;
-    index.runtime_revision = runtimeRevision;
     const runtime = readJson(run.runtime_path);
-    if (runtime) {
-        runtime.sessions = sessions;
-        runtime.updated_at = index.updated_at;
-        runtime.runtime_revision = runtimeRevision;
-    }
-    writeJson(run.run_index_path, index);
-    writeJson(run.runtime_path, runtime ?? index);
+    const runtimeRevision = typeof runtime?.runtime_revision === "number"
+        ? runtime.runtime_revision + 1
+        : typeof index.runtime_revision === "number"
+            ? index.runtime_revision + 1
+            : 1;
+    index.runtime_revision = runtimeRevision;
+    const authoritative = runtime ?? { ...index, schema_id: "dd-flow/flow-run@2" };
+    authoritative.sessions = sessions;
+    if (plan.plan_ref)
+        authoritative.plan_ref = plan.plan_ref;
+    if (plan.plan_progress)
+        authoritative.plan_progress = plan.plan_progress;
+    authoritative.workers = workers;
+    authoritative.updated_at = index.updated_at;
+    authoritative.runtime_revision = runtimeRevision;
+    writeJson(run.runtime_path, authoritative);
     context.db.run("UPDATE flow_runs SET index_json = ?, updated_at = ? WHERE project_id = ? AND id = ?", [JSON.stringify(index), index.updated_at, projectId, runId]);
 }
+function planProjection(context, projectId, protocolId, projectRoot) {
+    const binding = context.db.get("SELECT plan_path, plan_revision, plan_sha256 FROM plan_bindings WHERE project_id = ? AND protocol_id = ?", [projectId, protocolId]);
+    if (!binding)
+        return {};
+    const planPath = path.relative(projectRoot, binding.plan_path).split(path.sep).join("/");
+    const planId = readPlanId(binding.plan_path);
+    const progress = Object.fromEntries(context.db.all("SELECT item_id, status, summary, evidence_json FROM plan_progress WHERE project_id = ? AND protocol_id = ? ORDER BY item_id", [projectId, protocolId]).map((row) => [row.item_id, {
+            status: row.status,
+            ...(row.summary ? { summary: row.summary } : {}),
+            ...(parseStringArray(row.evidence_json).length > 0 ? { evidence: parseStringArray(row.evidence_json) } : {})
+        }]));
+    return {
+        plan_ref: {
+            path: planPath,
+            plan_id: planId,
+            revision: binding.plan_revision,
+            sha256: binding.plan_sha256
+        },
+        plan_progress: progress
+    };
+}
+function readPlanId(planPath) {
+    try {
+        const value = JSON.parse(fs.readFileSync(planPath, "utf8"));
+        if (value && typeof value === "object" && !Array.isArray(value) && typeof value.plan_id === "string") {
+            return value.plan_id;
+        }
+    }
+    catch {
+        // The canonical validator owns malformed-plan errors; projection stays bounded.
+    }
+    return "unknown-plan";
+}
+function workerProjection(context, projectId, runId) {
+    return Object.fromEntries(context.db.all("SELECT job_id, plan_item_id, status, worker_session_id FROM flow_jobs WHERE project_id = ? AND run_id = ? ORDER BY job_id", [projectId, runId]).map((job) => [job.job_id, {
+            units: [job.plan_item_id],
+            status: { pending: "registered", done: "completed" }[job.status] ?? job.status,
+            ...(job.worker_session_id ? { session_id: job.worker_session_id } : {})
+        }]));
+}
+function parseStringArray(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) && parsed.every((entry) => typeof entry === "string") ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
 function sessionProjection(row) {
     return {
         session_id: row.session_id,

package/dist/services/runs.js

@@ -5,17 +5,15 @@ import { spawnSync } from "node:child_process";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
 import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
-import { ensureDir, projectRunHome, projectRunIndexPath, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
+import { ensureDir, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { buildRunFlowGuidance } from "./flow-guidance.js";
 import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { checkpointRunUsage, usageForRun } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
-const runSchemaId = "dd-flow/flow-run-index@3";
-const legacyRunSchemaId = "dd-flow/flow-run-index@2";
-const oldestRunSchemaId = "dd-flow/flow-run-index@1";
-const runtimeSchemaId = "dd-flow/flow-run@1";
+const runSchemaId = "dd-flow/flow-run@2";
+const runtimeSchemaId = "dd-flow/flow-run@2";
 const runIdType = "RUN";
 const allowedRunFlowKinds = [
     "mb_sdlc",
@@ -51,7 +49,6 @@ export function startFlowRun(context, input) {
         now
     });
     const runHome = projectRunHome(context.ddFlowHome, project.id, runId);
-    const runIndexAbsolute = projectRunIndexPath(context.ddFlowHome, project.id, runId);
     const runDirRelative = path.posix.join("runs", runId);
     const runtimePath = projectRunJsonPath(context.ddFlowHome, project.id, runId);
     const index = {
@@ -60,16 +57,19 @@ export function startFlowRun(context, input) {
         short_id: shortId,
         flow_kind: flowKind,
         subject: {
-            type: requiredPlain(input.subjectType, "subject-type"),
-            id: requiredPlain(input.subjectId, "subject-id")
+            id: requiredPlain(input.subjectId, "subject-id"),
+            title: requiredPlain(input.subjectId, "subject-id")
         },
         project: {
             id: project.id,
-            root: project.root
+            title: path.basename(project.root)
         },
         workspace: {
-            root: workspaceRoot,
-            run_dir: runDirRelative
+            project_root: project.root,
+            workspace_path: workspaceRoot,
+            branch: gitFacts(workspaceRoot).branch ?? "unknown",
+            base: gitFacts(workspaceRoot).head ?? "unknown",
+            manager: "official-worktrunk"
         },
         run_home: {
             storage: "dd_flow_home",
@@ -86,7 +86,7 @@ export function startFlowRun(context, input) {
         },
         stage_runs: [],
         sessions: [],
-        artifacts: [],
+        artifacts: { stage_prompt: path.join(runHome, "stage-prompt.md"), stage_report_json: path.join(runHome, "stage-report.json"), stage_report_md: path.join(runHome, "stage-report.md"), stage_report_html: path.join(runHome, "stage-report.html"), summary: path.join(runHome, "summary.md") },
         status: "running",
         verdict: "pending",
         next_action: input.nextAction ?? null,
@@ -98,12 +98,16 @@ export function startFlowRun(context, input) {
         snapshot_revision: flowFlags.snapshot_revision,
         snapshot_checksum: flowFlags.snapshot_checksum,
         reconciliation_status: "reconciled",
-        flow_flags: flowFlags
+        flow_flags: flowFlags,
+        current_stage: null,
+        attempts: [],
+        session_coverage: { status: "unavailable", expected: [], observed: [], missing: [] },
+        usage_coverage: { status: "unavailable", expected: [], observed: [], missing: [] },
+        timeline_path: "timeline.jsonl"
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
     writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, 1));
-    writeJsonFile(runIndexAbsolute, index);
     context.db.run(`INSERT INTO flow_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, artifact_root_kind,
@@ -116,14 +120,14 @@ export function startFlowRun(context, input) {
         project.root,
         workspaceRoot,
         flowKind,
-        index.subject.type,
+        requiredPlain(input.subjectType, "subject-type"),
         index.subject.id,
         index.status,
         index.verdict,
         index.next_action,
         runtimePath,
         runHome,
-        runIndexAbsolute,
+        runtimePath,
         runHome,
         "home_run_v2",
         "dd_flow_home",
@@ -152,14 +156,14 @@ export function getFlowRunStatus(context, input) {
     const run = resolveRun(context, project.id, input.runId);
     refreshRunSessionProjection(context, project.id, run.id);
     const refreshedRun = requireRunById(context, project.id, run.id);
-    const index = parseRunIndex(refreshedRun.index_json);
+    const index = authoritativeIndex(refreshedRun);
     const runtime = readRuntimeSnapshot(refreshedRun.runtime_path);
     return { ok: true, run: flowRunSummary(refreshedRun), index, ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, refreshedRun, index) };
 }
 export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const runtime = readRuntimeSnapshot(run.runtime_path);
     const flags = runtime?.flow_flags ?? index.flow_flags;
     if (!flags) {
@@ -199,7 +203,7 @@ export function reviseFlowRunFlags(context, input) {
         // Read the authority only after the write lock: two callers with the same
         // expected revision must not both pass the compare-and-set check.
         const lockedRun = requireRunById(context, project.id, run.id);
-        const index = parseRunIndex(lockedRun.index_json);
+        const index = authoritativeIndex(lockedRun);
         const runtime = readRuntimeSnapshot(lockedRun.runtime_path);
         const current = runtime?.flow_flags ?? index.flow_flags;
         if (!current) {
@@ -268,7 +272,7 @@ export function reviseFlowRunFlags(context, input) {
             flow_flags: next,
             ...(reason ? { reason } : {})
         };
-        persistRunIndex(context, project, run, index, {
+        persistRunState(context, project, run, index, {
             flagRevision: { revision: next.snapshot_revision, checksum: next.snapshot_checksum, at: now, idempotency_key: idempotencyKey }
         });
         context.db.run(`INSERT INTO flow_run_flag_mutations
@@ -310,7 +314,7 @@ export function listFlowRuns(context, input) {
 export function attachFlowRunStage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const now = context.now();
     const stage = requiredPlain(input.stage, "stage");
     const dir = requiredStageDir(input.dir);
@@ -325,13 +329,20 @@ export function attachFlowRunStage(context, input) {
         dir,
         status,
         ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : existing?.data_schema_id ? { data_schema_id: existing.data_schema_id } : {}),
-        updated_at: now,
-        ...(status === "running" && !existing?.started_at ? { started_at: now } : {}),
-        ...(status === "running" ? { attempt: nextAttempt(existing) } : {})
+        updated_at: now
     };
+    if (status === "running") {
+        stageRun.started_at = now;
+        delete stageRun.completed_at;
+        stageRun.duration_ms = null;
+        stageRun.git = gitFacts(run.workspace_root);
+        stageRun.attempt = nextAttempt(existing);
+    }
     upsertStage(index, stageRun);
+    index.current_stage = stage;
+    index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
     index.updated_at = now;
-    persistRunIndex(context, project, run, index);
+    persistRunState(context, project, run, index);
     appendAudit(context, {
         projectId: project.id,
         eventType: "flow_run.stage_attached",
@@ -354,7 +365,7 @@ export function attachFlowRunStage(context, input) {
 export function completeFlowRunStage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const now = context.now();
     const stage = requiredPlain(input.stage, "stage");
     const status = parseStageStatus(input.status);
@@ -371,11 +382,20 @@ export function completeFlowRunStage(context, input) {
         ...(input.report ? { report: input.report } : {}),
         ...(input.aliases && input.aliases.length > 0 ? { artifact_aliases: input.aliases } : {}),
         updated_at: now,
-        ...(status === "done" || status === "blocked" || status === "failed" || status === "skipped" ? { completed_at: now } : {})
+        ...(status === "done" || status === "blocked" || status === "failed" || status === "skipped"
+            ? { completed_at: now, duration_ms: durationMs(existing.started_at ?? null, now), git: gitFacts(run.workspace_root) }
+            : {})
     };
     upsertStage(index, stageRun);
+    index.current_stage = stage;
+    index.attempts = index.stage_runs.map((item) => ({ stage: item.stage, attempt_number: Number((item.attempt ?? "try-001").replace("try-", "")) || 1, root: item.dir, archive: null, status: item.status, started_at: item.started_at ?? now, finished_at: item.completed_at ?? null }));
     index.updated_at = now;
-    persistRunIndex(context, project, run, index);
+    index.execution = {
+        project_root: index.execution?.project_root ?? run.project_root,
+        workspace_root: index.execution?.workspace_root ?? run.workspace_root,
+        git: gitFacts(run.workspace_root)
+    };
+    persistRunState(context, project, run, index);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, {
         projectId: project.id,
@@ -390,7 +410,7 @@ export function completeFlowRunStage(context, input) {
 export function completeFlowRun(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const now = context.now();
     const status = parseRunStatus(input.status);
     index.status = status;
@@ -399,8 +419,15 @@ export function completeFlowRun(context, input) {
     index.updated_at = now;
     if (["done", "blocked", "cancelled", "failed"].includes(status)) {
         index.completed_at = now;
+        index.finished_at = now;
+        index.duration_ms = durationMs(index.started_at ?? run.created_at, now);
+        index.execution = {
+            project_root: index.execution?.project_root ?? run.project_root,
+            workspace_root: index.execution?.workspace_root ?? run.workspace_root,
+            git: gitFacts(run.workspace_root)
+        };
     }
-    persistRunIndex(context, project, run, index);
+    persistRunState(context, project, run, index);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, {
         projectId: project.id,
@@ -416,7 +443,7 @@ const timelineSections = ["stages", "events", "sessions", "usage", "artifacts"];
 export function getFlowRunTimeline(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    const index = parseRunIndex(run.index_json);
+    const index = authoritativeIndex(run);
     const file = path.join(runArtifactRoot(run), "timeline.jsonl");
     const events = fs.existsSync(file)
         ? fs.readFileSync(file, "utf8").split(/\r?\n/).flatMap((line) => { try {
@@ -426,7 +453,10 @@ export function getFlowRunTimeline(context, input) {
             return [];
         } })
         : [];
-    const hidden = parseHiddenTimelineSections(input.hiddenSections ?? []);
+    if ((input.hiddenSections ?? []).length > 0) {
+        throw new AppError("validation", "Timeline sections are always included", 2, { hidden_sections: input.hiddenSections });
+    }
+    const hidden = new Set();
     const sessions = index.sessions;
     const elapsedMs = durationMs(index.started_at ?? run.created_at, index.completed_at ?? null);
     const report = {
@@ -490,7 +520,7 @@ function guidanceForRun(context, run, index) {
                 protocolStage: state.stage,
                 ...(state.flow_contract ? { contract: state.flow_contract } : {}),
                 runId: run.id,
-                runDir: index.run_home?.relative_path ?? index.workspace.run_dir
+                runDir: index.run_home?.relative_path ?? path.posix.join("runs", run.id)
             });
         }
         catch (error) {
@@ -498,11 +528,10 @@ function guidanceForRun(context, run, index) {
                 throw error;
         }
     }
-    return buildRunFlowGuidance({ stageRuns: index.stage_runs, runId: run.id, runDir: index.run_home?.relative_path ?? index.workspace.run_dir });
+    return buildRunFlowGuidance({ stageRuns: index.stage_runs, runId: run.id, runDir: index.run_home?.relative_path ?? path.posix.join("runs", run.id) });
 }
-function persistRunIndex(context, project, run, index, options = {}) {
+function persistRunState(context, project, run, index, options = {}) {
     const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, project.id, run.id);
-    const runIndexPath = run.run_index_path || projectRunIndexPath(context.ddFlowHome, project.id, run.id);
     const previousRuntime = readRuntimeSnapshot(runtimePath);
     const runtimeRevision = Math.max(index.runtime_revision ?? 0, previousRuntime?.runtime_revision ?? 0) + 1;
     index.runtime_revision = runtimeRevision;
@@ -511,9 +540,7 @@ function persistRunIndex(context, project, run, index, options = {}) {
         history.push(options.flagRevision);
     }
     ensureDir(path.dirname(runtimePath));
-    ensureDir(path.dirname(runIndexPath));
     writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, runtimeRevision, history));
-    writeJsonFile(runIndexPath, index);
     context.db.run(`UPDATE flow_runs
      SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?,
        updated_at = ?, completed_at = ?
@@ -523,7 +550,7 @@ function persistRunIndex(context, project, run, index, options = {}) {
         index.next_action,
         JSON.stringify(index),
         runtimePath,
-        runIndexPath,
+        runtimePath,
         index.updated_at,
         index.completed_at ?? null,
         project.id,
@@ -539,10 +566,12 @@ function appendRunTimeline(runHome, event) {
         const last = lines.length > 0 ? JSON.parse(lines[lines.length - 1]) : undefined;
         sequence = typeof last?.sequence === "number" ? last.sequence : lines.length;
     }
+    const safeEvent = sanitizeTimelineValue(event);
     const enriched = {
         event_id: crypto.randomUUID(),
         sequence: sequence + 1,
-        ...event
+        at: typeof safeEvent.at === "string" ? safeEvent.at : new Date().toISOString(),
+        ...safeEvent
     };
     fs.appendFileSync(timelinePath, `${JSON.stringify(enriched)}\n`);
 }
@@ -552,7 +581,6 @@ function runtimeSnapshotForIndex(index, runtimeRevision, flagRevisionHistory = [
     return {
         ...rest,
         schema_id: runtimeSchemaId,
-        run_index_schema_id: index.schema_id,
         runtime_revision: runtimeRevision,
         ...(flagRevisionHistory.length > 0 ? { flag_revision_history: flagRevisionHistory.slice(-32) } : {})
     };
@@ -568,18 +596,26 @@ function readRuntimeSnapshot(file) {
         return undefined;
     }
 }
-function parseHiddenTimelineSections(values) {
-    const hidden = new Set();
-    for (const value of values) {
-        if (!timelineSections.includes(value)) {
-            throw new AppError("validation", "--hide must name a timeline section", 2, {
-                value,
-                allowed: timelineSections
-            });
-        }
-        hidden.add(value);
+function authoritativeIndex(run) {
+    const runtime = readRuntimeSnapshot(run.runtime_path);
+    if (!runtime) {
+        throw new AppError("validation", "RUN authority is missing or invalid", 2, { run_id: run.id, path: run.runtime_path });
     }
-    return hidden;
+    return { ...runtime, schema_id: runSchemaId };
+}
+function sanitizeTimelineValue(value, key) {
+    if (key && /(secret|password|authorization|cookie|api[_-]?key|private[_-]?key|access[_-]?token|refresh[_-]?token|transcript|prompt|tool[_-]?output|document[_-]?content)/i.test(key)) {
+        return "[REDACTED]";
+    }
+    if (typeof value === "string") {
+        return value.length > 512 ? `${value.slice(0, 512)}…[TRUNCATED]` : value;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => sanitizeTimelineValue(item));
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([entryKey, entryValue]) => [entryKey, sanitizeTimelineValue(entryValue, entryKey)]));
+    }
+    return value;
 }
 function durationMs(startedAt, completedAt) {
     if (!startedAt || !completedAt)
@@ -669,13 +705,6 @@ function flowRunSummary(run) {
         completed_at: run.completed_at
     };
 }
-function parseRunIndex(text) {
-    const index = JSON.parse(text);
-    if (index.schema_id !== runSchemaId && index.schema_id !== legacyRunSchemaId && index.schema_id !== oldestRunSchemaId) {
-        throw new AppError("validation", `Invalid run index schema: ${String(index.schema_id)}`, 2);
-    }
-    return index;
-}
 function parseRunFlowKind(value) {
     const normalized = value === "mb-sdlc" ? "mb_sdlc" : value;
     if (!allowedRunFlowKinds.includes(normalized)) {
@@ -763,12 +792,17 @@ function writeJsonFile(file, value) {
     fs.renameSync(tmpFile, file);
 }
 function runArtifactRoot(run) {
-    return path.dirname(run.run_index_path);
+    return run.run_home_path ?? path.dirname(run.runtime_path);
 }
 function gitFacts(workspaceRoot) {
     const read = (args) => {
         const result = spawnSync("git", ["-C", workspaceRoot, ...args.split(" ")], { encoding: "utf8" });
         return result.status === 0 ? result.stdout.trim() || null : null;
     };
-    return { branch: read("branch --show-current"), head: read("rev-parse HEAD") };
+    const status = read("status --porcelain --untracked-files=all");
+    return {
+        branch: read("branch --show-current"),
+        head: read("rev-parse HEAD"),
+        status: status === null ? "unavailable" : status.length > 0 ? "dirty" : "clean"
+    };
 }