@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.160

package/dist/services/stage-report-renderer.js

@@ -1,14 +1,243 @@
 import fs from "node:fs";
 import path from "node:path";
+import crypto from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { withProjectionLock } from "../storage/projection-lock.js";
 import { writeJsonAtomic } from "../storage/paths.js";
+import { assertRunBundleSqlAuthority } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+/** Accepted bytes come from SQL receipts, never from the mutable publication.
+ * Stage completion and its independent committed checksum must agree. This is
+ * byte custody, not a substitute for the registered handler's semantic gates.
+ */
+export function readAcceptedStageData(context, scope) {
+    function refuse() { throw new AppError("stage_data_custody_invalid", "Accepted stage data lacks matching committed SQL byte custody", 1, { run_id: scope.runId, stage: scope.stage }); }
+    const run = context.db.get("SELECT index_json, run_root, run_dir FROM runs WHERE project_id = ? AND id = ?", [scope.projectId, scope.runId]);
+    if (!run)
+        refuse();
+    const index = JSON.parse(run.index_json);
+    assertRunBundleSqlAuthority(context, scope, index.execution_bundle);
+    const stage = index.stage_runs?.find((item) => item.stage === scope.stage);
+    const portable = (value) => typeof value === "string" && Boolean(value) && !path.posix.isAbsolute(value) && !path.win32.isAbsolute(value) && !value.includes("\\") && !value.includes("\0") && value.split("/").every(part => Boolean(part) && part !== "." && part !== "..");
+    if (!stage || stage.status !== "done" || !portable(stage.dir) || !portable(stage.data)
+        || typeof stage.attempt !== "string" || !/^try-[0-9]{3,}$/.test(stage.attempt)
+        || typeof stage.data_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(stage.data_sha256))
+        refuse();
+    const root = run.run_root ?? run.run_dir;
+    if (!path.isAbsolute(root))
+        refuse();
+    const relative = `${stage.dir}/${stage.data}`, destination = path.resolve(root, relative);
+    const rows = context.db.all("SELECT event_type, payload_json FROM audit_events WHERE project_id = ? AND event_type IN ('flow_run.stage_packet', 'flow_run.stage_report') AND json_extract(payload_json, '$.run_id') = ? AND json_extract(payload_json, '$.stage') = ? AND json_extract(payload_json, '$.attempt') = ? AND json_extract(payload_json, '$.sha256') = ?", [scope.projectId, scope.runId, scope.stage, stage.attempt, stage.data_sha256]);
+    let accepted;
+    for (const row of rows) {
+        const receipt = JSON.parse(row.payload_json);
+        if (receipt.sha256 !== stage.data_sha256)
+            continue;
+        const locator = row.event_type === "flow_run.stage_packet" ? receipt.file : typeof receipt.root === "string" ? path.join(receipt.root, "stage-report.json") : null;
+        if (typeof locator !== "string" || resolveStagePublicationPath(context, scope.projectId, scope.runId, locator) !== destination)
+            continue;
+        let bytes;
+        if (row.event_type === "flow_run.stage_packet") {
+            if (typeof receipt.base64 !== "string")
+                refuse();
+            bytes = Buffer.from(receipt.base64, "base64");
+            if (bytes.toString("base64") !== receipt.base64)
+                refuse();
+        }
+        else {
+            if (typeof receipt.bytes?.json !== "string")
+                refuse();
+            bytes = Buffer.from(receipt.bytes.json);
+        }
+        if (!bytes.length || crypto.createHash("sha256").update(bytes).digest("hex") !== stage.data_sha256)
+            refuse();
+        if (accepted && !accepted.equals(bytes))
+            refuse();
+        accepted = bytes;
+    }
+    if (!accepted)
+        refuse();
+    return { bytes: Buffer.from(accepted), result: { path: relative, sha256: stage.data_sha256 },
+        input_sha256: stage.input_sha256, data_schema_id: stage.data_schema_id,
+        authority_sha256: hybridDigest({ scope, attempt: stage.attempt, directory: stage.dir, data: stage.data,
+            input_sha256: stage.input_sha256 ?? null, data_schema_id: stage.data_schema_id ?? null,
+            anchor: index.execution_bundle ?? null, data_sha256: stage.data_sha256 }) };
+}
 /** Deterministic JSON -> Markdown/HTML projection shared by every stage. */
 export function writeStageReport(root, report) {
     const json = path.join(root, "stage-report.json");
     const markdown = path.join(root, "stage-report.md");
     const html = path.join(root, "stage-report.html");
+    const normalized = normalizeStageReport(report);
+    writeJsonAtomic(json, normalized);
+    const text = renderStageReportMarkdown(normalized);
+    fs.writeFileSync(markdown, text);
+    fs.writeFileSync(html, renderStageReportHtml(normalized, text));
+    return { json, markdown, html };
+}
+export function prepareStageReport(report) {
+    const normalized = normalizeStageReport(report);
+    const json = `${JSON.stringify(normalized, null, 2)}\n`;
+    const markdown = renderStageReportMarkdown(normalized);
+    const html = renderStageReportHtml(normalized, markdown);
+    return { normalized, bytes: { json, markdown, html }, sha256: crypto.createHash("sha256").update(json).digest("hex") };
+}
+export function prepareStagePacket(file, bytes) {
+    if (fs.existsSync(file) && !bytes.equals(fs.readFileSync(file)))
+        throw new AppError("stage_packet_conflict", "An existing Stage packet differs from prepared bytes", 2, { file });
+    return { file, bytes, sha256: crypto.createHash("sha256").update(bytes).digest("hex") };
+}
+export function acceptStagePacket(context, input) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const index = run ? JSON.parse(run.index_json) : null;
+    const attempt = index?.stage_runs?.find((item) => item.stage === input.stage)?.attempt;
+    if (!attempt)
+        throw new AppError("stage_packet_owner_missing", "Stage packet has no owning attempt", 1, { run_id: input.runId, stage: input.stage });
+    const payload = { run_id: input.runId, stage: input.stage, attempt, file: input.prepared.file, sha256: input.prepared.sha256, base64: input.prepared.bytes.toString("base64") };
+    context.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.stage_packet', 0, ?, ?)", [input.projectId, JSON.stringify(payload), context.now()]);
+    context.db.afterCommit(() => publishStagePacket(context, input.projectId, input.runId, input.stage, input.prepared.file));
+}
+export function publishStagePacket(context, projectId, runId, stage, file) {
+    file = resolveStagePublicationPath(context, projectId, runId, file);
+    assertPublicationPath(context, projectId, runId, file);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    withProjectionLock(`${file}.publish-lock`, () => {
+        assertPublicationPath(context, projectId, runId, file);
+        const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        const index = run ? JSON.parse(run.index_json) : null;
+        const currentAttempt = index?.stage_runs?.find((item) => item.stage === stage)?.attempt;
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' ORDER BY id DESC", [projectId]);
+        const packet = rows.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.attempt === currentAttempt && resolveStagePublicationPath(context, projectId, runId, item.file) === file);
+        if (!packet)
+            return;
+        const bytes = Buffer.from(packet.base64, "base64");
+        if (crypto.createHash("sha256").update(bytes).digest("hex") !== packet.sha256)
+            throw new AppError("stage_packet_invalid", "Stored Stage packet hash does not match its bytes", 1, { file });
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        try {
+            fs.writeFileSync(file, bytes, { flag: "wx" });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (!bytes.equals(fs.readFileSync(file)))
+                throw new AppError("stage_packet_conflict", "Accepted Stage packet differs from the published file", 1, { file, run_id: runId, stage, attempt: currentAttempt });
+        }
+    });
+}
+/** SQL receipt and exact bytes are committed with the owning Stage transition. */
+export function acceptStageReport(context, input) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const index = run ? JSON.parse(run.index_json) : null;
+    const attempt = index?.stage_runs?.find((item) => item.stage === input.stage)?.attempt;
+    if (!attempt)
+        throw new AppError("stage_report_owner_missing", "Stage report has no owning attempt", 1, { run_id: input.runId, stage: input.stage });
+    const payload = { run_id: input.runId, stage: input.stage, attempt, root: input.root, sha256: input.prepared.sha256, bytes: input.prepared.bytes };
+    context.db.run("INSERT INTO audit_events (project_id, event_type, forced, payload_json, created_at) VALUES (?, 'flow_run.stage_report', 0, ?, ?)", [input.projectId, JSON.stringify(payload), context.now()]);
+    context.db.afterCommit(() => publishStageReport(context, input.projectId, input.runId, input.stage, input.root));
+}
+/** Replays the latest committed receipt, never an obsolete attempt. */
+export function publishStageReport(context, projectId, runId, stage, root) {
+    root = resolveStagePublicationPath(context, projectId, runId, root);
+    assertPublicationPath(context, projectId, runId, root);
+    withProjectionLock(`${root}.report-publish-lock`, () => {
+        assertPublicationPath(context, projectId, runId, root);
+        const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+        const index = run ? JSON.parse(run.index_json) : null;
+        const currentAttempt = index?.stage_runs?.find((item) => item.stage === stage)?.attempt;
+        const events = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_report' ORDER BY id DESC", [projectId]);
+        const receipt = events.map((row) => JSON.parse(row.payload_json)).find((item) => item.run_id === runId && item.stage === stage && item.attempt === currentAttempt && resolveStagePublicationPath(context, projectId, runId, item.root) === root);
+        if (!receipt)
+            return;
+        fs.mkdirSync(root, { recursive: true });
+        for (const [name, bytes] of Object.entries(receipt.bytes)) {
+            const file = path.join(root, `stage-report.${name === "json" ? "json" : name === "markdown" ? "md" : "html"}`);
+            assertPublicationPath(context, projectId, runId, file);
+            try {
+                fs.writeFileSync(file, bytes, { flag: "wx" });
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                if (fs.readFileSync(file, "utf8") !== bytes)
+                    throw new AppError("stage_report_conflict", "Accepted Stage report differs from the published file", 1, { run_id: runId, stage, attempt: currentAttempt, file });
+            }
+        }
+    });
+}
+/** Operational destinations follow validated imports, while audit bytes retain
+ * their original locators. SQL-only so readers may also use it in settlement. */
+export function resolveStagePublicationPath(context, projectId, runId, locator) {
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run?.run_root || !path.isAbsolute(locator))
+        throw new AppError("stage_packet_invalid", "Stage publication has no absolute bound RUN locator", 1, { run_id: runId, locator });
+    let destination = path.resolve(locator);
+    const mappings = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.publication_relocation' ORDER BY id", [projectId]);
+    for (const row of mappings) {
+        const mapping = JSON.parse(row.payload_json);
+        if (mapping.run_id !== runId || !path.isAbsolute(mapping.from) || !path.isAbsolute(mapping.to))
+            continue;
+        const relative = path.relative(mapping.from, destination);
+        if (relative && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+            destination = path.resolve(mapping.to, relative);
+    }
+    const relative = path.relative(run.run_root, destination);
+    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        throw new AppError("publication_pending", "Stage publication escaped its bound RUN lineage", 1, { effect: "committed", run_id: runId, locator });
+    return destination;
+}
+/** Recheck the actual destination after preparation: a missing leaf may have
+ * an existing symlink ancestor, and retained packet bytes never authorize it. */
+function assertPublicationPath(context, projectId, runId, file) {
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const root = run?.run_root && path.resolve(run.run_root), destination = path.resolve(file);
+    if (!root || !destination.startsWith(`${root}${path.sep}`))
+        throw new AppError("publication_pending", "Stage publication escaped its RUN", 1, { effect: "committed", run_id: runId, file });
+    let ancestor = destination;
+    while (!fs.existsSync(ancestor) && ancestor !== root)
+        ancestor = path.dirname(ancestor);
+    const actual = fs.realpathSync(ancestor), realRoot = fs.realpathSync(root);
+    if (actual !== realRoot && !actual.startsWith(`${realRoot}${path.sep}`))
+        throw new AppError("publication_pending", "Stage publication escaped its RUN through a symlink", 1, { effect: "committed", run_id: runId, file });
+}
+/** Admission repair for predecessor reports; the stage being retried is archived separately. */
+export function reconcileRunStageReports(context, projectId, runId, exceptStage) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_report' ORDER BY id DESC", [projectId]);
+    const seen = new Set();
+    for (const row of rows) {
+        const receipt = JSON.parse(row.payload_json);
+        if (receipt.run_id !== runId || typeof receipt.stage !== "string" || typeof receipt.root !== "string" || receipt.stage === exceptStage || seen.has(receipt.stage))
+            continue;
+        seen.add(receipt.stage);
+        publishStageReport(context, projectId, runId, receipt.stage, receipt.root);
+    }
+    const packets = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' ORDER BY id DESC", [projectId]);
+    const packetFiles = new Set();
+    for (const row of packets) {
+        const packet = JSON.parse(row.payload_json);
+        if (packet.run_id !== runId || typeof packet.stage !== "string" || typeof packet.file !== "string" || packet.stage === exceptStage || packetFiles.has(packet.file))
+            continue;
+        packetFiles.add(packet.file);
+        publishStagePacket(context, projectId, runId, packet.stage, packet.file);
+    }
+}
+function normalizeStageReport(report) {
     const semantic = object(report.semantic);
+    if (semantic.materialization !== undefined) {
+        const value = object(semantic.materialization);
+        const authored = object(value.authored_result);
+        const relative = (item) => typeof item === "string" && item.length > 0 && !path.isAbsolute(item) && !item.split(/[\\/]/).includes("..");
+        if (value.schema_id !== "dd-flow/protocolize-materialization@1" || value.run_id !== report.run_id || report.stage !== "protocolize" || value.stage !== "protocolize"
+            || !["create", "link", "update", "not_applicable"].includes(String(value.action)) || value.status !== "passed"
+            || authored.role !== "authored_input" || !relative(authored.run_relative_path) || !/^[a-f0-9]{64}$/.test(String(authored.sha256))
+            || !(value.feature_path === null || relative(value.feature_path)) || !Array.isArray(value.protocol_ids) || value.protocol_ids.some(id => typeof id !== "string")
+            || !Array.isArray(value.documents) || value.documents.some(item => { const ref = object(item); return !relative(ref.path) || !/^[a-f0-9]{64}$/.test(String(ref.sha256)); })
+            || !Array.isArray(value.owned_links) || value.owned_links.some(item => { const edge = object(item); return !relative(edge.feature_path) || !relative(edge.protocol_path) || !value.protocol_ids.includes(edge.protocol_id); })) {
+            throw new AppError("stage_report_materialization_invalid", "PROTOCOLIZE materialization receipt is malformed or out of scope", 1);
+        }
+    }
     const sourceArtifacts = object(report.artifacts);
-    const normalized = {
+    return {
         ...report,
         schema_id: "dd-flow/stage-report@2",
         summary: string(report.summary) || string(semantic.result) || "Stage completed.",
@@ -27,11 +256,6 @@ export function writeStageReport(root, report) {
             html: string(sourceArtifacts.html) || "stage-report.html"
         }
     };
-    writeJsonAtomic(json, normalized);
-    const text = renderStageReportMarkdown(normalized);
-    fs.writeFileSync(markdown, text);
-    fs.writeFileSync(html, renderStageReportHtml(normalized, text));
-    return { json, markdown, html };
 }
 export function renderStageReportMarkdown(report) {
     const semantic = object(report.semantic);

package/dist/services/stage-work-graph.js

@@ -0,0 +1,52 @@
+import { AppError } from "../shared/errors.js";
+export function stageAttempt(context, projectId, runId, stage) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run)
+        throw new AppError("not_found", "Stage graph RUN is unavailable", 1);
+    const stages = JSON.parse(run.index_json).stage_runs ?? [];
+    return [...stages].reverse().find(item => item.stage === stage)?.attempt ?? "try-001";
+}
+export function bindStageWork(context, input) {
+    context.db.writeTransaction(() => bindStageWorkOwned(context, input), "stage-work.bind");
+}
+function bindStageWorkOwned(context, input) {
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    const index = run ? JSON.parse(run.index_json) : null;
+    if (index?.execution_bundle) {
+        // Stage attachment already admitted the frozen descriptor outside the writer.
+        // Membership checks here consume only authoritative SQLite facts.
+        const stage = index.stage_runs.find(item => item.stage === input.stage && item.status === "running");
+        const work = context.db.get("SELECT parent_work_id FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [input.projectId, input.runId, input.workId]);
+        const parentOwned = !work?.parent_work_id || context.db.get("SELECT 1 FROM works WHERE project_id = ? AND run_id = ? AND work_id = ?", [input.projectId, input.runId, work.parent_work_id]);
+        const currentStage = index.current_stage ?? (index.execution_bundle.flow_id === "sdlc" ? index.stage_runs.at(-1)?.stage : undefined);
+        if (!stage || currentStage !== input.stage || !work || !parentOwned || input.attempt !== undefined && input.attempt !== (stage.attempt ?? "try-001")
+            || input.cycle !== undefined && input.cycle !== stageCycle(context, input.projectId, input.runId, input.stage)) {
+            throw new AppError("stage_work_scope_invalid", "Work membership does not belong to the active frozen stage scope", 1, { run_id: input.runId, stage: input.stage, work_id: input.workId });
+        }
+    }
+    context.db.run("INSERT OR IGNORE INTO stage_work_memberships (project_id, run_id, work_id, stage, attempt, cycle) VALUES (?, ?, ?, ?, ?, ?)", [input.projectId, input.runId, input.workId, input.stage, input.attempt ?? stageAttempt(context, input.projectId, input.runId, input.stage), input.cycle ?? stageCycle(context, input.projectId, input.runId, input.stage)]);
+}
+export function stageCycle(context, projectId, runId, stage) {
+    if (stage !== "code" && stage !== "code-review")
+        return "";
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const cycle = row ? JSON.parse(row.index_json).variables?.["merge.source_repair"]?.cycle : undefined;
+    return typeof cycle === "string" ? cycle : stage === "code-review" ? "initial" : "";
+}
+export function stageWorkIds(context, projectId, runId, stage) {
+    if (!context.db.get("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'stage_work_memberships'"))
+        throw new AppError("stage_graph_compatibility_required", "Stage Work membership is unavailable; use the RUN's pinned engine", 1);
+    return new Set(context.db.all("SELECT work_id FROM stage_work_memberships WHERE project_id = ? AND run_id = ? AND stage = ? AND attempt = ? AND cycle = ?", [projectId, runId, stage, stageAttempt(context, projectId, runId, stage), stageCycle(context, projectId, runId, stage)]).map(row => row.work_id));
+}
+/** Generic Work APIs also serve non-stage runs; null preserves that contract. */
+export function currentStageWorkIds(context, projectId, runId) {
+    const row = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!row)
+        return null;
+    const index = JSON.parse(row.index_json);
+    const stage = [...(index.stage_runs ?? [])].reverse().find(item => item.status === "running")?.stage;
+    return stage ? stageWorkIds(context, projectId, runId, stage) : null;
+}
+export function stageGraphScope(context, projectId, runId, stage) {
+    return { project_id: projectId, run_id: runId, attempt: stageAttempt(context, projectId, runId, stage), cycle: stageCycle(context, projectId, runId, stage) };
+}

