@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.140

package/dist/services/workspace-bootstrap.js

@@ -2,39 +2,65 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { AppError } from "../shared/errors.js";
-import { codeExecutionEnvironment, runCheck } from "./code-checks.js";
-import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedOwnerIsAlive, managedProcessStatus, processTreeIsAlive, registerManagedProcess } from "./managed-processes.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { codeExecutionEnvironment, reconcileWorkspaceOwnership, runCheck, workspaceOperationId } from "./code-checks.js";
+import { confirmManagedProcess, finishManagedProcess, renewManagedProcess, managedOwnerIsAlive, managedProcessStatus, processTreeIsAlive, registerManagedProcess } from "./managed-processes.js";
 /** CODE and MERGE prepare their own checkout through the same managed executor.
  * Bootstrap is a project operation, not an alias classified by the engine as a test. */
 export async function runWorkspaceBootstrap(context, input) {
-    const operationId = `bootstrap:${crypto.createHash("sha256").update(JSON.stringify([input.runId, input.workspaceRoot, input.artifactDir, input.command])).digest("hex")}`;
+    reconcileWorkspaceOwnership(context, input.workspaceRoot);
+    const generation = assertRunMutationAllowed(context, input.projectId, input.runId);
+    const operationId = workspaceOperationId(input.workspaceRoot);
+    const identity = crypto.createHash("sha256").update(JSON.stringify([input.projectId, input.runId, generation, path.resolve(input.workspaceRoot), input.command])).digest("hex");
     const pending = managedProcessStatus(context).find(item => item.operation_id === operationId && ["starting", "running", "stopping"].includes(item.state));
     if (pending) {
+        if (pending.kind !== "workspace-bootstrap")
+            throw new AppError("bootstrap_in_progress", "A check currently owns this workspace; wait for it before bootstrapping", 2, { process_id: pending.id, stdout_path: pending.stdout_path, stderr_path: pending.stderr_path });
         if (processTreeIsAlive(pending) || (pending.state === "starting" && managedOwnerIsAlive(pending) !== false)) {
             throw new AppError("bootstrap_in_progress", "Workspace preparation is still running; inspect its logs and wait for the existing process, do not launch another copy", 2, { process_id: pending.id, stdout_path: pending.stdout_path, stderr_path: pending.stderr_path });
         }
-        const completionPath = path.join(path.dirname(pending.stdout_path), "completion.json");
-        let completion = null;
+        let pendingIdentity = null;
         try {
-            completion = JSON.parse(fs.readFileSync(completionPath, "utf8"));
+            const metadata = JSON.parse(pending.metadata_json);
+            pendingIdentity = typeof metadata.bootstrap_identity === "string" ? metadata.bootstrap_identity : null;
+        }
+        catch { /* Legacy records have no usable identity. */ }
+        if (pendingIdentity !== identity) {
+            finishManagedProcess(context, { id: pending.id, leaseToken: pending.lease_token, state: "failed", reason: "bootstrap_identity_superseded" });
+        }
+        else {
+            const completionPath = path.join(path.dirname(pending.stdout_path), "completion.json");
+            let completion = null;
+            try {
+                completion = JSON.parse(fs.readFileSync(completionPath, "utf8"));
+            }
+            catch { /* Interrupted shell has no terminal marker. */ }
+            const exitCode = typeof completion?.exit_code === "number" ? completion.exit_code : null;
+            const error = exitCode === null ? "bootstrap ended without a completion marker; inspect retained logs before retrying" : null;
+            finishManagedProcess(context, { id: pending.id, leaseToken: pending.lease_token, state: exitCode === 0 ? "stopped" : "failed", reason: error ?? "bootstrap_completion_reconciled" });
+            assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+            return result(pending.id, pending.stdout_path, pending.stderr_path, completionPath, exitCode, error);
         }
-        catch { /* Interrupted shell has no terminal marker. */ }
-        const exitCode = typeof completion?.exit_code === "number" ? completion.exit_code : null;
-        const error = exitCode === null ? "bootstrap ended without a completion marker; inspect retained logs before retrying" : null;
-        finishManagedProcess(context, { id: pending.id, leaseToken: pending.lease_token, state: exitCode === 0 ? "stopped" : "failed", reason: error ?? "bootstrap_completion_reconciled" });
-        return result(pending.id, pending.stdout_path, pending.stderr_path, completionPath, exitCode, error);
     }
     const directory = path.join(input.runHome, input.artifactDir, `bootstrap-${crypto.randomUUID()}`);
     fs.mkdirSync(directory, { recursive: true });
     const stdoutPath = path.join(directory, "stdout.log"), stderrPath = path.join(directory, "stderr.log"), completionPath = path.join(directory, "completion.json");
-    const managed = registerManagedProcess(context, { kind: "workspace-bootstrap", ownerId: operationId, ownerPid: process.pid, operationId, projectId: input.projectId, runId: input.runId, stdoutPath, stderrPath, metadata: { command: input.command, workspace_root: input.workspaceRoot } });
+    const managed = registerManagedProcess(context, { kind: "workspace-bootstrap", ownerId: `${operationId}:${identity}`, ownerPid: process.pid, operationId, uniqueActiveOperation: true, projectId: input.projectId, runId: input.runId, stdoutPath, stderrPath, metadata: { command: input.command, workspace_root: input.workspaceRoot, bootstrap_identity: identity } });
     const stdout = fs.openSync(stdoutPath, "a"), stderr = fs.openSync(stderrPath, "a");
     try {
-        input.progress?.(`workspace bootstrap started: ${input.command}; logs: ${directory}`);
-        const completed = await runCheck(input.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_CHECK_COMPLETION_FILE: completionPath }, stdout, stderr, elapsed => input.progress?.(`workspace bootstrap still running (${elapsed}s); logs: ${directory}; next report in 15s`), pid => confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token }));
+        try {
+            input.progress?.(`workspace bootstrap preparing: ${input.command}; logs: ${directory}`);
+            assertRunMutationAllowed(context, input.projectId, input.runId, generation);
+        }
+        catch (error) {
+            finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: "failed", reason: "dispatch_fenced_before_spawn" });
+            throw error;
+        }
+        const completed = await runCheck(input.command, input.workspaceRoot, { ...codeExecutionEnvironment(input.workspaceRoot), DD_FLOW_CHECK_COMPLETION_FILE: completionPath }, stdout, stderr, elapsed => input.progress?.(`workspace bootstrap still running (${elapsed}s); logs: ${directory}; next report in 15s`), pid => confirmManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), attemptMs => renewManagedProcess({ ...context, resourceDatabaseMode: "prepared_existing", databaseDeadlineAt: Date.now() + attemptMs }, { id: managed.id, leaseToken: managed.lease_token }));
         const current = managedProcessStatus(context).find(item => item.id === managed.id);
         if (processTreeIsAlive(current))
             throw new AppError("bootstrap_tree_not_settled", "Bootstrap shell exited but still owns live processes; resources were retained for inspection", 2, { process_id: managed.id, stdout_path: stdoutPath, stderr_path: stderrPath });
