@loucompanion/forge-bridge 0.1.3-dev.b6be5e7f9668 → 0.1.3-dev.ba7d36726eda

package/dist/shared/process/host-process-supervisor.js

@@ -0,0 +1,195 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const windowsJobSupervisorPath = fileURLToPath(new URL("../../../runtime/windows-job-supervisor.ps1", import.meta.url));
+export function resolveHostProcessSupervisedLaunch(request, resolvedCommand, resolvedArgs, platform = process.platform) {
+    const env = request.env;
+    if (env?.FORGE_RUNTIME_MODE !== "host")
+        return null;
+    const supervisorId = requiredEnvironment(env, "FORGE_PROCESS_SUPERVISOR_ID");
+    const metadataPath = requiredEnvironment(env, "FORGE_PROCESS_SUPERVISOR_METADATA_PATH");
+    const logDirectory = requiredEnvironment(env, "FORGE_LOG_DIR");
+    assertMetadataPath(logDirectory, metadataPath);
+    const commandDigest = createHash("sha256")
+        .update(JSON.stringify([resolvedCommand, ...resolvedArgs]))
+        .digest("hex");
+    if (platform === "win32") {
+        if (!fs.existsSync(windowsJobSupervisorPath)) {
+            throw new Error(`host_process_supervisor_missing: ${windowsJobSupervisorPath}`);
+        }
+        const payload = Buffer.from(JSON.stringify({
+            command: resolvedCommand,
+            args: resolvedArgs,
+            cwd: request.cwd,
+            parentPid: process.pid,
+            supervisorId,
+        }), "utf8").toString("base64");
+        return {
+            command: windowsPowerShellPath(),
+            args: [
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                windowsJobSupervisorPath,
+                "-Mode",
+                "Outer",
+                "-Payload",
+                payload,
+            ],
+            detached: false,
+            supervisorId,
+            strategy: "windows_job_object",
+            metadataPath,
+            commandDigest,
+        };
+    }
+    return {
+        command: resolvedCommand,
+        args: resolvedArgs,
+        detached: true,
+        supervisorId,
+        strategy: "unix_process_group",
+        metadataPath,
+        commandDigest,
+    };
+}
+export function persistHostProcessSupervisorMetadata(launch, request, rootPid, rootCreatedAt) {
+    if (!Number.isSafeInteger(rootPid) || rootPid <= 0) {
+        throw new Error("host_process_supervisor_invalid: supervised root PID was not assigned.");
+    }
+    const env = request.env ?? {};
+    const metadata = {
+        schemaVersion: 1,
+        supervisorId: launch.supervisorId,
+        strategy: launch.strategy,
+        rootPid,
+        rootCreatedAt,
+        rootIdentity: captureHostProcessIdentity(rootPid),
+        commandDigest: launch.commandDigest,
+        worktreePath: request.cwd,
+        runtimeLeaseId: requiredEnvironment(env, "FORGE_RESOURCE_LEASE_ID"),
+        dispatchAttemptId: requiredEnvironment(env, "FORGE_DISPATCH_ATTEMPT_ID"),
+        fencingToken: requiredEnvironment(env, "FORGE_FENCING_TOKEN"),
+        bridgePid: process.pid,
+    };
+    fs.writeFileSync(launch.metadataPath, `${JSON.stringify(metadata)}\n`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o600,
+    });
+    return metadata;
+}
+/**
+ * Captures an OS-issued process birth marker. Recovery compares this marker
+ * before signalling a persisted PID so PID reuse can never redirect cleanup
+ * at an unrelated process.
+ */
+export function captureHostProcessIdentity(pid, platform = process.platform) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        if (platform === "linux") {
+            const bootId = fs.readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+            const stat = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
+            const close = stat.lastIndexOf(")");
+            const fields = close >= 0 ? stat.slice(close + 2).trim().split(/\s+/u) : [];
+            const startTicks = fields[19];
+            return bootId && startTicks && /^\d+$/u.test(startTicks)
+                ? `linux:${bootId}:${startTicks}`
+                : null;
+        }
+        if (platform === "win32") {
+            const output = execFileSync(windowsPowerShellPath(), [
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`,
+            ], {
+                encoding: "utf8",
+                windowsHide: true,
+                timeout: 2_000,
+                stdio: ["ignore", "pipe", "ignore"],
+            }).trim();
+            return /^\d+$/u.test(output) ? `win32:${output}` : null;
+        }
+        // Other Unix variants do not expose a sufficiently strong birth marker
+        // through Node. Fail closed rather than trust a second-resolution ps time.
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function terminateHostProcessTree(child, launch, graceMs = 2_000) {
+    if (!launch) {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // The process already settled.
+        }
+        return;
+    }
+    if (launch.strategy === "windows_job_object") {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // Closing the launcher is best effort when the Job Object already settled.
+        }
+        return;
+    }
+    const processGroupId = child.pid;
+    if (!processGroupId || !signalUnixProcessGroup(processGroupId, "SIGTERM"))
+        return;
+    await new Promise(resolve => setTimeout(resolve, graceMs));
+    if (unixProcessGroupExists(processGroupId)) {
+        signalUnixProcessGroup(processGroupId, "SIGKILL");
+    }
+}
+function requiredEnvironment(env, name) {
+    const value = env[name]?.trim();
+    if (!value)
+        throw new Error(`host_process_supervisor_invalid: ${name} is required.`);
+    return value;
+}
+function assertMetadataPath(logDirectory, metadataPath) {
+    const root = path.resolve(logDirectory);
+    const target = path.resolve(metadataPath);
+    if (target !== root && !target.startsWith(`${root}${path.sep}`)) {
+        throw new Error("host_process_supervisor_invalid: metadata path must be inside FORGE_LOG_DIR.");
+    }
+}
+function windowsPowerShellPath() {
+    const systemRoot = process.env.SystemRoot?.trim() || "C:\\Windows";
+    const candidate = path.win32.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+    return fs.existsSync(candidate) ? candidate : "powershell.exe";
+}
+function signalUnixProcessGroup(processGroupId, signal) {
+    try {
+        process.kill(-processGroupId, signal);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return false;
+        throw error;
+    }
+}
+function unixProcessGroupExists(processGroupId) {
+    try {
+        process.kill(-processGroupId, 0);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ESRCH")
+            return false;
+        throw error;
+    }
+}

package/dist/shared/process/windows-launch.d.ts

@@ -0,0 +1,8 @@
+export interface LaunchCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+}
+export declare function buildWindowsCmdLaunch(command: string, args: readonly string[], comSpec?: string | undefined): LaunchCommand;
+export declare function buildWindowsLaunchCommand(commandPath: string, args: readonly string[]): LaunchCommand;
+export declare function windowsCommandLine(command: string, args: readonly string[]): string;
+export declare function quoteWindowsCommandLineArg(value: string): string;

package/dist/shared/process/windows-launch.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+export function buildWindowsCmdLaunch(command, args, comSpec = process.env.ComSpec) {
+    const resolvedComSpec = comSpec?.trim();
+    const commandLine = windowsCommandLine(command, args);
+    const cmdPayload = commandLine.startsWith('"') ? `"${commandLine}"` : commandLine;
+    return {
+        command: resolvedComSpec || "cmd.exe",
+        args: ["/d", "/s", "/v:off", "/c", cmdPayload]
+    };
+}
+export function buildWindowsLaunchCommand(commandPath, args) {
+    const extension = path.extname(commandPath).toLowerCase();
+    if (extension === ".ps1") {
+        return {
+            command: powershellExecutable(),
+            args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", commandPath, ...args]
+        };
+    }
+    if (extension === ".cmd" || extension === ".bat") {
+        return buildWindowsCmdLaunch(commandPath, args);
+    }
+    return { command: commandPath, args };
+}
+export function windowsCommandLine(command, args) {
+    return [command, ...args].map(quoteWindowsCommandLineArg).join(" ");
+}
+export function quoteWindowsCommandLineArg(value) {
+    const escaped = value
+        .replace(/\^/g, "^^")
+        .replace(/%/g, "^%");
+    if (escaped.length > 0 && !/[\s"&|<>()^%!]/.test(escaped)) {
+        return escaped;
+    }
+    return `"${escaped.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/g, "$1$1")}"`;
+}
+function powershellExecutable() {
+    const systemRoot = process.env.SystemRoot;
+    return systemRoot
+        ? path.join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+        : "powershell.exe";
+}

package/dist/shared/provider-capabilities.d.ts

@@ -0,0 +1 @@
+export declare function supportsDraftImageAttachmentsFor(cliProviders: readonly string[]): boolean;

package/dist/shared/provider-capabilities.js

@@ -0,0 +1,3 @@
+export function supportsDraftImageAttachmentsFor(cliProviders) {
+    return cliProviders.some((provider) => provider.trim().toLowerCase() === "codex");
+}

package/dist/shared/redaction/redaction.js

@@ -1,16 +1,23 @@
 const secretKeyPattern = /(api[_-]?key|authorization|bearer|client[_-]?secret|password|secret|token)/i;
+const attachmentContentKeyPattern = /^(textContent|contentBase64)$/i;
+const serializedAttachmentContentPattern = /("(?:textContent|contentBase64)"\s*:\s*")(?:(?:\\.)|[^"\\])*(")/gi;
+const authorizationCredentialPattern = /(\bauthorization\s*[:=]\s*(?:bearer|basic)?\s*)([^"',\s]+)/gi;
+const bearerCredentialPattern = /(\bbearer\s+)([^"',\s]+)/gi;
+const secretAssignmentPattern = /(api[_-]?key|client[_-]?secret|password|secret|token)(\s*["']?\s*[:=]\s*["']?\s*)([^"',\s]+)/gi;
 export function redactSecrets(value, exactSecrets = []) {
     return redactValue(value, exactSecrets);
 }
 export function redactText(value, exactSecrets = []) {
-    let redacted = value;
+    let redacted = value.replace(serializedAttachmentContentPattern, "$1[REDACTED]$2");
     for (const secret of exactSecrets) {
         if (secret.length > 0) {
             redacted = redacted.split(secret).join("[REDACTED]");
         }
     }
     return redacted
-        .replace(/(api[_-]?key|authorization|bearer|client[_-]?secret|password|secret|token)(["':=\s]+)([^"',\s]+)/gi, "$1$2[REDACTED]")
+        .replace(authorizationCredentialPattern, "$1[REDACTED]")
+        .replace(bearerCredentialPattern, "$1[REDACTED]")
+        .replace(secretAssignmentPattern, "$1$2[REDACTED]")
         .replace(/(sk-[a-zA-Z0-9_-]{12,})/g, "[REDACTED]");
 }
 function redactValue(value, exactSecrets) {
@@ -25,6 +32,6 @@ function redactValue(value, exactSecrets) {
     }
     return Object.fromEntries(Object.entries(value).map(([key, item]) => [
         key,
-        secretKeyPattern.test(key) ? "[REDACTED]" : redactValue(item, exactSecrets)
+        secretKeyPattern.test(key) || attachmentContentKeyPattern.test(key) ? "[REDACTED]" : redactValue(item, exactSecrets)
     ]));
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.3-dev.b6be5e7f9668";
+export declare const forgeBridgeVersion = "0.1.3-dev.ba7d36726eda";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.3-dev.b6be5e7f9668";
+export const forgeBridgeVersion = "0.1.3-dev.ba7d36726eda";

package/dist/worktree/artifact-injector.js

@@ -36,19 +36,29 @@ const DRAFT_OPERATIONAL_SKILLS = new Set([
     "draft-repo-context",
     "draft-graph-context",
     "draft-product-scope",
-    "draft-work-order-plan",
     "draft-critic",
     "draft-proposal"
 ]);
+const DRAFT_WORK_ITEM_OPERATIONAL_SKILLS = new Set([
+    "draft-work-item-plan"
+]);
+const DRAFT_WORK_ORDER_OPERATIONAL_SKILLS = new Set([
+    "draft-work-order-plan"
+]);
 const DRAFT_OPERATIONAL_HOOKS = new Set([
     "draft-intent",
     "draft-repo-context",
     "draft-graph-context",
     "draft-product-scope",
-    "draft-work-order-plan",
     "draft-critic",
     "draft-proposal"
 ]);
+const DRAFT_WORK_ITEM_OPERATIONAL_HOOKS = new Set([
+    "draft-work-item-plan"
+]);
+const DRAFT_WORK_ORDER_OPERATIONAL_HOOKS = new Set([
+    "draft-work-order-plan"
+]);
 export async function injectWorktreeArtifacts(worktreePath, artifacts) {
     for (const artifact of artifacts) {
         await writeArtifact(worktreePath, artifact);
@@ -64,7 +74,7 @@ export function filterArtifactsForLane(artifacts, lane, phase) {
         return artifacts.filter((artifact) => shouldInjectArchitectArtifact(artifact, commandSlug));
     }
     if (normalizedLane === "draft") {
-        return artifacts.filter((artifact) => shouldInjectDraftArtifact(artifact, commandSlug));
+        return artifacts.filter((artifact) => shouldInjectDraftArtifact(artifact, commandSlug, phase));
     }
     return artifacts;
 }
@@ -142,7 +152,7 @@ function shouldInjectArchitectArtifact(artifact, commandSlug) {
             return false;
     }
 }
-function shouldInjectDraftArtifact(artifact, commandSlug) {
+function shouldInjectDraftArtifact(artifact, commandSlug, phase) {
     if (artifact.scope.trim().toLowerCase() !== "operational") {
         return false;
     }
@@ -151,13 +161,36 @@ function shouldInjectDraftArtifact(artifact, commandSlug) {
         case "command":
             return slug === commandSlug;
         case "skill":
-            return DRAFT_OPERATIONAL_SKILLS.has(slug);
+            return DRAFT_OPERATIONAL_SKILLS.has(slug) || draftPhaseSkills(phase).has(slug);
         case "hook":
-            return DRAFT_OPERATIONAL_HOOKS.has(slug);
+            return DRAFT_OPERATIONAL_HOOKS.has(slug) || draftPhaseHooks(phase).has(slug);
         default:
             return false;
     }
 }
+function draftPhaseSkills(phase) {
+    switch (normalizeDraftPhase(phase)) {
+        case "work_order":
+            return DRAFT_WORK_ORDER_OPERATIONAL_SKILLS;
+        case "story":
+            return DRAFT_WORK_ITEM_OPERATIONAL_SKILLS;
+        default:
+            return DRAFT_WORK_ITEM_OPERATIONAL_SKILLS;
+    }
+}
+function draftPhaseHooks(phase) {
+    switch (normalizeDraftPhase(phase)) {
+        case "work_order":
+            return DRAFT_WORK_ORDER_OPERATIONAL_HOOKS;
+        case "story":
+            return DRAFT_WORK_ITEM_OPERATIONAL_HOOKS;
+        default:
+            return DRAFT_WORK_ITEM_OPERATIONAL_HOOKS;
+    }
+}
+function normalizeDraftPhase(phase) {
+    return phase.trim().toLowerCase().replaceAll("-", "_");
+}
 export function buildSpecBody(laneCommand, workItem, phase = "implementation") {
     const prompt = laneCommand.body.replaceAll("{workItemId}", workItem.id);
     return `---

package/dist/worktree/dependency-warmer.d.ts

@@ -30,3 +30,14 @@ export declare function createDirectoryLink(sourcePath: string, targetPath: stri
 export declare function lockfilesDiffer(baseCheckoutPath: string, worktreePath: string, packageRootRelative: string): Promise<boolean>;
 export declare function requiresInstallFallback(entry: WarmPathEntry, baseCheckoutPath: string, worktreePath: string, sourceExists: boolean): Promise<string | null>;
 export declare function declaresNativeModules(packageRootPath: string): Promise<boolean>;
+export interface NpmLaunchOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly execPath?: string;
+    readonly platform?: NodeJS.Platform;
+    readonly homeDir?: string;
+    readonly candidates?: readonly string[];
+}
+export declare function resolveNpmLaunch(args: readonly string[], options?: NpmLaunchOptions): {
+    command: string;
+    args: readonly string[];
+};

package/dist/worktree/dependency-warmer.js

@@ -1,6 +1,9 @@
+import { existsSync, realpathSync } from "node:fs";
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { NodeProcessRunner } from "../shared/process/process.js";
+import { buildWindowsCmdLaunch } from "../shared/process/windows-launch.js";
 import { isSubPath } from "../shared/path/path.js";
 const SKIP_DIR_NAMES = new Set([
     ".git",
@@ -184,7 +187,8 @@ async function runInstallFallback(entry, worktreePath, reason, executor) {
     if (entry.ecosystem === "node") {
         const lockPath = path.join(cwd, "package-lock.json");
         const args = (await pathExists(lockPath)) ? ["ci"] : ["install"];
-        await executor.run(cwd, "npm", args);
+        const launch = resolveNpmLaunch(args);
+        await executor.run(cwd, launch.command, launch.args);
         return { ecosystem: entry.ecosystem, packageRoot: entry.packageRoot, reason, command: `npm ${args.join(" ")}` };
     }
     if (entry.ecosystem === "python") {
@@ -286,6 +290,46 @@ async function sha256File(filePath) {
     const content = await fs.readFile(filePath);
     return crypto.createHash("sha256").update(content).digest("hex");
 }
+export function resolveNpmLaunch(args, options = {}) {
+    const env = options.env ?? process.env;
+    const execPath = options.execPath ?? process.execPath;
+    const npmExecPath = env.npm_execpath;
+    if (npmExecPath) {
+        return { command: execPath, args: [npmExecPath, ...args] };
+    }
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32") {
+        const comSpec = options.env ? env.ComSpec ?? "cmd.exe" : env.ComSpec;
+        return buildWindowsCmdLaunch("npm.cmd", args, comSpec);
+    }
+    for (const candidate of options.candidates ?? defaultNpmCliCandidates(execPath, options.homeDir ?? os.homedir())) {
+        const resolvedCandidate = tryResolveNpmCandidate(candidate);
+        if (resolvedCandidate) {
+            return { command: execPath, args: [resolvedCandidate, ...args] };
+        }
+    }
+    return { command: "npm", args };
+}
+function tryResolveNpmCandidate(candidate) {
+    try {
+        if (!existsSync(candidate)) {
+            return null;
+        }
+        return realpathSync(candidate);
+    }
+    catch {
+        return null;
+    }
+}
+function defaultNpmCliCandidates(execPath, homeDir) {
+    const candidates = [];
+    const execDir = path.dirname(execPath);
+    if (path.isAbsolute(execDir)) {
+        candidates.push(path.join(execDir, "npm"), path.join(execDir, "npm-cli.js"), path.join(execDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"));
+    }
+    candidates.push("/usr/bin/npm", "/usr/local/bin/npm", path.join(homeDir, ".npm-global", "bin", "npm"), path.join(homeDir, ".npm-global", "lib", "node_modules", "npm", "bin", "npm-cli.js"));
+    return candidates;
+}
 const defaultCommandExecutor = {
     async run(cwd, command, args) {
         const result = await defaultProcessRunner.run({ command, cwd, args });

package/dist/worktree/index.d.ts

@@ -1,4 +1,5 @@
 export { GitWorktreeService } from "./worktree.service.js";
+export { managedRepoRoot, resolveManagedWorktreeRoot, resolveManagedWorktreeRootForRepo, } from "./worktree-paths.js";
 export { detectWarmPaths, warmWorktreeDependencies, createDirectoryLink, lockfilesDiffer, requiresInstallFallback } from "./dependency-warmer.js";
 export type { WarmDependenciesResult, WarmPathEntry, InstallFallbackResult } from "./dependency-warmer.js";
 export type { WorktreeService } from "./worktree.base.js";

package/dist/worktree/index.js

@@ -1,2 +1,3 @@
 export { GitWorktreeService } from "./worktree.service.js";
+export { managedRepoRoot, resolveManagedWorktreeRoot, resolveManagedWorktreeRootForRepo, } from "./worktree-paths.js";
 export { detectWarmPaths, warmWorktreeDependencies, createDirectoryLink, lockfilesDiffer, requiresInstallFallback } from "./dependency-warmer.js";

package/dist/worktree/prior-phase-artifact-hydrator.d.ts

@@ -0,0 +1,2 @@
+import type { DispatchPriorPhaseArtifact } from "../session/session.types.js";
+export declare function hydratePriorPhaseArtifacts(worktreePath: string, artifacts?: readonly DispatchPriorPhaseArtifact[]): Promise<number>;

package/dist/worktree/prior-phase-artifact-hydrator.js

@@ -0,0 +1,136 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isSubPath } from "../shared/path/path.js";
+const MAX_ARTIFACT_COUNT = 128;
+const MAX_CONTENT_BYTES = 2 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 12 * 1024 * 1024;
+const phaseFiles = {
+    implementation: {
+        verdict: "implementation.completeness.json",
+        report: "implementation.report.md"
+    },
+    self_review: {
+        verdict: "self-review.report.json",
+        report: "self-review.summary.md"
+    },
+    validation: {
+        verdict: "validation.verdict.json",
+        report: "validation.report.md"
+    }
+};
+export async function hydratePriorPhaseArtifacts(worktreePath, artifacts = []) {
+    if (artifacts.length === 0)
+        return 0;
+    if (artifacts.length > MAX_ARTIFACT_COUNT) {
+        throw new Error(`Prior phase artifact handoff exceeds ${MAX_ARTIFACT_COUNT} artifacts.`);
+    }
+    const targets = new Set();
+    let totalBytes = 0;
+    for (const artifact of artifacts) {
+        const workItemId = safeArtifactSegment(artifact.workItemId, "work item id");
+        const files = phaseFiles[artifact.phase];
+        if (!files) {
+            throw new Error(`Unsupported prior phase artifact phase '${artifact.phase}'.`);
+        }
+        const verdictBytes = Buffer.byteLength(artifact.verdictJson, "utf8");
+        const reportBytes = Buffer.byteLength(artifact.report, "utf8");
+        if (verdictBytes > MAX_CONTENT_BYTES || reportBytes > MAX_CONTENT_BYTES) {
+            throw new Error(`Prior phase artifact '${artifact.artifactId}' exceeds the per-file hydration limit.`);
+        }
+        totalBytes += verdictBytes + reportBytes;
+        if (totalBytes > MAX_TOTAL_BYTES) {
+            throw new Error("Prior phase artifact handoff exceeds the total hydration limit.");
+        }
+        verifyContentHash(artifact.verdictJson, artifact.verdictContentHash, artifact.artifactId, "verdict");
+        verifyContentHash(artifact.report, artifact.reportContentHash, artifact.artifactId, "report");
+        validateVerdict(artifact);
+        const artifactRoot = path.resolve(worktreePath, ".forge", "work-items", workItemId, "artifacts");
+        if (!isSubPath(worktreePath, artifactRoot)) {
+            throw new Error("Prior phase artifact target must stay under the worktree.");
+        }
+        await ensureNoSymlinkPathSegments(worktreePath, artifactRoot);
+        await fs.mkdir(artifactRoot, { recursive: true });
+        await ensureNoSymlinkPathSegments(worktreePath, artifactRoot);
+        const verdictPath = path.join(artifactRoot, files.verdict);
+        const reportPath = path.join(artifactRoot, files.report);
+        const targetKey = verdictPath.toLowerCase();
+        if (targets.has(targetKey)) {
+            throw new Error(`Duplicate prior phase artifact target for work item '${workItemId}' phase '${artifact.phase}'.`);
+        }
+        targets.add(targetKey);
+        await writeAtomic(verdictPath, artifact.verdictJson);
+        await writeAtomic(reportPath, artifact.report);
+    }
+    return artifacts.length;
+}
+function validateVerdict(artifact) {
+    let parsed;
+    try {
+        parsed = JSON.parse(artifact.verdictJson);
+    }
+    catch {
+        throw new Error(`Prior phase artifact '${artifact.artifactId}' verdict is not valid JSON.`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Prior phase artifact '${artifact.artifactId}' verdict must be a JSON object.`);
+    }
+    const recordedPhase = parsed["phase"];
+    const normalizedPhase = typeof recordedPhase === "string"
+        ? recordedPhase.trim().toLowerCase().replace(/-/g, "_")
+        : "";
+    if (normalizedPhase !== artifact.phase) {
+        throw new Error(`Prior phase artifact '${artifact.artifactId}' phase does not match its verdict.`);
+    }
+}
+function verifyContentHash(content, expected, artifactId, label) {
+    const normalizedExpected = expected.trim().toLowerCase().replace(/^sha256:/, "");
+    if (!/^[0-9a-f]{64}$/.test(normalizedExpected)) {
+        throw new Error(`Prior phase artifact '${artifactId}' ${label} hash is invalid.`);
+    }
+    const actual = createHash("sha256").update(content, "utf8").digest("hex");
+    if (actual !== normalizedExpected) {
+        throw new Error(`Prior phase artifact '${artifactId}' ${label} content_hash mismatch.`);
+    }
+}
+function safeArtifactSegment(value, label) {
+    const trimmed = value.trim();
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(trimmed)) {
+        throw new Error(`Prior phase artifact ${label} is not a safe path segment.`);
+    }
+    return trimmed;
+}
+async function writeAtomic(targetPath, content) {
+    const temporaryPath = `${targetPath}.tmp-${randomUUID()}`;
+    try {
+        await fs.writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600, flag: "wx" });
+        await fs.rename(temporaryPath, targetPath);
+    }
+    finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+async function ensureNoSymlinkPathSegments(root, targetPath) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedTarget = path.resolve(targetPath);
+    const relative = path.relative(resolvedRoot, resolvedTarget);
+    if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        throw new Error("Prior phase artifact path must stay under the worktree.");
+    }
+    let current = resolvedRoot;
+    for (const segment of relative.split(path.sep)) {
+        if (!segment)
+            continue;
+        current = path.join(current, segment);
+        const stat = await fs.lstat(current).catch((error) => {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink()) {
+            throw new Error("Prior phase artifact path must not traverse symlinked path segments.");
+        }
+    }
+}

package/dist/worktree/worktree-paths.d.ts

@@ -0,0 +1,4 @@
+export declare function managedRepoRoot(allowedRoot: string): string;
+export declare function resolveManagedWorktreeRoot(allowedRoot: string, repoPath: string): string;
+export declare function resolveManagedWorktreeRootForRepo(repoPath: string, allowedRoot?: string): string;
+export declare function defaultWorktreeCoordinatorStateRoot(): string;

package/dist/worktree/worktree-paths.js

@@ -0,0 +1,30 @@
+import os from "node:os";
+import path from "node:path";
+import { isSubPath } from "../shared/path/path.js";
+export function managedRepoRoot(allowedRoot) {
+    return path.join(path.resolve(allowedRoot), ".forge-worktrees", "_repos");
+}
+export function resolveManagedWorktreeRoot(allowedRoot, repoPath) {
+    const resolvedAllowedRoot = path.resolve(allowedRoot);
+    const resolvedRepoPath = path.resolve(repoPath);
+    const baseName = path.basename(resolvedRepoPath);
+    return isSubPath(managedRepoRoot(resolvedAllowedRoot), resolvedRepoPath)
+        ? path.join(resolvedAllowedRoot, ".forge-worktrees", baseName)
+        : path.join(path.dirname(resolvedRepoPath), ".forge-worktrees", baseName);
+}
+export function resolveManagedWorktreeRootForRepo(repoPath, allowedRoot) {
+    const resolvedRepoPath = path.resolve(repoPath);
+    if (allowedRoot && isSubPath(path.resolve(allowedRoot), resolvedRepoPath)) {
+        return resolveManagedWorktreeRoot(allowedRoot, resolvedRepoPath);
+    }
+    const repoParent = path.dirname(resolvedRepoPath);
+    const managedRoot = path.dirname(repoParent);
+    if (path.basename(repoParent) === "_repos" && path.basename(managedRoot) === ".forge-worktrees") {
+        return path.join(managedRoot, path.basename(resolvedRepoPath));
+    }
+    return path.join(repoParent, ".forge-worktrees", path.basename(resolvedRepoPath));
+}
+export function defaultWorktreeCoordinatorStateRoot() {
+    return process.env.FORGE_SANDBOX_STATE_ROOT
+        ?? path.join(os.homedir(), ".forge", "bridge", "sandboxes");
+}

package/dist/worktree/worktree.base.d.ts

@@ -3,3 +3,6 @@ export interface WorktreeService {
     prepare(request: WorktreePrepareRequest): Promise<WorktreeHandle>;
     release(handle: WorktreeHandle): Promise<void>;
 }
+export interface WorktreeLifecycleCoordinator {
+    withLock<T>(repoPath: string, action: () => Promise<T>, signal?: AbortSignal): Promise<T>;
+}