package/dist/services/technical-notes.js

@@ -0,0 +1,31 @@
+import crypto from "node:crypto";
+import { appendNoteTimeline } from "./run-timeline.js";
+/** Optional operational evidence never replaces a committed semantic outcome. */
+export function recordTechnicalNote(context, projectId, runId, input) {
+    const id = crypto.createHash("sha256").update(JSON.stringify([runId, input.generation, input.stage ?? null,
+        input.work_id ?? null, input.phase, input.source_operation_id ?? null, input.code, input.resource_identity ?? null])).digest("hex");
+    try {
+        const previous = readTechnicalNotes(context, projectId, runId).find(note => note.id === id);
+        if (input.state === "resolved" && !previous)
+            return;
+        const now = context.now(), note = { ...input, id, run_id: runId, state: input.state ?? "open",
+            first_seen: previous?.first_seen ?? now, last_seen: now };
+        if (previous?.state === note.state && previous.consequence === note.consequence)
+            return;
+        appendNoteTimeline(context, projectId, runId, { type: note.state === "resolved" ? "technical_note_resolved" : "technical_note_recorded", note });
+    }
+    catch {
+        // Do not copy arbitrary provider messages, environment or transcript here.
+        process.stderr.write(`${JSON.stringify({ event: "technical_note_persistence_unavailable", run_id: runId, code: input.code, phase: input.phase, note_id: id })}\n`);
+    }
+}
+export function readTechnicalNotes(context, projectId, runId) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.timeline' AND json_extract(payload_json, '$.run_id') = ? ORDER BY id", [projectId, runId]);
+    const notes = new Map();
+    for (const row of rows) {
+        const event = JSON.parse(row.payload_json).event;
+        if (["technical_note_recorded", "technical_note_resolved"].includes(event?.type ?? "") && event.note?.id)
+            notes.set(event.note.id, event.note);
+    }
+    return [...notes.values()];
+}

