@loucompanion/forge-bridge 0.1.1-dev.2bc1e7f19b3a → 0.1.1-dev.2d1a116ca78d

package/dist/session/session.types.js

@@ -15,9 +15,16 @@ export function parseRunOnceDispatchPacket(value) {
         lease: parseLease(packet.lease),
         execution: parseExecution(packet.execution),
         serverLocal: parseServerLocal(packet.serverLocal),
+        pullRequest: parsePullRequest(packet.pullRequest),
         apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant),
         artifacts: parseArtifacts(packet.artifacts),
-        warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides)
+        warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides),
+        qaBrowser: parseQaBrowser(packet.qaBrowser),
+        qaRework: parseQaRework(packet.qaRework),
+        architectRevision: parseArchitectRevision(packet.architectRevision),
+        storyDevelop: parseStoryDevelop(packet.storyDevelop),
+        storyQa: parseStoryQa(packet.storyQa),
+        draft: parseDraftPrompt(packet.draft)
     };
 }
 export function failureResult(summary, events = []) {
@@ -55,6 +62,9 @@ function parseCycleRun(value) {
     const cycle = asObject(value, "cycleRun");
     return {
         id: requiredString(cycle, "id"),
+        ownerType: optionalString(cycle, "ownerType"),
+        ownerId: optionalString(cycle, "ownerId"),
+        workItemId: optionalString(cycle, "workItemId"),
         kind: requiredString(cycle, "kind"),
         phase: requiredString(cycle, "phase"),
         requestedBase: optionalString(cycle, "requestedBase") ?? "develop",
@@ -76,6 +86,9 @@ function parseLease(value) {
     const lease = asObject(value, "lease");
     return {
         id: requiredString(lease, "id"),
+        ownerType: optionalString(lease, "ownerType"),
+        ownerId: optionalString(lease, "ownerId"),
+        workItemId: optionalString(lease, "workItemId"),
         worktreeKey: requiredString(lease, "worktreeKey"),
         lane: requiredString(lease, "lane"),
         fencingToken: requiredString(lease, "fencingToken"),
@@ -93,7 +106,19 @@ function parseExecution(value) {
         repoId: requiredString(execution, "repoId"),
         role: requiredString(execution, "role"),
         lane: requiredString(execution, "lane"),
-        requiresApiKeySecretGrant: requiredBoolean(execution, "requiresApiKeySecretGrant")
+        requiresApiKeySecretGrant: requiredBoolean(execution, "requiresApiKeySecretGrant"),
+        runnerRepoLocalPath: optionalString(execution, "runnerRepoLocalPath")
+    };
+}
+function parseDraftPrompt(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const draft = asObject(value, "draft");
+    return {
+        kind: requiredString(draft, "kind"),
+        systemPrompt: requiredString(draft, "systemPrompt"),
+        userPrompt: requiredString(draft, "userPrompt")
     };
 }
 function parseApiKeySecretGrant(value) {
@@ -115,6 +140,28 @@ function parseServerLocal(value) {
         cleanupWorktrees: requiredBoolean(serverLocal, "cleanupWorktrees")
     };
 }
+function parsePullRequest(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const pullRequest = asObject(value, "pullRequest");
+    return {
+        number: requiredNumber(pullRequest, "number"),
+        provider: requiredString(pullRequest, "provider"),
+        title: optionalString(pullRequest, "title") ?? "",
+        sourceBranch: requiredString(pullRequest, "sourceBranch"),
+        targetBranch: requiredString(pullRequest, "targetBranch"),
+        url: optionalString(pullRequest, "url") ?? "",
+        state: requiredString(pullRequest, "state"),
+        checkState: requiredString(pullRequest, "checkState"),
+        mergeState: requiredString(pullRequest, "mergeState"),
+        requiredChecksPassed: requiredNumber(pullRequest, "requiredChecksPassed"),
+        requiredChecksTotal: requiredNumber(pullRequest, "requiredChecksTotal"),
+        unresolvedThreads: requiredNumber(pullRequest, "unresolvedThreads"),
+        humanApproved: requiredBoolean(pullRequest, "humanApproved"),
+        hasMergeConflicts: requiredBoolean(pullRequest, "hasMergeConflicts")
+    };
+}
 function parseWarmPathOverrides(value) {
     if (value === undefined || value === null) {
         return [];
@@ -138,6 +185,197 @@ function parseWarmPathOverride(entry, index) {
     }
     return segments.join("/");
 }
+function parseQaBrowser(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const qaBrowser = asObject(value, "qaBrowser");
+    return {
+        required: optionalBoolean(qaBrowser, "required") ?? false,
+        launchTarget: parseQaAppLaunchTarget(qaBrowser.launchTarget ?? qaBrowser.launch_target),
+        artifactsPath: optionalString(qaBrowser, "artifactsPath") ?? optionalString(qaBrowser, "artifacts_path") ?? "",
+        missingTargetReason: optionalString(qaBrowser, "missingTargetReason") ?? optionalString(qaBrowser, "missing_target_reason")
+    };
+}
+function parseQaAppLaunchTarget(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const launchTarget = asObject(value, "qaBrowser.launchTarget");
+    const routes = launchTarget.routes;
+    if (routes !== undefined && routes !== null && !Array.isArray(routes)) {
+        throw new Error("qaBrowser.launchTarget.routes must be an array when provided.");
+    }
+    return {
+        url: optionalString(launchTarget, "url"),
+        command: optionalString(launchTarget, "command"),
+        working_directory: optionalString(launchTarget, "working_directory"),
+        ready_url: optionalString(launchTarget, "ready_url"),
+        routes: Array.isArray(routes)
+            ? routes.map((entry, index) => {
+                if (typeof entry !== "string") {
+                    throw new Error(`qaBrowser.launchTarget.routes[${index}] must be a string.`);
+                }
+                return entry;
+            }).filter((entry) => entry.trim().length > 0)
+            : [],
+        notes: optionalString(launchTarget, "notes")
+    };
+}
+function parseQaRework(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const qaRework = asObject(value, "qaRework");
+    const findingIdsValue = qaRework.findingIds;
+    if (!Array.isArray(findingIdsValue)) {
+        throw new Error("qaRework.findingIds must be an array.");
+    }
+    const findingsValue = qaRework.findings;
+    if (!Array.isArray(findingsValue)) {
+        throw new Error("qaRework.findings must be an array.");
+    }
+    return {
+        attempt: requiredNumber(qaRework, "attempt"),
+        maxAttempts: requiredNumber(qaRework, "maxAttempts"),
+        packetPath: requiredString(qaRework, "packetPath"),
+        packetJson: requiredString(qaRework, "packetJson"),
+        findingIds: findingIdsValue.map((entry, index) => {
+            if (typeof entry !== "string" || entry.trim().length === 0) {
+                throw new Error(`qaRework.findingIds[${index}] must be a non-empty string.`);
+            }
+            return entry;
+        }),
+        findings: findingsValue.map((entry, index) => asObject(entry, `qaRework.findings[${index}]`))
+    };
+}
+function parseArchitectRevision(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const revision = asObject(value, "architectRevision");
+    return {
+        priorPlanId: requiredString(revision, "priorPlanId"),
+        priorContentHash: requiredString(revision, "priorContentHash"),
+        feedback: requiredString(revision, "feedback")
+    };
+}
+function parseStoryDevelop(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const storyDevelop = asObject(value, "storyDevelop");
+    const dependencyWorkItemIds = storyDevelop.dependencyWorkItemIds;
+    if (!Array.isArray(dependencyWorkItemIds)) {
+        throw new Error("storyDevelop.dependencyWorkItemIds must be an array.");
+    }
+    return {
+        storyWorkItemId: requiredString(storyDevelop, "storyWorkItemId"),
+        planId: requiredString(storyDevelop, "planId"),
+        planContentHash: requiredString(storyDevelop, "planContentHash"),
+        architectTaskId: requiredString(storyDevelop, "architectTaskId"),
+        phaseId: requiredString(storyDevelop, "phaseId"),
+        dependencyWorkItemIds: dependencyWorkItemIds.map((entry, index) => {
+            if (typeof entry !== "string" || entry.trim().length === 0) {
+                throw new Error(`storyDevelop.dependencyWorkItemIds[${index}] must be a non-empty string.`);
+            }
+            return entry.trim();
+        })
+    };
+}
+function parseStoryQa(value) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const storyQa = asObject(value, "storyQa");
+    return {
+        storyWorkItemId: requiredString(storyQa, "storyWorkItemId"),
+        planId: requiredString(storyQa, "planId"),
+        planContentHash: requiredString(storyQa, "planContentHash"),
+        worktreeKey: requiredString(storyQa, "worktreeKey"),
+        branch: requiredString(storyQa, "branch"),
+        implementationPlanJson: optionalString(storyQa, "implementationPlanJson"),
+        qaPlanJson: optionalString(storyQa, "qaPlanJson"),
+        finalQaChecks: parseStringArray(storyQa.finalQaChecks, "storyQa.finalQaChecks"),
+        childTasks: parseStoryQaChildTasks(storyQa.childTasks),
+        dependencies: parseStoryQaDependencies(storyQa.dependencies)
+    };
+}
+function parseStoryQaChildTasks(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("storyQa.childTasks must be an array.");
+    }
+    return value.map((entry, index) => {
+        const child = asObject(entry, `storyQa.childTasks[${index}]`);
+        return {
+            workItemId: requiredString(child, "workItemId"),
+            title: requiredString(child, "title"),
+            architectTaskId: requiredString(child, "architectTaskId"),
+            phaseId: requiredString(child, "phaseId"),
+            phaseOrder: requiredNumber(child, "phaseOrder"),
+            dependencyWorkItemIds: parseStringArray(child.dependencyWorkItemIds, `storyQa.childTasks[${index}].dependencyWorkItemIds`),
+            spec: parseStoryQaSpec(child.spec, `storyQa.childTasks[${index}].spec`),
+            implementationArtifact: parseStoryQaArtifact(child.implementationArtifact, `storyQa.childTasks[${index}].implementationArtifact`),
+            selfReviewArtifact: parseStoryQaArtifact(child.selfReviewArtifact, `storyQa.childTasks[${index}].selfReviewArtifact`),
+            validationArtifact: parseStoryQaArtifact(child.validationArtifact, `storyQa.childTasks[${index}].validationArtifact`),
+            qaArtifact: parseStoryQaArtifact(child.qaArtifact, `storyQa.childTasks[${index}].qaArtifact`)
+        };
+    });
+}
+function parseStoryQaSpec(value, label) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const spec = asObject(value, label);
+    return {
+        version: requiredNumber(spec, "version"),
+        status: requiredString(spec, "status"),
+        path: requiredString(spec, "path"),
+        contentHash: requiredString(spec, "contentHash"),
+        body: requiredString(spec, "body")
+    };
+}
+function parseStoryQaArtifact(value, label) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    const artifact = asObject(value, label);
+    return {
+        artifactId: requiredString(artifact, "artifactId"),
+        cycleRunId: requiredString(artifact, "cycleRunId"),
+        phase: requiredString(artifact, "phase"),
+        status: requiredString(artifact, "status"),
+        producedAt: requiredString(artifact, "producedAt"),
+        path: optionalString(artifact, "path"),
+        verdictJson: optionalString(artifact, "verdictJson"),
+        evidenceJson: optionalString(artifact, "evidenceJson"),
+        findingsJson: optionalString(artifact, "findingsJson"),
+        report: optionalString(artifact, "report")
+    };
+}
+function parseStoryQaDependencies(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("storyQa.dependencies must be an array.");
+    }
+    return value.map((entry, index) => {
+        const dependency = asObject(entry, `storyQa.dependencies[${index}]`);
+        return {
+            fromWorkItemId: requiredString(dependency, "fromWorkItemId").trim(),
+            toWorkItemId: requiredString(dependency, "toWorkItemId").trim()
+        };
+    });
+}
+function parseStringArray(value, label) {
+    if (!Array.isArray(value)) {
+        throw new Error(`${label} must be an array.`);
+    }
+    return value.map((entry, index) => {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new Error(`${label}[${index}] must be a non-empty string.`);
+        }
+        return entry.trim();
+    });
+}
 function parseArtifacts(value) {
     if (value === undefined || value === null) {
         return [];
@@ -189,6 +427,16 @@ function requiredBoolean(source, key) {
     }
     return value;
 }
+function optionalBoolean(source, key) {
+    const value = source[key];
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "boolean") {
+        throw new Error(`${key} must be a boolean when provided.`);
+    }
+    return value;
+}
 function optionalPositiveInteger(source, key) {
     const value = source[key];
     if (value === undefined || value === null) {

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.1-dev.2bc1e7f19b3a";
+export declare const forgeBridgeVersion = "0.1.1-dev.2d1a116ca78d";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.1-dev.2bc1e7f19b3a";
+export const forgeBridgeVersion = "0.1.1-dev.2d1a116ca78d";

package/dist/worktree/artifact-injector.d.ts

@@ -1,5 +1,6 @@
 import type { DispatchResolvedArtifact } from "../session/session.types.js";
 export declare function injectWorktreeArtifacts(worktreePath: string, artifacts: readonly DispatchResolvedArtifact[]): Promise<void>;
+export declare function filterArtifactsForLane(artifacts: readonly DispatchResolvedArtifact[], lane: string, phase: string): readonly DispatchResolvedArtifact[];
 export declare function writeArtifact(worktreePath: string, artifact: DispatchResolvedArtifact): Promise<void>;
 export declare function selectLaneCommand(artifacts: readonly DispatchResolvedArtifact[], lane: string, phase: string): DispatchResolvedArtifact | undefined;
 export declare function resolveCommandSlug(lane: string, phase: string): string;

package/dist/worktree/artifact-injector.js

@@ -1,11 +1,73 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
+const DEBUG_OPERATIONAL_SKILLS = new Set(["debug-repro", "debug-root-cause", "debug-fix", "debug-regression"]);
+const DEBUG_OPERATIONAL_HOOKS = new Set(["debug-gate", "debug-tool-hook", "debug-rework"]);
+const ARCHITECT_OPERATIONAL_SKILLS = new Set([
+    "architect-repo-map",
+    "architect-acceptance-map",
+    "architect-contract-designer",
+    "architect-dag-planner",
+    "architect-test-plan-designer",
+    "architect-risk-review",
+    "architect-integration-strategy",
+    "architect-handoff-writer",
+    "architect-mcp-contract",
+    "architect-semantic-validator"
+]);
+const ARCHITECT_OPERATIONAL_HOOKS = new Set([
+    "architect-preflight",
+    "architect-context",
+    "architect-repo-map",
+    "architect-acceptance-map",
+    "architect-contracts",
+    "architect-plan",
+    "architect-qa-seed",
+    "architect-integration",
+    "architect-mcp-contract",
+    "architect-validate-plan",
+    "architect-risk-gate",
+    "architect-mcp-complete",
+    "architect-complete",
+    "architect-revise"
+]);
+const DRAFT_OPERATIONAL_SKILLS = new Set([
+    "draft-intent",
+    "draft-repo-context",
+    "draft-graph-context",
+    "draft-product-scope",
+    "draft-work-order-plan",
+    "draft-critic",
+    "draft-proposal"
+]);
+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"
+]);
 export async function injectWorktreeArtifacts(worktreePath, artifacts) {
     for (const artifact of artifacts) {
         await writeArtifact(worktreePath, artifact);
     }
 }