+        assertRunMutationAllowed(context, input.projectId, input.runId, generation);
         finishManagedProcess(context, { id: managed.id, leaseToken: managed.lease_token, state: completed.exitCode === 0 && !completed.error ? "stopped" : "failed", reason: completed.error });
         return result(managed.id, stdoutPath, stderrPath, completionPath, completed.exitCode, completed.error);
     }
@@ -45,6 +71,17 @@ export async function runWorkspaceBootstrap(context, input) {
 }
 function result(id, stdout, stderr, completion, exitCode, error) {
     // Full logs remain on disk; keep the returned prompt bounded.
-    const excerpt = (file) => fs.existsSync(file) ? fs.readFileSync(file, "utf8").slice(-64_000) : "";
+    const excerpt = (file) => {
+        if (!fs.existsSync(file))
+            return "";
+        const fd = fs.openSync(file, "r");
+        try {
+            const size = fs.fstatSync(fd).size, bytes = Buffer.alloc(Math.min(size, 64_000));
+            return bytes.subarray(0, fs.readSync(fd, bytes, 0, bytes.length, Math.max(0, size - bytes.length))).toString("utf8");
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    };
     return { exit_code: exitCode, stdout: excerpt(stdout), stderr: excerpt(stderr), error, process_id: id, stdout_path: stdout, stderr_path: stderr, completion_path: completion };
 }

package/dist/services/workspace-files.js

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { isDeepStrictEqual } from "node:util";
+import { AppError } from "../shared/errors.js";
+import { agyWorkspaceHooks } from "../harness-runtime/lib/agy-hooks.mjs";
+/** Local environment/credential files are never an exported reviewer or EVAL input. */
+export function localEnvironmentAllowed(source) {
+    const name = path.basename(source).normalize("NFC").toLowerCase();
+    return name === ".env.example" || (name !== ".env" && !name.startsWith(".env."));
+}
+/** A damaged/inaccessible repository is not an intentional gitless workspace. */
+export function isGitlessWorkspace(root, result) {
+    // git check-ignore can exit 128 before consuming --stdin, yielding EPIPE
+    // alongside the authoritative "not a git repository" diagnostic.
+    if ((result.error && result.error.code !== "EPIPE") || result.status !== 128 || !/not a git repository|outside a repository/i.test(result.stderr ?? ""))
+        return false;
+    for (let directory = path.resolve(root);; directory = path.dirname(directory)) {
+        try {
+            fs.lstatSync(path.join(directory, ".git"));
+            return false;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                return false;
+        }
+        if (path.dirname(directory) === directory)
+            return true;
+    }
+}
+export function workspaceGitFiles(root, args) {
+    const result = spawnSync("git", ["ls-files", "-z", ...args], { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    if (isGitlessWorkspace(root, result))
+        return null;
+    if (result.status !== 0 || result.error)
+        throw new AppError("workspace_status_failed", "Could not determine workspace file inventory", 1, { workspace_root: root, stderr: result.stderr || null, cause: result.error?.message ?? null });
+    return [...new Set(result.stdout.split("\0").filter(Boolean))];
+}
+/** The exact qualified AGY file is infrastructure only while untracked.
+ * Never write a shared worktree exclude: that would hide a sibling's mixed
+ * user hooks. Snapshots still retain this qualification input. */
+export function ownedWorkspaceHookPath(root, trackedFiles) {
+    const relative = ".agents/hooks.json", file = path.join(root, relative);
+    try {
+        if (!fs.lstatSync(path.dirname(file)).isDirectory() || !fs.lstatSync(file).isFile() || !isDeepStrictEqual(JSON.parse(fs.readFileSync(file, "utf8")), agyWorkspaceHooks()))
+            return null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT" || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+    const tracked = trackedFiles ?? workspaceGitFiles(root, ["--cached", "--", relative]) ?? [];
+    return tracked.includes(relative) ? null : relative;
+}
+/** New feature worktrees do not inherit untracked qualified hooks via Git. */
+export function propagateOwnedWorkspaceHooks(sourceRoot, targetRoot) {
+    const relative = ownedWorkspaceHookPath(sourceRoot);
+    if (!relative || path.resolve(sourceRoot) === path.resolve(targetRoot))
+        return null;
+    const target = path.join(targetRoot, relative), directory = path.dirname(target);
+    if (fs.lstatSync(target, { throwIfNoEntry: false }))
+        return null; // User/tracked target wins; daemon checks qualification.
+    if (workspaceGitFiles(targetRoot, ["--cached", "--", relative])?.includes(relative))
+        return null;
+    if (fs.lstatSync(directory, { throwIfNoEntry: false }) && !fs.lstatSync(directory).isDirectory())
+        throw new AppError("workspace_hooks_unqualified", "AGY hook directory is not an owned directory", 1, { path: directory });
+    fs.mkdirSync(directory, { recursive: true });
+    fs.copyFileSync(path.join(sourceRoot, relative), target, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(target, 0o600);
+    return target;
+}
+/** Ignore only provider-owned service files. Tracked/explicit inputs win;
+ * other ignored and untracked product/task files remain snapshot payload. */
+export function projectServicePathFilter(root, explicitInputs = [], trackedFiles) {
+    const retained = new Set([...(trackedFiles ?? workspaceGitFiles(root, ["--cached"]) ?? []), ...explicitInputs].map(file => path.resolve(root, file)));
+    const branches = new Set();
+    for (const file of retained)
+        for (let directory = path.dirname(file); directory !== path.dirname(directory); directory = path.dirname(directory))
+            branches.add(directory);
+    return file => {
+        const absolute = path.resolve(file), relative = path.relative(root, absolute);
+        return !relative.split(path.sep).includes(".zcode") || retained.has(absolute) || branches.has(absolute);
+    };
+}

package/dist/services/worktrees.js

@@ -4,11 +4,14 @@ import { spawnSync } from "node:child_process";
 import { flowContractForState } from "../domain/flow-contract.js";
 import { requireStage } from "../domain/validation.js";
 import { AppError } from "../shared/errors.js";
-import { projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
+import { canonicalPath, projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { persistProtocolState, readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { requireProjectByRoot } from "./projects.js";
 import { ensureManagedWorktrunk, inspectManagedWorktrunk } from "./tooling.js";
+import { propagateOwnedWorkspaceHooks } from "./workspace-files.js";
+import { commandResult } from '../harness-runtime/lib/process-json.mjs';
+import { SETUP_STARTUP_MS } from '../harness-runtime/lib/setup-progress.mjs';
 export function planWorktree(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     const state = readProtocolRuntimeState(context, protocol).state;
@@ -28,7 +31,7 @@ export function planWorktree(context, input) {
         worktrunk: inspectManagedWorktrunk(context)
     };
 }
-export function createWorktreeRecord(context, input) {
+export function prepareWorktreeCreate(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     const existing = activeWorktreeRecord(context, protocol.project_id, protocol.id);
     if (existing) {
@@ -37,18 +40,57 @@ export function createWorktreeRecord(context, input) {
             worktree_path: existing.worktree_path
         });
     }
-    const created = createManagedWorktree(context, { projectRoot: protocol.project_root, branch: input.branch, base: input.base, path: input.path });
-    recordManagedWorktree(context, { protocolId: protocol.id, projectRoot: protocol.project_root, branch: input.branch, base: input.base, created });
+    return prepareManagedWorktree({ ...input, projectRoot: protocol.project_root });
+}
+export async function createWorktreeRecord(context, input, prepared = prepareWorktreeCreate(context, input)) {
+    const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
+    if (activeWorktreeRecord(context, protocol.project_id, protocol.id))
+        throw new AppError("worktree_already_exists", "Protocol already has an active worktree record", 1);
+    const created = await createManagedWorktree(context, prepared, prepared);
+    recordManagedWorktree(context, { protocolId: protocol.id, projectRoot: protocol.project_root, branch: prepared.branch, base: prepared.base, created });
     return { ok: true, worktree: activeWorktreeRecord(context, protocol.project_id, protocol.id) };
 }
-/** Creates the checkout before a PRT exists. PROTOCOLIZE materializes the PRT only inside this checkout. */
-export function createManagedWorktree(context, input) {
+export function prepareManagedWorktree(input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const worktrunk = ensureManagedWorktrunk(context);
+    const invalid = (message) => { throw new AppError("validation", message, 2, { phase: "prepare", effect: "no_effect", recoverable: true }); };
+    for (const key of ["branch", "base", "path"])
+        if (typeof input[key] !== "string" || !input[key].trim() || input[key].includes("\0"))
+            invalid(`--${key} must be a non-empty value without NUL`);
+    const git = (args) => {
+        const result = spawnSync("git", ["-C", projectRoot, ...args], { encoding: "utf8", env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" } });
+        if (result.error)
+            throw result.error;
+        return result;
+    };
+    const branch = git(["check-ref-format", "--branch", input.branch]);
+    if (input.branch.startsWith("-") || branch.status !== 0 || branch.stdout.trim() !== input.branch)
+        invalid("--branch must be a literal valid Git branch name");
+    const base = git(["rev-parse", "--verify", "--end-of-options", `${input.base}^{commit}`]);
+    if (base.status !== 0)
+        invalid("--base must resolve to an existing Git commit");
+    if (git(["show-ref", "--verify", "--quiet", `refs/heads/${input.branch}`]).status === 0)
+        invalid("--branch already exists; choose a new feature branch");
+    const destination = canonicalPath(input.path, false);
+    if (isTrackedProjectPath(canonicalPath(projectRoot), destination))
+        invalid("--path must be outside the project checkout");
+    if (fs.existsSync(destination) && (!fs.statSync(destination).isDirectory() || fs.readdirSync(destination).length))
+        invalid("--path must be an absent or empty directory");
+    let parent = path.dirname(destination);
+    while (!fs.existsSync(parent) && path.dirname(parent) !== parent)
+        parent = path.dirname(parent);
+    if (!fs.statSync(parent).isDirectory())
+        invalid("--path has a parent that is not a directory");
+    fs.accessSync(parent, fs.constants.W_OK | fs.constants.X_OK);
+    return { projectRoot, branch: input.branch, base: base.stdout.trim(), path: destination };
+}
+/** Creates the checkout before a PRT exists. PROTOCOLIZE materializes the PRT only inside this checkout. */
+export async function createManagedWorktree(context, input, prepared = prepareManagedWorktree(input)) {
+    const { projectRoot } = prepared;
+    const worktrunk = await ensureManagedWorktrunk(context);
     // Worktrunk owns creation; the CLI supplies its project-scoped service path
     // as a one-shot config override rather than relying on a developer's user config.
-    const command = [worktrunk.bin, "-C", projectRoot, "--config-set", `worktree-path = ${JSON.stringify(path.resolve(input.path))}`, "switch", "--create", input.branch, "--base", input.base, "--no-cd", "--format=json", "-y"];
-    const result = runExternal(command);
+    const command = [worktrunk.bin, "-C", projectRoot, "--config-set", `worktree-path = ${JSON.stringify(prepared.path)}`, "switch", "--create", prepared.branch, "--base", prepared.base, "--no-cd", "--format=json", "-y"];
+    const result = await runExternal(command);
     if (result.exit_code !== 0)
         throw new AppError("worktrunk_command_unavailable", "Worktrunk switch failed", 1, { command: sanitizeCommand(command), result });
     const response = parseWorktrunkResponse(result.stdout, command);
@@ -76,65 +118,73 @@ export function recordManagedWorktree(context, input) {
     appendAudit(context, { protocolId: protocol.id, projectId: protocol.project_id, eventType: "worktree.created", payload: { protocol_id: protocol.id, feature_branch: input.branch, base: input.base, path: input.created.worktreePath } });
 }
 /** Bootstrap a just-created RUN workspace before a durable PRT exists. */
-export function bootstrapManagedWorktree(context, input) {
-    const projectRoot = resolveProjectRoot(input.projectRoot);
-    const worktreePath = path.resolve(input.worktreePath);
+export function prepareManagedWorktreeBootstrapSources(root) {
+    const projectRoot = resolveProjectRoot(root);
     const includeFile = path.join(projectRoot, ".worktreeinclude");
     const configFile = path.join(projectRoot, ".config", "wt.toml");
     if (!fs.existsSync(includeFile) || !fs.existsSync(configFile)) {
         throw new AppError("bootstrap_unavailable", "Project-owned Worktrunk bootstrap files are required", 1, { include_file: includeFile, config_file: configFile });
     }
-    const worktrunk = ensureManagedWorktrunk(context);
+    for (const file of [includeFile, configFile]) {
+        if (!fs.statSync(file).isFile())
+            throw new AppError("bootstrap_unavailable", "Project-owned bootstrap inputs must be regular files", 1, { file });
+        fs.accessSync(file, fs.constants.R_OK);
+    }
+    return projectRoot;
+}
+export function prepareManagedWorktreeBootstrap(input) {
+    const projectRoot = prepareManagedWorktreeBootstrapSources(input.projectRoot);
+    const worktreePath = path.resolve(input.worktreePath);
+    if (!fs.statSync(worktreePath).isDirectory())
+        throw new AppError("bootstrap_unavailable", "Bootstrap worktree must be a directory", 1, { worktree_path: worktreePath });
+    return { projectRoot, worktreePath };
+}
+export async function bootstrapManagedWorktree(context, input, prepared = prepareManagedWorktreeBootstrap(input)) {
+    const { worktreePath } = prepared;
+    const worktrunk = await ensureManagedWorktrunk(context);
     const commands = [
         [worktrunk.bin, "-C", worktreePath, "step", "copy-ignored", "--require-include"],
         [worktrunk.bin, "-C", worktreePath, "hook", "pre-start", "--yes"]
     ];
     const results = [];
     for (const command of commands) {
-        const result = runExternal(command);
+        const result = await runExternal(command);
         results.push({ command: sanitizeCommand(command), ...result });
         if (result.exit_code !== 0) {
             throw new AppError("bootstrap_failed", "Project-owned Worktrunk bootstrap failed", 1, { command: sanitizeCommand(command), result, results });
         }
     }
-    return { status: "succeeded", commands: results };
+    const qualifiedHook = propagateOwnedWorkspaceHooks(prepared.projectRoot, worktreePath);
+    return { status: "succeeded", commands: results, ...(qualifiedHook ? { qualified_hook: qualifiedHook } : {}) };
 }
 export function getWorktreeStatus(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     return { ok: true, protocol_id: protocol.id, worktree: worktreeRecord(context, protocol.project_id, protocol.id), worktrunk: inspectManagedWorktrunk(context) };
 }
-export function bootstrapWorktree(context, input) {
+export function prepareWorktreeBootstrap(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
     const record = activeWorktreeRecord(context, protocol.project_id, protocol.id);
     if (!record) {
         throw new AppError("not_found", `Worktree record is not active for protocol: ${protocol.id}`, 1);
     }
-    const includeFile = path.join(protocol.project_root, ".worktreeinclude");
-    const configFile = path.join(protocol.project_root, ".config", "wt.toml");
-    if (!fs.existsSync(includeFile) || !fs.existsSync(configFile)) {
-        throw new AppError("bootstrap_unavailable", "Project-owned Worktrunk bootstrap files are required", 1, {
-            include_file: includeFile,
-            config_file: configFile,
-            next_action: "Add .worktreeinclude and .config/wt.toml before bootstrapping the workspace."
-        });
+    return { protocol, record, managed: prepareManagedWorktreeBootstrap({ projectRoot: protocol.project_root, worktreePath: record.worktree_path }) };
+}
+export async function bootstrapWorktree(context, input, prepared = prepareWorktreeBootstrap(context, input)) {
+    const { protocol, record } = prepared;
+    const active = activeWorktreeRecord(context, protocol.project_id, protocol.id);
+    if (!active || active.worktree_path !== record.worktree_path)
+        throw new AppError("worktree_active", "Worktree changed after bootstrap preparation", 1);
+    let result;
+    try {
+        result = await bootstrapManagedWorktree(context, prepared.managed, prepared.managed);
     }
-    const worktrunk = ensureManagedWorktrunk(context);
-    const commands = [
-        [worktrunk.bin, "-C", record.worktree_path, "step", "copy-ignored", "--require-include"],
-        [worktrunk.bin, "-C", record.worktree_path, "hook", "pre-start", "--yes"]
-    ];
-    const results = [];
-    for (const command of commands) {
-        const result = runExternal(command);
-        results.push({ command: sanitizeCommand(command), ...result });
-        if (result.exit_code !== 0) {
-            const failed = { command: sanitizeCommand(command), result, results };
-            markBootstrapFailed(context, protocol, record, failed);
-            throw new AppError("bootstrap_failed", "Project-owned Worktrunk bootstrap failed", 1, failed);
-        }
+    catch (error) {
+        if (error instanceof AppError && error.code === "bootstrap_failed")
+            markBootstrapFailed(context, protocol, record, error.details);
+        throw error;
     }
     const now = context.now();
-    const result = { commands: results, status: "succeeded" };
+    const results = result.commands;
     context.db.run(`UPDATE worktree_records
      SET bootstrap_status = 'succeeded', last_command_result_json = ?, updated_at = ?
      WHERE project_id = ? AND protocol_id = ?`, [JSON.stringify(result), now, protocol.project_id, protocol.id]);
@@ -155,7 +205,7 @@ export function bootstrapWorktree(context, input) {
     });
     return { ok: true, worktree: worktreeRecord(context, protocol.project_id, protocol.id) };
 }
-export function closeWorktree(context, input) {
+export function prepareWorktreeClose(context, input) {
     if (!["keep", "remove"].includes(input.mode)) {
         throw new AppError("validation", "--mode must be keep or remove", 2);
     }
@@ -171,6 +221,10 @@ export function closeWorktree(context, input) {
             stage: state.stage
         });
     }
+    return { protocol, record };
+}
+export function closeWorktree(context, input) {
+    const { protocol, record } = prepareWorktreeClose(context, input);
     const now = context.now();
     const nextStatus = input.mode === "keep" ? "kept" : fs.existsSync(record.worktree_path) ? "kept" : "removed";
     context.db.run(`UPDATE worktree_records SET status = ?, updated_at = ?, closed_at = ? WHERE project_id = ? AND protocol_id = ?`, [nextStatus, now, now, protocol.project_id, protocol.id]);
@@ -202,16 +256,16 @@ export function worktreeRecord(context, projectId, protocolId) {
 function activeWorktreeRecord(context, projectId, protocolId) {
     return context.db.get("SELECT * FROM worktree_records WHERE project_id = ? AND protocol_id = ? AND status = 'active'", [projectId, protocolId]);
 }
-function runExternal(command) {
+async function runExternal(command) {
     const [bin, ...args] = command;
     if (!bin) {
         return { exit_code: null, stdout: "", stderr: "Missing executable." };
     }
-    const result = spawnSync(bin, args, { encoding: "utf8" });
+    const result = await commandResult(bin, args, { startupMs: SETUP_STARTUP_MS });
     return {
-        exit_code: typeof result.status === "number" ? result.status : null,
+        exit_code: result.exit_code,
         stdout: sanitizeOutput(result.stdout),
-        stderr: sanitizeOutput(result.stderr || result.error?.message || "")
+        stderr: sanitizeOutput(result.stderr)
     };
 }
 function sanitizeCommand(command) {

package/dist/shared/entity-references.js

@@ -0,0 +1,8 @@
+/** Stable model-facing reference for persisted project, RUN and Work IDs. */
+export function shortEntityReference(id) {
+    return /^(?:PRJ|RUN|WRK)-\d{3,}(?:-|$)/.exec(id)?.[0]?.replace(/-$/, "") ?? id;
+}
+/** Accepted spellings of one already-resolved entity. Wrong full slugs stay distinct. */
+export function entityReferenceVariants(id) {
+    return [...new Set([id, shortEntityReference(id)])];
+}

package/dist/shared/errors.js

@@ -1,3 +1,4 @@
+import { errorRecord as nativeErrorRecord } from "../harness-runtime/lib/operation-errors.mjs";
 export class AppError extends Error {
     code;
     exitCode;
@@ -9,6 +10,22 @@ export class AppError extends Error {
         this.details = details;
     }
 }
+/** Error fields must cross JSON boundaries as data: Error.message is not enumerable. */
+export function errorRecord(error, depth = 0) {
+    const value = nativeErrorRecord(error, depth);
+    const details = value.details && typeof value.details === "object" && !Array.isArray(value.details) ? value.details : {};
+    let typed = false;
+    try {
+        typed = typeof error?.code === "string";
+    }
+    catch { /* Diagnostic access cannot replace the primary failure. */ }
+    return {
+        ...value,
+        code: typed ? value.code : "unexpected",
+        exitCode: value.exitCode ?? 1,
+        details,
+    };
+}
 export function isAppError(error) {
     return error instanceof AppError;
 }

package/dist/storage/agent-output.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+/** Execution only: prepare an agent's write destination without creating or replacing its payload. */
+export function prepareAgentOutputFile(file) {
+    const absolute = path.resolve(file);
+    try {
+        const parent = path.dirname(absolute);
+        fs.mkdirSync(parent, { recursive: true });
+        fs.accessSync(parent, fs.constants.W_OK | fs.constants.X_OK);
+        // lstat also rejects dangling links: an advertised output must not silently
+        // redirect a write to another authority or overwrite a retained input.
+        const existing = fs.lstatSync(absolute, { throwIfNoEntry: false });
+        if (existing) {
+            if (!existing.isFile())
+                throw new Error("Output must be a regular file, not a directory or link");
+            fs.accessSync(absolute, fs.constants.W_OK);
+        }
+        return absolute;
+    }
+    catch (error) {
+        throw new AppError("agent_output_unavailable", "Agent output destination is not writable", 1, {
+            file: absolute, cause: error instanceof Error ? error.message : String(error)
+        });
+    }
+}