@deksden-com/dd-flow-cli 0.9.0-beta.1 → 0.9.0-beta.100

package/dist/services/sessions.js

@@ -1,9 +1,9 @@
 import crypto from "node:crypto";
-import fs from "node:fs";
 import { continuationPolicies, flowKinds } from "../domain/contracts.js";
 import { AppError } from "../shared/errors.js";
-import { commandOption, commandPosition, parseLifecycleCommand } from "./lifecycle-command.js";
+import { hookSessionIdentity } from "./hooks.js";
 import { parseJsonObject } from "../shared/json.js";
+import { prepareTextFile } from "../cli/input-preparation.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { cancelLaneWaitersForWorker } from "./lanes.js";
@@ -11,6 +11,18 @@ import { checkpointSessionUsage } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
 import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
 import { appendFlowRunTimelineEvent } from "./runs.js";
+import { publicSessionIdentity, storageSessionId } from "./session-identity.js";
+export function publicFlowSession(context, session) {
+    const identity = publicSessionIdentity(session);
+    const parent = session.parent_session_id
+        ? context.db.get("SELECT harness, provider_session_id, session_id FROM sessions WHERE project_id = ? AND session_id = ?", [session.project_id, session.parent_session_id])
+        : null;
+    const publicFields = { ...session };
+    delete publicFields.session_id;
+    delete publicFields.provider_session_id;
+    delete publicFields.parent_session_id;
+    return { ...publicFields, harness_id: identity.harness_id, session_id: identity.session_id, parent_session: parent ? publicSessionIdentity(parent) : null };
+}
 export function recordFlowSessionObservation(context, input) {
     const duplicate = context.db.get("SELECT id FROM flow_session_segments WHERE project_id = ? AND event_key = ?", [input.projectId, input.eventKey]);
     if (duplicate)
@@ -18,8 +30,8 @@ export function recordFlowSessionObservation(context, input) {
     const open = context.db.get(`SELECT id, run_id, protocol_id FROM flow_session_segments
      WHERE project_id = ? AND session_id = ? AND ended_at IS NULL ORDER BY started_at DESC, id DESC LIMIT 1`, [input.projectId, input.sessionId]);
     const now = context.now();
-    const runId = input.runId ?? null;
-    const protocolId = input.protocolId ?? null;
+    const runId = input.runId === undefined ? open?.run_id ?? null : input.runId;
+    const protocolId = input.protocolId === undefined ? open?.protocol_id ?? null : input.protocolId;
     if (open && open.run_id === runId && open.protocol_id === protocolId) {
         return { changed: false, segment_id: open.id };
     }
@@ -30,27 +42,6 @@ export function recordFlowSessionObservation(context, input) {
      VALUES (?, ?, ?, ?, ?, NULL, ?, ?, ?)`, [input.projectId, input.sessionId, runId, protocolId, now, input.cwd ?? null, input.toolName ?? null, input.eventKey]);
     return { changed: true, segment_id: Number(result.lastInsertRowid) };
 }
-export function bindObservedFlowSession(context, project, payload, sessionId) {
-    if (resolveProjectRoot(payload.project_root) !== project.root) {
-        throw new AppError("project_mismatch", "Observed session payload project_root does not match hook cwd project", 1, {
-            expected: project.root,
-            actual: payload.project_root
-        });
-    }
-    const session = upsertFlowSession(context, project, payload, sessionId);
-    if (session.session_kind !== "orchestrator") {
-        const now = context.now();
-        for (const unit of payload.coverage_units ?? []) {
-            if (!unit.job_id)
-                continue;
-            context.db.run(`UPDATE flow_jobs SET status = 'running', worker_session_id = ?, attempts = attempts + 1, started_at = COALESCE(started_at, ?), updated_at = ?
-         WHERE project_id = ? AND run_id = ? AND job_id = ? AND status IN ('pending', 'failed')`, [session.session_id, now, now, project.id, session.run_id ?? "", unit.job_id]);
-        }
-    }
-    if (session.run_id)
-        refreshRunSessionProjection(context, project.id, session.run_id);
-    return session;
-}
 export function registerFlowJob(context, input) {
     const jobId = input.jobId ?? `JOB-${input.runId}-${input.planItemId}`.replace(/[^A-Za-z0-9_-]+/g, "-");
     const now = context.now();
@@ -64,9 +55,33 @@ export function flowJobsForRun(context, projectId, runId) {
     return context.db.all("SELECT * FROM flow_jobs WHERE project_id = ? AND run_id = ? ORDER BY plan_item_id", [projectId, runId]);
 }
 export function registerFlowSession(context, input) {
-    const payload = decodeFlowSessionPayload(input);
+    const payload = input.preparedPayload ?? prepareFlowSessionPayload(input);
     const project = requireProjectByRoot(context, resolveProjectRoot(payload.project_root));
-    const session = upsertFlowSession(context, project, payload, input.sessionId);
+    if (payload.run_id && !context.db.get("SELECT id FROM runs WHERE project_id = ? AND id = ?", [project.id, payload.run_id])) {
+        throw new AppError("not_found", `Run is not registered: ${payload.run_id}`, 1, { run_id: payload.run_id, effect: "no_effect" });
+    }
+    const identity = input.hookEventId ? hookSessionIdentity(context, project.id, input.hookEventId) : undefined;
+    if (!identity && input.sessionId && payload.provider_session_id && payload.provider_session_id !== input.sessionId) {
+        throw new AppError("validation", "--session-id conflicts with payload provider_session_id", 2);
+    }
+    const session = upsertFlowSession(context, project, identity ? {
+        ...payload, harness: identity.harness, provider_session_id: identity.providerSessionId,
+        parent_session_id: identity.parentSessionId, agent_id: identity.agentId,
+        provider: identity.provider, model: identity.model, reasoning: identity.reasoning,
+        mode: identity.mode, agent_type: identity.agentType
+    } : { ...payload, ...(input.sessionId ? { provider_session_id: input.sessionId } : {}) }, identity?.sessionId ?? input.sessionId);
+    recordFlowSessionObservation(context, { projectId: project.id, sessionId: session.session_id,
+        runId: session.run_id, protocolId: session.protocol_id, cwd: session.cwd,
+        eventKey: `session-register-${crypto.randomUUID()}` });
+    // Logical Work/job binding belongs to the successful CLI registration, never
+    // to observation of model-supplied payload by a pre-tool hook.
+    if (session.session_kind !== "orchestrator")
+        for (const unit of payload.coverage_units ?? []) {
+            if (!unit.job_id)
+                continue;
+            context.db.run(`UPDATE flow_jobs SET status = 'running', worker_session_id = ?, attempts = attempts + 1, started_at = COALESCE(started_at, ?), updated_at = ?
+       WHERE project_id = ? AND run_id = ? AND job_id = ? AND status IN ('pending', 'failed')`, [session.session_id, context.now(), context.now(), project.id, session.run_id ?? "", unit.job_id]);
+        }
     if (session.run_id)
         appendFlowRunTimelineEvent(context, project.id, session.run_id, { type: "session_bound", session_id: session.session_id });
     if (session.run_id)
@@ -86,7 +101,7 @@ export function registerFlowSession(context, input) {
         },
         ...(session.protocol_id ? { protocolId: session.protocol_id } : {})
     });
-    return { ok: true, session };
+    return { ok: true, session: publicFlowSession(context, session) };
 }
 export function getFlowSessionStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -96,7 +111,7 @@ export function getFlowSessionStatus(context, input) {
     });
     return {
         ok: true,
-        sessions,
+        sessions: sessions.map((session) => publicFlowSession(context, session)),
         coverage: reconcileSessionCoverage(sessions)
     };
 }
@@ -111,13 +126,14 @@ export function stopFlowSession(context, input) {
     markSessionStopped(context, project, session, input.reason);
     if (session.run_id)
         refreshRunSessionProjection(context, project.id, session.run_id);
-    return { ok: true, session: flowSessionById(context, project.id, input.sessionId) };
+    const updated = flowSessionById(context, project.id, input.sessionId);
+    return { ok: true, session: updated ? publicFlowSession(context, updated) : null };
 }
 export function syncFlowSessionUsage(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const session = requireFlowSession(context, project.id, input.sessionId);
     if (!session.run_id) {
-        return { ok: true, session_id: session.session_id, extraction_status: "not_observable", diagnostic: "session_not_bound_to_run" };
+        return { ok: true, session: publicSessionIdentity(session), extraction_status: "not_observable", diagnostic: "session_not_bound_to_run" };
     }
     return { ok: true, snapshot: checkpointSessionUsage(context, session, { checkpoint: "manual_sync", stage: session.current_stage }) };
 }
@@ -158,7 +174,7 @@ export function activeFlowSessionsForProject(context, projectId) {
 }
 export function flowSessionsForProject(context, projectId, filter = {}) {
     if (filter.sessionId) {
-        return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND session_id = ? ORDER BY updated_at DESC", [projectId, filter.sessionId]);
+        return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND (session_id = ? OR provider_session_id = ?) ORDER BY updated_at DESC", [projectId, filter.sessionId, filter.sessionId]);
     }
     if (filter.workerId) {
         return context.db.all("SELECT * FROM sessions WHERE project_id = ? AND worker_id = ? ORDER BY updated_at DESC", [projectId, filter.workerId]);
@@ -166,10 +182,7 @@ export function flowSessionsForProject(context, projectId, filter = {}) {
     return context.db.all("SELECT * FROM sessions WHERE project_id = ? ORDER BY updated_at DESC", [projectId]);
 }
 export function flowSessionById(context, projectId, sessionId) {
-    return context.db.get("SELECT * FROM sessions WHERE project_id = ? AND session_id = ?", [
-        projectId,
-        sessionId
-    ]);
+    return context.db.get("SELECT * FROM sessions WHERE project_id = ? AND (session_id = ? OR provider_session_id = ?)", [projectId, sessionId, sessionId]);
 }
 export function updateFlowSessionContinuation(context, projectId, sessionId, actionKey) {
     const session = flowSessionById(context, projectId, sessionId);
@@ -185,52 +198,15 @@ export function updateFlowSessionContinuation(context, projectId, sessionId, act
         refreshRunSessionProjection(context, projectId, session.run_id);
     return nextCount;
 }
-export function flowSessionPayloadFromRegisterCommand(command) {
-    const invocation = typeof command === "string" ? invocationFromCommand(command) : command;
-    if (!invocation)
-        return undefined;
-    if (invocation.operation === "stage_start")
-        return flowSessionPayloadFromStageStartCommand(invocation);
-    if (invocation.operation !== "session_register")
-        return undefined;
-    const payloadBase64 = commandOption(invocation, "payload-base64");
-    const payloadJson = commandOption(invocation, "payload-json");
-    const payloadFile = commandOption(invocation, "payload-file");
-    if (!payloadBase64 && !payloadJson && !payloadFile) {
-        return undefined;
-    }
-    return decodeFlowSessionPayload({ payloadBase64, payloadJson, payloadFile });
-}
-function flowSessionPayloadFromStageStartCommand(invocation) {
-    const projectRoot = commandOption(invocation, "project-root");
-    const stage = commandOption(invocation, "stage");
-    const run = commandPosition(invocation, 0);
-    if (!projectRoot || !stage || !run || run.startsWith("--"))
-        return undefined;
-    return {
-        project_root: projectRoot,
-        flow_kind: ["code", "implementation", "readiness", "merge"].includes(stage) ? "implementation" : "planning",
-        run_id: run,
-        protocol_id: null,
-        worker_id: null,
-        workspace_path: null,
-        continuation_policy: "go_router",
-        session_kind: "orchestrator",
-        current_stage: stage,
-        coverage_units: []
-    };
-}
-function invocationFromCommand(command) {
-    const analysis = parseLifecycleCommand(command);
-    return analysis.kind === "none" ? undefined : analysis.invocation;
-}
-function decodeFlowSessionPayload(input) {
+export function prepareFlowSessionPayload(input) {
+    if ([input.payloadFile, input.payloadBase64, input.payloadJson].filter(value => value !== undefined).length !== 1)
+        throw new AppError("usage", "session register requires exactly one of --payload-file, --payload-base64, or --payload-json", 2);
     if (input.payloadFile) {
-        return normalizeFlowSessionPayload(parseJsonObject(fs.readFileSync(input.payloadFile, "utf8"), "session payload"));
+        return normalizeFlowSessionPayload(parseJsonObject(prepareTextFile(input.payloadFile, "session payload").text, "session payload"));
     }
     if (input.payloadBase64) {
         if (/\$[A-Za-z_{(]/.test(input.payloadBase64)) {
-            throw new AppError("validation", "session register --payload-base64 must be a literal base64 value because Codex PreToolUse hooks run before shell variable expansion; use --payload-file from prompts", 2);
+            throw new AppError("validation", "session register received an unexpanded shell variable as --payload-base64; expand it before invoking the CLI or use --payload-file", 2);
         }
         return normalizeFlowSessionPayload(parseJsonObject(Buffer.from(input.payloadBase64, "base64").toString("utf8"), "session payload"));
     }
@@ -286,7 +262,12 @@ function normalizeFlowSessionPayload(payload) {
 }
 function upsertFlowSession(context, project, payload, forcedSessionId) {
     const now = context.now();
-    const sessionId = forcedSessionId ?? payload.session_id ?? payload.worker_id ?? payload.protocol_id ?? crypto.randomUUID();
+    // `sessions.session_id` is a private storage key.  The native ID is kept
+    // unchanged in provider_session_id and is always paired with its harness in
+    // public contracts.  A caller may pass a forced key only after a trusted
+    // hook has already derived it from that pair.
+    const nativeSessionId = payload.provider_session_id ?? payload.session_id ?? payload.worker_id ?? payload.protocol_id ?? crypto.randomUUID();
+    const sessionId = forcedSessionId ?? storageSessionId({ harness_id: payload.harness ?? "codex-desktop", session_id: nativeSessionId });
     const workspacePath = payload.workspace_path ?? payload.cwd ?? project.root;
     context.db.run(`INSERT INTO sessions
       (session_id, project_id, harness, provider_session_id, agent_id, provider, model, reasoning, mode, agent_type, project_root, flow_kind, status, run_id, parent_session_id, role, aspect_id, plan_item_id, session_kind, protocol_id, worker_id, workspace_path,
@@ -334,7 +315,7 @@ function upsertFlowSession(context, project, payload, forcedSessionId) {
         sessionId,
         project.id,
         payload.harness ?? "codex-desktop",
-        payload.provider_session_id ?? null,
+        nativeSessionId,
         payload.agent_id ?? null,
         payload.provider ?? null,
         payload.model ?? null,

package/dist/services/stage-blocker.js

@@ -1,19 +1,24 @@
 import { AppError } from "../shared/errors.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { requireProjectByRoot } from "./projects.js";
-import { blockFlowRunStage, unblockFlowRunStage } from "./runs.js";
+import { blockFlowRunStage, unblockFlowRunStage, prepareFlowRunStageBlock, prepareFlowRunStageUnblock } from "./runs.js";
 import { flowCommand } from "./stage-pause.js";
 import { refreshRunWorkProjection } from "./work-registry.js";
-export function blockStageForRuntime(context, input) {
+export function prepareStageRuntimeBlock(context, input) {
+    if (typeof input.code !== "string" || !input.code.trim() || typeof input.summary !== "string" || !input.summary.trim())
+        throw new AppError("validation", "stage block requires a code and summary", 2);
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const work = requireWork(context, project.id, run.id, input.workId);
     if (work.status !== "running")
         throw new AppError("invalid_work_state", "Only a running Work can be blocked", 1, { work_id: work.work_id, status: work.status });
-    if (!input.code.trim() || !input.summary.trim())
-        throw new AppError("validation", "stage block requires a code and summary", 2);
-    const state = blockFlowRunStage(context, { ...input, projectRoot });
+    const flow = prepareFlowRunStageBlock(context, { ...input, projectRoot });
+    return { projectRoot, project, work, flow };
+}
+export function blockStageForRuntime(context, input) {
+    const { projectRoot, project, work, flow } = prepareStageRuntimeBlock(context, input);
+    const state = blockFlowRunStage(context, { ...input, projectRoot }, flow);
     const now = context.now();
     context.db.run("UPDATE works SET status = 'paused', updated_at = ? WHERE work_id = ? AND status = 'running'", [now, work.work_id]);
     refreshRunWorkProjection(context, project.id, work.run_id);
@@ -30,14 +35,19 @@ export function blockStageForRuntime(context, input) {
         state
     };
 }
-export function unblockStageAfterRuntimeRepair(context, input) {
+export function prepareStageRuntimeUnblock(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const project = requireProjectByRoot(context, projectRoot);
     const run = requireRun(context, project.id, input.runId);
     const work = requireWork(context, project.id, run.id, input.workId);
     if (work.status !== "paused")
         throw new AppError("invalid_work_state", "stage unblock requires its paused Work", 1, { work_id: work.work_id, status: work.status });
-    const state = unblockFlowRunStage(context, { projectRoot, runId: work.run_id, stage: input.stage, workId: work.work_id });
+    const flow = prepareFlowRunStageUnblock(context, { ...input, projectRoot, runId: work.run_id });
+    return { projectRoot, project, work, flow };
+}
+export function unblockStageAfterRuntimeRepair(context, input) {
+    const { projectRoot, project, work, flow } = prepareStageRuntimeUnblock(context, input);
+    const state = unblockFlowRunStage(context, { projectRoot, runId: work.run_id, stage: input.stage, workId: work.work_id }, flow);
     const now = context.now();
     context.db.run("UPDATE works SET status = 'running', updated_at = ? WHERE work_id = ? AND status = 'paused'", [now, work.work_id]);
     refreshRunWorkProjection(context, project.id, work.run_id);

package/dist/services/stage-context.js

@@ -2,33 +2,42 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { parseJsonObject } from "../shared/json.js";
+import { prepareFileBytes, prepareJsonText, prepareOutputFile } from "../cli/input-preparation.js";
 export function loadExternalStageContext(input) {
-    const sourcePath = path.resolve(input.file);
-    if (!fs.existsSync(sourcePath) || !fs.statSync(sourcePath).isFile())
-        throw new AppError("not_found", "Stage context file is missing", 2, { context_file: sourcePath });
-    const bytes = fs.readFileSync(sourcePath);
+    const { file: sourcePath, bytes } = prepareFileBytes(input.file, "Stage context");
     const materializedSha256 = sha256(bytes);
     if (materializedSha256 !== input.expectedSha256)
         throw new AppError("context_checksum_mismatch", "Stage context checksum does not match --context-sha256", 2, { context_file: sourcePath, expected_sha256: input.expectedSha256, actual_sha256: materializedSha256 });
-    const value = parseJsonObject(bytes.toString("utf8"), "stage context");
+    const value = prepareJsonText(bytes.toString("utf8"), { file: sourcePath, label: "Stage context" }).value;
     validateContext(value, input.stage);
-    return { value, sourcePath, materializedSha256 };
+    return { value, sourcePath, materializedSha256, bytes };
 }
-/** Installs exactly one immutable external context for a stage attempt. */
-export function installExternalStageContext(input) {
-    fs.mkdirSync(input.stageRoot, { recursive: true });
+export function prepareExternalStageContext(input) {
+    const destination = externalStageContextDestination(input);
+    if (!fs.existsSync(destination))
+        prepareOutputFile(destination);
+    return destination;
+}
+function externalStageContextDestination(input) {
     const destination = path.join(input.stageRoot, "stage-context.json");
     if (fs.existsSync(destination)) {
         const existing = sha256(fs.readFileSync(destination));
         if (existing !== input.loaded.materializedSha256)
             throw new AppError("stage_context_replacement", "A different stage context is already installed for this Stage", 2, { stage_context: destination, expected_sha256: input.loaded.materializedSha256, actual_sha256: existing });
     }
-    else {
+    return destination;
+}
+/** Installs exactly one immutable external context for a stage attempt. */
+export function installExternalStageContext(input) {
+    // Publication may follow earlier effects. Recheck immutable identity here,
+    // but never reclassify a late output failure as a no-effect input rejection.
+    const destination = externalStageContextDestination(input);
+    fs.mkdirSync(input.stageRoot, { recursive: true });
+    if (!fs.existsSync(destination)) {
         // The receipt is the hash of the runner-materialized bytes, not of a
         // convenient reserialization.  Preserve those exact bytes as evidence.
         const temporary = `${destination}.${process.pid}.tmp`;
-        fs.copyFileSync(input.loaded.sourcePath, temporary);
+        fs.writeFileSync(temporary, input.loaded.bytes);
         fs.renameSync(temporary, destination);
     }
     return {
@@ -76,15 +85,32 @@ export function renderExternalStageContext(input) {
     ].join("\n");
 }
 function validateContext(value, expectedStage) {
-    if (value.schema_id !== "dd-eval/stage-context@1")
-        throw new AppError("validation", "Stage context must use dd-eval/stage-context@1", 2);
+    const object = (item) => Boolean(item && typeof item === "object" && !Array.isArray(item));
+    const text = (item) => typeof item === "string" && Boolean(item.trim());
+    if (!object(value))
+        throw new AppError("validation", "Stage context must be an object", 2);
+    if (value.schema_id !== "dd-flow/stage-context@1" && value.schema_id !== "dd-eval/stage-context@1")
+        throw new AppError("validation", "Stage context must use dd-flow/stage-context@1", 2);
     if (value.stage !== expectedStage)
         throw new AppError("validation", "Stage context does not match --stage", 2, { expected_stage: expectedStage, context_stage: value.stage });
-    if (!value.objective?.trim())
+    if (!text(value.objective))
         throw new AppError("validation", "Stage context objective is required", 2);
-    for (const source of value.sources ?? []) {
-        if (!source.role?.trim() || !source.path?.trim() || !source.reason?.trim())
-            throw new AppError("validation", "Every stage context source needs role, path and reason", 2);
+    for (const key of ["task_input", "sources", "accepted_decisions", "dynamic_roles"]) {
+        if (value[key] === undefined)
+            continue;
+        if (!Array.isArray(value[key]))
+            throw new AppError("validation", `Stage context ${key} must be an array`, 2);
+        for (const item of value[key]) {
+            const valid = key === "accepted_decisions" ? text(item) || object(item) && (text(item.id) || text(item.statement)) && [item.id, item.statement].every(field => field === undefined || text(field))
+                : object(item) && text(item.role) && (key === "dynamic_roles" ? item.reason === undefined || text(item.reason)
+                    : text(item.path) && (key === "sources" ? text(item.reason) && (item.required === undefined || typeof item.required === "boolean") && (item.root === undefined || typeof item.root === "string" && ["project", "workspace", "run"].includes(item.root)) : item.sha256 === undefined || text(item.sha256)));
+            if (!valid)
+                throw new AppError("validation", `Invalid stage context ${key} item`, 2, { parameter: key });
+        }
+    }
+    for (const key of ["semantic_package_sha256", "context_slice_sha256"]) {
+        if (value[key] !== undefined && !text(value[key]))
+            throw new AppError("validation", `Stage context ${key} must be a nonempty string`, 2);
     }
 }
 function sha256(value) { return crypto.createHash("sha256").update(value).digest("hex"); }