+export function filterArtifactsForLane(artifacts, lane, phase) {
+    const normalizedLane = lane.trim().toLowerCase();
+    const commandSlug = resolveCommandSlug(lane, phase).toLowerCase();
+    if (normalizedLane === "debug") {
+        return artifacts.filter((artifact) => shouldInjectDebugArtifact(artifact, commandSlug));
+    }
+    if (normalizedLane === "architect") {
+        return artifacts.filter((artifact) => shouldInjectArchitectArtifact(artifact, commandSlug));
+    }
+    if (normalizedLane === "draft") {
+        return artifacts.filter((artifact) => shouldInjectDraftArtifact(artifact, commandSlug));
+    }
+    return artifacts;
+}
 export async function writeArtifact(worktreePath, artifact) {
     const writtenHash = sha256(artifact.body);
     if (writtenHash !== artifact.contentHash.toLowerCase()) {
@@ -29,11 +91,17 @@ export function selectLaneCommand(artifacts, lane, phase) {
     return artifacts.find((artifact) => normalizedArtifactKind(artifact.kind) === "command" && artifact.slug.trim().toLowerCase() === slug);
 }
 export function resolveCommandSlug(lane, phase) {
+    const normalizedLane = lane.trim().toLowerCase();
+    if (normalizedLane === "debug") {
+        return "debug-prompt";
+    }
     const normalizedPhase = phase.trim().toLowerCase().replace(/-/g, "_");
     if (normalizedPhase === "rework") {
         return "rework-prompt";
     }
-    switch (lane.trim().toLowerCase()) {
+    switch (normalizedLane) {
+        case "draft":
+            return "draft-prompt";
         case "architect":
             return "architect-prompt";
         case "qa":
@@ -42,6 +110,54 @@ export function resolveCommandSlug(lane, phase) {
             return "dev-prompt";
     }
 }
+function shouldInjectDebugArtifact(artifact, commandSlug) {
+    if (artifact.scope.trim().toLowerCase() !== "operational") {
+        return false;
+    }
+    const slug = artifact.slug.trim().toLowerCase();
+    switch (normalizedArtifactKind(artifact.kind)) {
+        case "command":
+            return slug === commandSlug;
+        case "skill":
+            return DEBUG_OPERATIONAL_SKILLS.has(slug);
+        case "hook":
+            return DEBUG_OPERATIONAL_HOOKS.has(slug);
+        default:
+            return true;
+    }
+}
+function shouldInjectArchitectArtifact(artifact, commandSlug) {
+    if (artifact.scope.trim().toLowerCase() !== "operational") {
+        return false;
+    }
+    const slug = artifact.slug.trim().toLowerCase();
+    switch (normalizedArtifactKind(artifact.kind)) {
+        case "command":
+            return slug === commandSlug;
+        case "skill":
+            return ARCHITECT_OPERATIONAL_SKILLS.has(slug);
+        case "hook":
+            return ARCHITECT_OPERATIONAL_HOOKS.has(slug);
+        default:
+            return false;
+    }
+}
+function shouldInjectDraftArtifact(artifact, commandSlug) {
+    if (artifact.scope.trim().toLowerCase() !== "operational") {
+        return false;
+    }
+    const slug = artifact.slug.trim().toLowerCase();
+    switch (normalizedArtifactKind(artifact.kind)) {
+        case "command":
+            return slug === commandSlug;
+        case "skill":
+            return DRAFT_OPERATIONAL_SKILLS.has(slug);
+        case "hook":
+            return DRAFT_OPERATIONAL_HOOKS.has(slug);
+        default:
+            return false;
+    }
+}
 export function buildSpecBody(laneCommand, workItem, phase = "implementation") {
     const prompt = laneCommand.body.replaceAll("{workItemId}", workItem.id);
     return `---

package/dist/worktree/worktree.service.d.ts

@@ -11,6 +11,7 @@ export declare class GitWorktreeService implements WorktreeService {
     private resolveMatchingRepo;
     private ensureBaseBranch;
     private gitRefExists;
+    private currentBranch;
     private ensureGitIdentity;
 }
 export declare function normalizeBranchName(value: string | null | undefined, fallback: string): string;

package/dist/worktree/worktree.service.js

@@ -2,7 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { GitClient } from "../shared/git/git.js";
 import { ensureDirectory, isSubPath, resolveExistingDirectoryPath, safeSegment } from "../shared/path/path.js";
-import { injectWorktreeArtifacts } from "./artifact-injector.js";
+import { filterArtifactsForLane, injectWorktreeArtifacts } from "./artifact-injector.js";
 import { warmWorktreeDependencies } from "./dependency-warmer.js";
 export class GitWorktreeService {
     git;
@@ -17,9 +17,12 @@ export class GitWorktreeService {
         await this.ensureBaseBranch(repoPath, baseBranch);
         const shortId = request.workItem.id.replace(/-/g, "").slice(0, 12);
         const kind = safeSegment(request.workItem.kind, "work-item");
-        const branchName = normalizeBranchName(`${kind}/${shortId}`, "work-item/unknown");
+        const fallbackWorktreeKey = `${kind}/${shortId}`;
+        const worktreeKey = request.worktreeKey?.trim() || fallbackWorktreeKey;
+        const worktreeSegments = worktreeKeySegments(worktreeKey, kind, shortId);
+        const branchName = normalizeBranchName(worktreeSegments.join("/"), "work-item/unknown");
         const worktreeRoot = resolveWorktreeRoot(allowedRoot, repoPath);
-        const worktreePath = path.join(worktreeRoot, kind, shortId);
+        const worktreePath = path.join(worktreeRoot, ...worktreeSegments);
         const resolvedWorktreeParent = await ensureDirectory(path.dirname(worktreePath));
         if (!isSubPath(allowedRoot, resolvedWorktreeParent)) {
             throw new Error(`Worktree path must stay under ${allowedRoot}.`);
@@ -35,10 +38,17 @@ export class GitWorktreeService {
             if (!isSubPath(allowedRoot, resolvedWorktreePath)) {
                 throw new Error(`Worktree path must stay under ${allowedRoot}.`);
             }
+            const currentBranch = await this.currentBranch(resolvedWorktreePath);
+            if (currentBranch !== branchName) {
+                throw new Error(`Existing worktree ${resolvedWorktreePath} is on branch '${currentBranch}', expected '${branchName}'.`);
+            }
         }
         await this.ensureGitIdentity(resolvedWorktreePath);
-        if (request.artifacts.length > 0) {
-            await injectWorktreeArtifacts(resolvedWorktreePath, request.artifacts);
+        await clearRunArtifactRoots(resolvedWorktreePath, request);
+        const qaReworkPacketPath = await materializeQaReworkPacket(resolvedWorktreePath, request);
+        const artifacts = filterArtifactsForLane(request.artifacts, request.lane, request.phase);
+        if (artifacts.length > 0) {
+            await injectWorktreeArtifacts(resolvedWorktreePath, artifacts);
         }
         const dependencyWarm = await warmWorktreeDependencies({
             baseCheckoutPath: repoPath,
@@ -52,7 +62,8 @@ export class GitWorktreeService {
             branchName,
             baseBranch,
             cleanupWorktrees: request.cleanupWorktrees,
-            dependencyWarm
+            dependencyWarm,
+            qaReworkPacketPath
         };
     }
     async release(handle) {
@@ -171,6 +182,9 @@ export class GitWorktreeService {
     async gitRefExists(repoPath, gitRef) {
         return this.git.run(repoPath, ["show-ref", "--verify", "--quiet", gitRef]).then(() => true).catch(() => false);
     }
+    async currentBranch(repoPath) {
+        return (await this.git.run(repoPath, ["rev-parse", "--abbrev-ref", "HEAD"])).trim();
+    }
     async ensureGitIdentity(repoPath) {
         await this.git.run(repoPath, ["config", "user.email", "forge-bridge@forge.local"]);
         await this.git.run(repoPath, ["config", "user.name", "Forge Bridge"]);
@@ -192,6 +206,76 @@ function isCloneableRemote(remoteUrl) {
     }
     return trimmed.startsWith("git@") || trimmed.includes("://") || path.isAbsolute(trimmed);
 }
+async function clearRunArtifactRoots(worktreePath, request) {
+    const roots = new Set();
+    roots.add(workItemArtifactRoot(worktreePath, request.workItem.id));
+    const ownerType = normalizeOwnerType(request.ownerType);
+    const ownerId = request.ownerId?.trim();
+    if (ownerType && ownerId) {
+        roots.add(ownerArtifactRoot(worktreePath, ownerType, ownerId));
+    }
+    for (const root of roots) {
+        const resolvedRoot = path.resolve(root);
+        if (!isSubPath(worktreePath, resolvedRoot)) {
+            throw new Error(`Artifact root must stay under ${worktreePath}.`);
+        }
+        await ensureNoSymlinkPathSegments(worktreePath, resolvedRoot, "Artifact root must not traverse symlinked path segments.");
+        await fs.rm(resolvedRoot, { recursive: true, force: true });
+        await fs.mkdir(resolvedRoot, { recursive: true });
+    }
+}
+async function materializeQaReworkPacket(worktreePath, request) {
+    const qaRework = request.qaRework;
+    if (!qaRework) {
+        return undefined;
+    }
+    const artifactRoot = artifactRootForRequest(worktreePath, request);
+    const packetFileName = qaReworkPacketFileName(qaRework.packetPath);
+    const packetPath = path.join(artifactRoot, packetFileName);
+    const paths = new Set([packetPath, path.join(artifactRoot, "qa-rework-packet.json")]);
+    const packetJson = qaRework.packetJson.endsWith("\n") ? qaRework.packetJson : `${qaRework.packetJson}\n`;
+    for (const target of paths) {
+        const resolvedTarget = path.resolve(target);
+        if (!isSubPath(worktreePath, resolvedTarget)) {
+            throw new Error(`QA rework packet path must stay under ${worktreePath}.`);
+        }
+        await ensureNoSymlinkPathSegments(worktreePath, path.dirname(resolvedTarget), "QA rework packet path must not traverse symlinked path segments.");
+        await fs.mkdir(path.dirname(resolvedTarget), { recursive: true });
+        await fs.writeFile(resolvedTarget, packetJson, "utf8");
+    }
+    return path.resolve(packetPath);
+}
+function artifactRootForRequest(worktreePath, request) {
+    const ownerType = normalizeOwnerType(request.ownerType);
+    const ownerId = request.ownerId?.trim();
+    if (ownerType && ownerId) {
+        return ownerArtifactRoot(worktreePath, ownerType, ownerId);
+    }
+    return workItemArtifactRoot(worktreePath, request.workItem.id);
+}
+function workItemArtifactRoot(worktreePath, workItemId) {
+    return path.join(worktreePath, ".forge", "work-items", safeSegment(workItemId, "work item id"), "artifacts");
+}
+function ownerArtifactRoot(worktreePath, ownerType, ownerId) {
+    return path.join(worktreePath, ".forge", ownerType === "story" ? "stories" : "work-items", safeSegment(ownerId, "owner id"), "artifacts");
+}
+function normalizeOwnerType(value) {
+    const normalized = (value ?? "").trim().toLowerCase().replace(/-/g, "_");
+    if (normalized === "story") {
+        return "story";
+    }
+    if (normalized === "work_item" || normalized === "workitem" || normalized === "work item") {
+        return "work_item";
+    }
+    return null;
+}
+function qaReworkPacketFileName(packetPath) {
+    const normalized = packetPath.trim().replace(/\\/g, "/");
+    const fileName = normalized.split("/").filter(Boolean).at(-1) ?? "";
+    return /^qa-rework-packet(?:\.attempt-\d+)?\.json$/i.test(fileName)
+        ? fileName
+        : "qa-rework-packet.json";
+}
 export function normalizeBranchName(value, fallback) {
     const branch = (value?.trim() || fallback).trim();
     if (branch.length === 0 ||
@@ -204,6 +288,7 @@ export function normalizeBranchName(value, fallback) {
         branch.endsWith(".") ||
         branch.toLowerCase().endsWith(".lock") ||
         /\s/.test(branch) ||
+        // eslint-disable-next-line no-control-regex -- Git branch validation must reject ASCII control characters.
         /[\u0000-\u001f~^:?*[\\]/.test(branch) ||
         branch.split("/").some((part) => part.length === 0 || part.startsWith(".") || part.toLowerCase().endsWith(".lock"))) {
         throw new Error("Git branch name must be valid, without whitespace, and cannot start with '-'.");
@@ -240,6 +325,39 @@ async function gitMetadataExists(repoPath, allowedRoot) {
     const resolvedGitDir = await resolveExistingDirectoryPath(gitDirPath);
     return isSubPath(allowedRoot, resolvedGitDir);
 }
+async function ensureNoSymlinkPathSegments(root, targetPath, errorMessage) {
+    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(errorMessage);
+    }
+    let current = resolvedRoot;
+    const rootStat = await fs.lstat(current);
+    if (rootStat.isSymbolicLink()) {
+        throw new Error(errorMessage);
+    }
+    if (!relative) {
+        return;
+    }
+    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(errorMessage);
+        }
+    }
+}
 async function pathExists(inputPath) {
     return fs.stat(inputPath).then(() => true).catch(() => false);
 }
@@ -259,6 +377,14 @@ function uniqueStrings(values) {
     }
     return result;
 }
+function worktreeKeySegments(worktreeKey, fallbackKind, fallbackShortId) {
+    const segments = worktreeKey
+        .split("/")
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0)
+        .map((segment) => safeSegment(segment, "worktree"));
+    return segments.length > 0 ? segments : [fallbackKind, fallbackShortId];
+}
 function isSinglePathSegment(value) {
     return value.length > 0 && value !== "." && value !== ".." && !value.includes("/") && !value.includes("\\");
 }