package/dist/services/tooling.js

@@ -2,9 +2,11 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawnSync } from "node:child_process";
-import { AppError } from "../shared/errors.js";
+import { commandResult, commandText } from '../harness-runtime/lib/process-json.mjs';
+import { publishSetup, SETUP_STARTUP_MS } from '../harness-runtime/lib/setup-progress.mjs';
+import { AppError, errorRecord, processEvidence } from "../shared/errors.js";
 import { ensureDir } from "../storage/paths.js";
+import { acquireInstallationLock } from "./installation-lock.js";
 const manifestRelativePath = path.join("tools", "worktrunk-manifest.json");
 const managedToolRootName = "wt";
 const manifestSchemaId = "dd-flow/managed-tool-manifest@1";
@@ -44,7 +46,7 @@ export function worktrunkPlatform() {
     });
 }
 export function worktrunkCacheRoot(context, platform = worktrunkPlatform()) {
-    return path.join(context.ddFlowHome, "tools", managedToolRootName, worktrunkManifest().version, platform);
+    return path.join(path.resolve(context.env.DD_FLOW_RESOURCE_HOME || context.ddFlowHome), "tools", managedToolRootName, worktrunkManifest().version, platform);
 }
 export function worktrunkCacheBinary(context, platform = worktrunkPlatform()) {
     return path.join(worktrunkCacheRoot(context, platform), process.platform === "win32" ? "wt.exe" : "wt");
@@ -71,14 +73,40 @@ export function inspectManagedWorktrunk(context) {
         };
     }
 }
