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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @deksden-com/dd-flow-cli
 
+## 0.9.0-beta.160
+
+### Patch Changes
+
+- Prepare pinned Worktrunk through a provider-free CLI and reuse its verified cache across isolated runs through the explicit resource home. Use owned installation locks, bounded native download retries and actual write progress across retries. Preserve acquisition context and refuse replay when child cleanup is unknown (plan 114).
+
 ## 0.9.0-beta.159
 
 ### Patch Changes

package/dist/build-info.json

@@ -1,8 +1,8 @@
 {
   "cli_package": "@deksden-com/dd-flow-cli",
-  "cli_version": "0.9.0-beta.159",
-  "cli_commit": "138ff716eb8e3f8e4b5c32a7556284c30e50804b",
-  "built_at": "2026-10-29T12:37:35.400Z",
+  "cli_version": "0.9.0-beta.160",
+  "cli_commit": "3d065fa9b570fdb25570e4c47d7c99a5d50d5574",
+  "built_at": "2026-10-29T15:12:42.101Z",
   "built_with_canon": {
     "version": "4.1.4",
     "commit": "7cc415b3ef3ce37c9624c7cee51023e66f67cd57",

package/dist/cli/command-inputs.js

@@ -31,6 +31,7 @@ physicalPathOptions.add("native-config-home");
 physicalPathOptions.add("operational-decision-file");
 physicalPathOptions.add("workspace");
 export const commandInputs = {
+    "tool ensure wt": route(0),
     "delivery inputs": route(1, "project-root stage"),
     "delivery checks": route(1, "project-root stage result-file", lifecycle, "", "", { stage: ["prepare", "verify"] }),
     "delivery execute": route(1, "project-root stage result-file", lifecycle, "", "", { stage: ["publish", "deploy"] }),

package/dist/cli/command-metadata.js

@@ -265,7 +265,7 @@ export function optionsForCommandTree(command) {
 }
 /** One exact native routing classification shared by router and compatibility admission. */
 export function routerNativeRoute(key) {
-    return key === "version" || key.startsWith("engine ") || key === "schema validate"
+    return key === "version" || key === "tool ensure wt" || key.startsWith("engine ") || key === "schema validate"
         || key === "flow list" || key === "flow show" || key === "flow mb-init" || key === "init" || key === "flow mb-upgrade" || key === "upgrade"
         || key === "flow mb-audit" || key === "flow project-review" || key === "flow mb-distill" || key === "flow mb-fix" || key === "flow review-fix" || key === "flow interactive" || key === "review"
         || key === "flow release" || key === "flow deploy" || key === "flow publish"

package/dist/cli/help.js

@@ -2,6 +2,15 @@ import { AppError } from "../shared/errors.js";
 import { commandInputs, commandAliases } from "./command-inputs.js";
 import { commandKeyForPositions, globalOptionDocumentation, optionsForCommandTree, routerNativeRoute } from "./command-metadata.js";
 const helpPages = new Map([
+    ["tool", `dd-flow tool ensure wt - prepare the pinned Worktrunk capability
+
+Usage:
+  dd-flow tool ensure wt --json
+
+Verifies or installs the pinned tool in explicit DD_FLOW_RESOURCE_HOME (legacy
+fallback: DD_FLOW_HOME). Uses no RUN database and starts no provider Session.
+Returns version, platform, binary/archive checksums and cache_root. Availability
+does not approve any worktree or productive action.`],
     ...["release", "deploy", "publish"].map((flow) => [`flow ${flow}`, `dd-flow flow ${flow} - start or replay one request-bound delivery RUN
 
 Usage:

package/dist/cli/run-cli.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { ensureManagedWorktrunk } from "../services/tooling.js";
 import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
 import { preparePromptDelivery, publishPromptDelivery } from "../services/prompt-delivery.js";
 import { requiredOption, optionalOption, optionalNumber, optionalPositiveNumber } from "./argument-values.js";
@@ -221,6 +222,18 @@ async function runCliRequest(args, io, env) {
             return runModelsCli(args, io);
         if (output.args[0] === "profiles")
             return runOperatorProfilesCli(args, env, io);
+        if (output.args[0] === "tool") {
+            prepareCommandRoute(output.args); // Reject unknown tools before filesystem/store effects.
+            if (output.responseFile)
+                prepareResponseDestination(output.responseFile);
+            const tool = await ensureManagedWorktrunk({ ddFlowHome: resolveDdFlowHome(env), env });
+            const payload = writeResponseFile({ ok: true, tool: "wt", ...tool, cache_root: path.dirname(tool.bin) }, output);
+            if (output.json)
+                writeJson(io.stdout, payload);
+            else
+                io.stdout.write(`${renderHumanResult(output.args, payload)}${tool.bin}\n`);
+            return 0;
+        }
         const suppliedInvocationId = optionalOption(parseArgs(output.args.slice(2)), "invocation-id");
         if (isNativeHookIngress(output.args)) {
             writeJson(io.stdout, await dispatchNativeHook(output.args, await readStdin(io.stdin), env));

package/dist/services/tooling.js

@@ -4,8 +4,9 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { commandResult, commandText } from '../harness-runtime/lib/process-json.mjs';
 import { publishSetup, SETUP_STARTUP_MS } from '../harness-runtime/lib/setup-progress.mjs';
-import { AppError, processEvidence } from "../shared/errors.js";
+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";
@@ -45,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");
@@ -78,8 +79,34 @@ export async function ensureManagedWorktrunk(context) {
     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);
@@ -90,44 +117,56 @@ export async 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."
             });
         }
-        await 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();
     }
 }
-async 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 {
-        let observedBytes = 0;
+        let marker = null, progress = 0;
         publishSetup('probe_started', 'worktrunk-download');
-        const download = await commandResult("curl", ["--fail", "--location", "--silent", "--show-error", "-o", archivePath, artifact.url], { startupMs: SETUP_STARTUP_MS, progress: () => {
-                const bytes = fs.existsSync(archivePath) ? fs.statSync(archivePath).size : 0;
-                if (bytes > observedBytes) {
-                    observedBytes = bytes;
-                    publishSetup('transfer_progress', `worktrunk-transfer:${bytes}`);
+        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}`);
                 }
-                return observedBytes;
+                marker = next;
+                return progress;
             } });
-        if (download.exit_code !== 0) {
+        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) {
@@ -140,11 +179,13 @@ async function installWorktrunkArtifact(manifest, platform, targetRoot) {
             });
         }
         ensureDir(extractedRoot);
+        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);
+        acquisitionPhase = "tool-version";
         await verifyWorktrunkVersion(extractedBinary, manifest.version);
         const binaryChecksum = sha256File(extractedBinary);
         const stagedRoot = path.join(tempRoot, "managed");
@@ -160,12 +201,36 @@ async 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) {
@@ -208,22 +273,22 @@ function verifyCachedWorktrunk(context, manifest, platform) {
 }
 export async function extractArchive(archive, destination, format) {
     if (format === "tar.xz") {
-        const listing = await commandResult("tar", ["-tJf", archive], { startupMs: SETUP_STARTUP_MS });
+        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 });
+        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 = await commandResult("unzip", ["-Z1", archive], { startupMs: SETUP_STARTUP_MS });
+    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 });
+    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) });
 }
@@ -243,7 +308,7 @@ function findBinary(root) {
     return null;
 }
 async function verifyWorktrunkVersion(bin, expected) {
-    const output = await commandText(bin, ['--version'], { startupMs: SETUP_STARTUP_MS, phase: 'native-version' });
+    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,
@@ -262,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");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.9.0-beta.159",
+  "version": "0.9.0-beta.160",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "packageManager": "pnpm@10.23.0",