-export function ensureManagedWorktrunk(context) {
+export async function ensureManagedWorktrunk(context) {
     const manifest = worktrunkManifest();
     const platform = worktrunkPlatform();
     const cachedRoot = worktrunkCacheRoot(context, platform);
     if (fs.existsSync(cachedRoot))
         return verifyCachedWorktrunk(context, manifest, platform);
-    const lockDir = `${cachedRoot}.lock`;
-    acquireLock(lockDir);
+    ensureDir(path.dirname(cachedRoot));
+    const lockFile = `${cachedRoot}.lock`;
+    const identity = crypto.createHash("sha256").update(JSON.stringify([manifest.tool, manifest.version, platform, artifactFor(manifest, platform).sha256])).digest("hex");
+    let lock;
+    try {
+        lock = acquireInstallationLock(lockFile, identity);
+    }
+    catch (cause) {
+        if (fs.existsSync(cachedRoot))
+            return verifyCachedWorktrunk(context, manifest, platform);
+        if (!(cause instanceof AppError) || cause.code !== "installation_locked")
+            throw cause;
+        throw new AppError("tool_install_pending", "Pinned Worktrunk installation requires its current owner", 1, { tool: manifest.tool, version: manifest.version, platform, cache_root: cachedRoot, lock_file: lockFile,
+            phase: "prepare", effect: "no_effect", recoverable: false, cause: errorRecord(cause) });
+    }
+    let primary;
+    const release = () => {
+        try {
+            lock.release();
+        }
+        catch (cause) {
+            if (!primary || typeof primary !== "object")
+                throw cause;
+            Object.assign(primary, { cleanup_error: errorRecord(cause) });
+            if (primary instanceof AppError)
+                Object.assign(primary.details, { recoverable: false, lock_cleanup_error: errorRecord(cause) });
+        }
+    };
     try {
         if (fs.existsSync(cachedRoot))
             return verifyCachedWorktrunk(context, manifest, platform);
@@ -89,35 +117,57 @@ export function ensureManagedWorktrunk(context) {
                 platform,
                 cache_root: cachedRoot,
                 artifact_url: artifactFor(manifest, platform).url,
+                phase: "prepare", effect: "no_effect", recoverable: true,
                 next_action: "Place the verified official artifact in the managed tool cache and retry."
             });
         }
-        installWorktrunkArtifact(manifest, platform, cachedRoot);
+        await installWorktrunkArtifact(manifest, platform, cachedRoot, lock.assertOwnership);
         return verifyCachedWorktrunk(context, manifest, platform);
     }
+    catch (cause) {
+        primary = cause;
+        throw cause;
+    }
     finally {
-        fs.rmSync(lockDir, { recursive: true, force: true });
+        release();
     }
 }
-function installWorktrunkArtifact(manifest, platform, targetRoot) {
+async function installWorktrunkArtifact(manifest, platform, targetRoot, assertOwnership) {
     const artifact = artifactFor(manifest, platform);
     const parent = path.dirname(targetRoot);
     ensureDir(parent);
     const tempRoot = fs.mkdtempSync(path.join(parent, `.wt-${process.pid}-`));
     const archivePath = path.join(tempRoot, `worktrunk.${artifact.archive}`);
     const extractedRoot = path.join(tempRoot, "extracted");
+    let acquisitionPhase = "tool-download", cleanupSafe = true;
     try {
-        const download = spawnSync("curl", ["--fail", "--location", "--silent", "--show-error", "--max-time", "120", "-o", archivePath, artifact.url], { encoding: "utf8" });
-        if (download.status !== 0) {
+        let marker = null, progress = 0;
+        publishSetup('probe_started', 'worktrunk-download');
+        const download = await commandResult("curl", ["--fail", "--location", "--silent", "--show-error", "--retry", "2", "--retry-delay", "1", "--retry-connrefused", "--connect-timeout", "30", "-o", archivePath, artifact.url], { startupMs: SETUP_STARTUP_MS, phase: acquisitionPhase, progress: () => {
+                const stat = fs.statSync(archivePath, { bigint: true, throwIfNoEntry: false });
+                const next = stat ? `${stat.size}:${stat.mtimeNs}` : null;
+                if (next !== marker && stat && stat.size > 0n) {
+                    progress++;
+                    publishSetup('transfer_progress', `worktrunk-transfer:${progress}`);
+                }
+                marker = next;
+                return progress;
+            } });
+        if (download.exit_code !== 0 || download.signal) {
             throw new AppError("tool_unavailable", "Unable to download the pinned Worktrunk artifact", 1, {
                 tool: manifest.tool,
                 version: manifest.version,
                 platform,
                 artifact_url: artifact.url,
+                cache_root: targetRoot, acquisition_phase: acquisitionPhase,
+                phase: "prepare", effect: "no_effect", recoverable: true,
+                process: processEvidence(download),
                 stdout: sanitize(download.stdout),
                 stderr: sanitize(download.stderr)
             });
         }
+        acquisitionPhase = "tool-archive-verification";
+        publishSetup('probe_completed', 'worktrunk-download');
         const archiveChecksum = sha256File(archivePath);
         if (archiveChecksum !== artifact.sha256) {
             throw new AppError("tool_integrity_failed", "Pinned Worktrunk artifact checksum mismatch", 1, {
@@ -129,12 +179,14 @@ function installWorktrunkArtifact(manifest, platform, targetRoot) {
             });
         }
         ensureDir(extractedRoot);
-        extractArchive(archivePath, extractedRoot, artifact.archive);
+        acquisitionPhase = "tool-extraction";
+        await extractArchive(archivePath, extractedRoot, artifact.archive);
         const extractedBinary = findBinary(extractedRoot);
         if (!extractedBinary)
             throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive does not contain wt", 1, { platform });
         fs.chmodSync(extractedBinary, 0o755);
-        verifyWorktrunkVersion(extractedBinary, manifest.version);
+        acquisitionPhase = "tool-version";
+        await verifyWorktrunkVersion(extractedBinary, manifest.version);
         const binaryChecksum = sha256File(extractedBinary);
         const stagedRoot = path.join(tempRoot, "managed");
         ensureDir(stagedRoot);
@@ -149,12 +201,36 @@ function installWorktrunkArtifact(manifest, platform, targetRoot) {
             archive_sha256: artifact.sha256,
             binary_sha256: binaryChecksum
         }, null, 2)}\n`);
+        assertOwnership();
         if (fs.existsSync(targetRoot))
             throw new AppError("tool_integrity_failed", "Managed Worktrunk cache appeared during installation", 1, { cache_root: targetRoot });
         fs.renameSync(stagedRoot, targetRoot);
     }
+    catch (cause) {
+        const cleanupError = cause?.cleanup_error;
+        cleanupSafe = !cleanupError && (cause instanceof AppError || cause?.code === "command_observation_lost");
+        if (cause?.code === "command_observation_lost") {
+            throw new AppError("tool_unavailable", "Pinned Worktrunk acquisition lost command observation", 1, { tool: manifest.tool, version: manifest.version, platform, artifact_url: artifact.url, cache_root: targetRoot,
+                acquisition_phase: acquisitionPhase, phase: "prepare", effect: cleanupError ? "unknown" : "no_effect",
+                recoverable: !cleanupError, cause: errorRecord(cause), ...(cleanupError ? { cleanup_error: errorRecord(cleanupError), staging_root: tempRoot } : {}) });
+        }
+        if (cause instanceof AppError) {
+            throw new AppError(cause.code, cause.message, cause.exitCode, {
+                tool: manifest.tool, version: manifest.version, platform, artifact_url: artifact.url, cache_root: targetRoot,
+                acquisition_phase: acquisitionPhase, phase: "prepare", effect: "no_effect", recoverable: false,
+                ...cause.details,
+                ...(cleanupError ? { effect: "unknown", recoverable: false, cleanup_error: errorRecord(cleanupError), staging_root: tempRoot } : {})
+            });
+        }
+        throw new AppError("tool_unavailable", "Pinned Worktrunk acquisition did not complete", 1, {
+            tool: manifest.tool, version: manifest.version, platform, artifact_url: artifact.url, cache_root: targetRoot,
+            acquisition_phase: acquisitionPhase, phase: "prepare", effect: "unknown", recoverable: false,
+            staging_root: tempRoot, cause: errorRecord(cause), ...(cleanupError ? { cleanup_error: errorRecord(cleanupError) } : {})
+        });
+    }
     finally {
-        fs.rmSync(tempRoot, { recursive: true, force: true });
+        if (cleanupSafe)
+            fs.rmSync(tempRoot, { recursive: true, force: true });
     }
 }
 function verifyCachedWorktrunk(context, manifest, platform) {
@@ -186,7 +262,7 @@ function verifyCachedWorktrunk(context, manifest, platform) {
             actual_binary_sha256: actualBinaryChecksum
         });
     }
-    verifyWorktrunkVersion(bin, manifest.version);
+    // The admitted binary checksum binds the version probe performed at install.
     return {
         bin,
         version: manifest.version,
@@ -195,24 +271,26 @@ function verifyCachedWorktrunk(context, manifest, platform) {
         binary_sha256: actualBinaryChecksum
     };
 }
-function extractArchive(archive, destination, format) {
+export async function extractArchive(archive, destination, format) {
     if (format === "tar.xz") {
-        const listing = spawnSync("tar", ["-tJf", archive], { encoding: "utf8" });
-        if (listing.status !== 0 || listing.stdout.split("\n").some(unsafeArchivePath)) {
-            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe or unreadable file list", 1);
-        }
-        const extracted = spawnSync("tar", ["-xJf", archive, "-C", destination], { encoding: "utf8" });
-        if (extracted.status !== 0)
-            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { stderr: sanitize(extracted.stderr) });
+        const listing = await commandResult("tar", ["-tJf", archive], { startupMs: SETUP_STARTUP_MS, phase: "tool-archive-list" });
+        if (listing.exit_code !== 0 || listing.signal)
+            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive listing failed", 1, { process: processEvidence(listing) });
+        if (listing.stdout.split("\n").some(unsafeArchivePath))
+            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe file list", 1, { phase: "archive_path_validation" });
+        const extracted = await commandResult("tar", ["-xJvf", archive, "-C", destination], { startupMs: SETUP_STARTUP_MS, phase: "tool-extraction" });
+        if (extracted.exit_code !== 0 || extracted.signal)
+            throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { process: processEvidence(extracted) });
         return;
     }
-    const listing = spawnSync("unzip", ["-Z1", archive], { encoding: "utf8" });
-    if (listing.status !== 0 || listing.stdout.split("\n").some(unsafeArchivePath)) {
-        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe or unreadable file list", 1);
-    }
-    const extracted = spawnSync("unzip", ["-q", archive, "-d", destination], { encoding: "utf8" });
-    if (extracted.status !== 0)
-        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { stderr: sanitize(extracted.stderr) });
+    const listing = await commandResult("unzip", ["-Z1", archive], { startupMs: SETUP_STARTUP_MS, phase: "tool-archive-list" });
+    if (listing.exit_code !== 0 || listing.signal)
+        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive listing failed", 1, { process: processEvidence(listing) });
+    if (listing.stdout.split("\n").some(unsafeArchivePath))
+        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive has an unsafe file list", 1, { phase: "archive_path_validation" });
+    const extracted = await commandResult("unzip", [archive, "-d", destination], { startupMs: SETUP_STARTUP_MS, phase: "tool-extraction" });
+    if (extracted.exit_code !== 0 || extracted.signal)
+        throw new AppError("tool_integrity_failed", "Pinned Worktrunk archive extraction failed", 1, { process: processEvidence(extracted) });
 }
 function findBinary(root) {
     const expected = process.platform === "win32" ? "wt.exe" : "wt";
@@ -229,13 +307,11 @@ function findBinary(root) {
     }
     return null;
 }
-function verifyWorktrunkVersion(bin, expected) {
-    const result = spawnSync(bin, ["--version"], { encoding: "utf8" });
-    const output = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
-    if (result.status !== 0 || !output.includes(expected)) {
+async function verifyWorktrunkVersion(bin, expected) {
+    const output = await commandText(bin, ['--version'], { startupMs: SETUP_STARTUP_MS, phase: 'tool-version' });
+    if (!output.includes(expected)) {
         throw new AppError("tool_integrity_failed", "Managed Worktrunk version verification failed", 1, {
             expected_version: expected,
-            status: result.status,
             output: sanitize(output)
         });
     }
@@ -251,15 +327,6 @@ function validateManifest(value, file) {
         throw new AppError("tool_manifest_invalid", `Managed Worktrunk manifest is invalid: ${file}`, 1, { manifest: file });
     }
 }
-function acquireLock(lockDir) {
-    ensureDir(path.dirname(lockDir));
-    try {
-        fs.mkdirSync(lockDir);
-    }
-    catch {
-        throw new AppError("tool_install_locked", "Another Worktrunk installation is in progress", 1, { lock_dir: lockDir });
-    }
-}
 function sha256File(file) {
     return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
 }