@loucompanion/forge-bridge 0.1.1-dev.caea7216568f → 0.1.1-dev.e52b249f07a8

package/dist/bridge/bridge.service.js

@@ -123,6 +123,7 @@ export class ForgeBridgeService {
         const mapping = findRepoMapping(dispatch, this.config.repoMappings);
         const localPath = mapping?.localPath?.trim();
         const repoRoot = localPath ? path.dirname(path.resolve(localPath)) : this.config.defaultRepoRoot;
+        const qaLaunchTarget = normalizeQaAppLaunchTarget(mapping?.qaAppLaunchTarget) ?? dispatch.qaBrowser?.launchTarget ?? null;
         return {
             ...dispatch,
             repo: {
@@ -133,7 +134,13 @@ export class ForgeBridgeService {
             serverLocal: {
                 repoRoot,
                 cleanupWorktrees: this.config.cleanupWorktrees
-            }
+            },
+            qaBrowser: dispatch.qaBrowser
+                ? {
+                    ...dispatch.qaBrowser,
+                    launchTarget: qaLaunchTarget
+                }
+                : dispatch.qaBrowser
         };
     }
     async sendResult(leaseId, fencingToken, result) {
@@ -323,6 +330,27 @@ function findRepoMapping(dispatch, mappings) {
             (!!mapping.remoteUrl?.trim() && equalsIgnoreCase(mapping.remoteUrl, dispatch.repo.remoteUrl)));
     });
 }
+function normalizeQaAppLaunchTarget(target) {
+    if (!target) {
+        return null;
+    }
+    const routes = [...new Set((target.routes ?? []).map((route) => route.trim()).filter(Boolean))];
+    const normalized = {
+        url: cleanString(target.url),
+        command: cleanString(target.command),
+        working_directory: cleanString(target.working_directory),
+        ready_url: cleanString(target.ready_url),
+        routes,
+        notes: cleanString(target.notes)
+    };
+    return normalized.url || normalized.command || normalized.ready_url || routes.length > 0
+        ? normalized
+        : null;
+}
+function cleanString(value) {
+    const clean = value?.trim();
+    return clean ? clean : null;
+}
 function equalsIgnoreCase(left, right) {
     return !!left?.trim() && !!right?.trim() && left.trim().toLowerCase() === right.trim().toLowerCase();
 }

package/dist/bridge/bridge.types.d.ts

@@ -27,6 +27,15 @@ export interface BridgeRepoMapping {
     readonly name?: string | null;
     readonly remoteUrl?: string | null;
     readonly localPath?: string | null;
+    readonly qaAppLaunchTarget?: QaAppLaunchTarget | null;
+}
+export interface QaAppLaunchTarget {
+    readonly url?: string | null;
+    readonly command?: string | null;
+    readonly working_directory?: string | null;
+    readonly ready_url?: string | null;
+    readonly routes?: readonly string[] | null;
+    readonly notes?: string | null;
 }
 export interface BridgeProviderStatus {
     readonly signedIn?: boolean | null;

package/dist/cli/local-config.js

@@ -159,7 +159,8 @@ function normalizeRepoMappings(values) {
             repoId: cleanString(mapping.repoId),
             name: cleanString(mapping.name) ?? label,
             remoteUrl: cleanString(mapping.remoteUrl),
-            localPath: path.resolve(mapping.localPath)
+            localPath: path.resolve(mapping.localPath),
+            qaAppLaunchTarget: normalizeQaAppLaunchTarget(mapping.qaAppLaunchTarget)
         };
     })
         .sort((left, right) => left.label.localeCompare(right.label));
@@ -171,6 +172,22 @@ function normalizeLabel(value) {
     }
     return label;
 }
+function normalizeQaAppLaunchTarget(value) {
+    if (!value)
+        return undefined;
+    const routes = cleanList(value.routes);
+    const normalized = {
+        url: cleanString(value.url),
+        command: cleanString(value.command),
+        working_directory: cleanString(value.working_directory),
+        ready_url: cleanString(value.ready_url),
+        routes,
+        notes: cleanString(value.notes)
+    };
+    return normalized.url || normalized.command || normalized.ready_url || routes?.length
+        ? normalized
+        : undefined;
+}
 function cleanString(value) {
     const clean = value?.trim();
     return clean ? clean : undefined;

package/dist/session/phase-completion.d.ts

@@ -17,6 +17,8 @@ export interface CompletionToolRuntimeOptions {
 export interface CompletionToolServerConfig {
     readonly worktreePath: string;
     readonly workItemId: string;
+    readonly ownerType?: string;
+    readonly ownerId?: string;
     readonly phase: CompletionPhase;
     readonly producedBy?: string;
     readonly redactionSecrets?: readonly string[];
@@ -41,6 +43,8 @@ export interface CompletionToolCallResult {
 export interface CompletionArtifactReference {
     readonly phase: CompletionPhase;
     readonly workItemId: string;
+    readonly ownerType?: string;
+    readonly ownerId?: string;
     readonly repoPath: string;
     readonly path: string;
     readonly reportPath: string;

package/dist/session/phase-completion.js

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { redactSecrets } from "../shared/redaction/redaction.js";
+import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "./qa-sidecar-validation.js";
 const toolServerName = "forge";
 const completionRedactionSecretsEnv = "FORGE_COMPLETION_REDACTION_SECRETS";
 const completionPhaseOrder = ["implementation", "self_review", "validation"];
@@ -76,6 +77,9 @@ export function expectedCompletionToolName(phase) {
 export function artifactRootFor(worktreePath, workItemId) {
     return path.join(worktreePath, ".forge", "work-items", safePathSegment(workItemId, "work item id"), "artifacts");
 }
+function artifactRootForOwner(worktreePath, ownerType, ownerId) {
+    return path.join(worktreePath, ".forge", artifactOwnerDirectory(ownerType), safePathSegment(ownerId, "owner id"), "artifacts");
+}
 export function completionArtifactJsonPath(worktreePath, workItemId, phase) {
     return path.join(artifactRootFor(worktreePath, workItemId), phaseFiles[phase].jsonFileName);
 }
@@ -86,9 +90,13 @@ export async function prepareCompletionToolRuntime(options) {
     const phase = options.phase ?? completionPhaseFromDispatch(options.dispatch);
     const worktreePath = path.resolve(options.worktree.worktreePath);
     const workItemId = options.dispatch.workItem.id;
+    const ownerType = normalizedOwnerType(options.dispatch.cycleRun.ownerType) ?? "work_item";
+    const ownerId = options.dispatch.cycleRun.ownerId ?? workItemId;
     const mcpArgs = buildCompletionToolServerArgs({
         worktreePath,
         workItemId,
+        ownerType,
+        ownerId,
         phase,
         producedBy: `${options.dispatch.execution.provider}-cli`,
         developCycle: usesDevelopCycleCompletion(options.dispatch)
@@ -117,6 +125,10 @@ export function buildCompletionToolServerArgs(config) {
         "--produced-by",
         config.producedBy ?? "forge-completion-tool"
     ];
+    if (config.ownerType || config.ownerId) {
+        args.push("--owner-type", normalizedOwnerType(config.ownerType) ?? "work_item");
+        args.push("--owner-id", config.ownerId ?? config.workItemId);
+    }
     if (config.developCycle) {
         args.push("--develop-cycle");
     }
@@ -265,6 +277,8 @@ export async function writeCompletionArtifact(config, toolName, input) {
     const artifactWithoutHash = normalizeArtifactPayload(redactedPayload, {
         phase,
         workItemId: config.workItemId,
+        ownerType: config.ownerType,
+        ownerId: config.ownerId,
         producedBy,
         status
     });
@@ -283,6 +297,7 @@ export async function writeCompletionArtifact(config, toolName, input) {
     return {
         phase,
         workItemId: config.workItemId,
+        ...artifactReferenceOwnerFields(config),
         repoPath: path.resolve(config.worktreePath),
         path: artifactPath,
         reportPath,
@@ -292,18 +307,28 @@ export async function writeCompletionArtifact(config, toolName, input) {
     };
 }
 async function writeQaCompletionArtifact(config, payload, status, producedBy) {
-    const artifactRoot = artifactRootFor(config.worktreePath, config.workItemId);
+    const ownerFields = artifactOwnerFields(config);
+    const artifactRoot = ownerFields.owner_type && ownerFields.owner_id
+        ? artifactRootForOwner(config.worktreePath, ownerFields.owner_type, ownerFields.owner_id)
+        : artifactRootFor(config.worktreePath, config.workItemId);
     const planPath = path.join(artifactRoot, "qa.plan.json");
     const evidencePath = path.join(artifactRoot, "qa.evidence.json");
     const findingsPath = path.join(artifactRoot, "qa.findings.json");
     const verdictPath = path.join(artifactRoot, "qa.verdict.json");
     const reportPath = path.join(artifactRoot, "qa.report.md");
-    const relativeEvidencePath = qaArtifactRelativePath(config.workItemId, "qa.evidence.json");
-    const relativeFindingsPath = qaArtifactRelativePath(config.workItemId, "qa.findings.json");
-    const relativeReportPath = qaArtifactRelativePath(config.workItemId, "qa.report.md");
+    const relativeEvidencePath = ownerFields.owner_type && ownerFields.owner_id
+        ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.evidence.json")
+        : qaArtifactRelativePath(config.workItemId, "qa.evidence.json");
+    const relativeFindingsPath = ownerFields.owner_type && ownerFields.owner_id
+        ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.findings.json")
+        : qaArtifactRelativePath(config.workItemId, "qa.findings.json");
+    const relativeReportPath = ownerFields.owner_type && ownerFields.owner_id
+        ? qaArtifactRelativePathForOwner(ownerFields.owner_type, ownerFields.owner_id, "qa.report.md")
+        : qaArtifactRelativePath(config.workItemId, "qa.report.md");
     const evidenceSource = qaEvidenceSource(payload);
     const commands = qaArray(payload, "commands", evidenceSource);
     const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
+    const sidecars = await validateQaSidecarReferences(config.worktreePath, config.workItemId, qaArray(payload, "sidecars", evidenceSource), ownerFields.owner_type, ownerFields.owner_id);
     const notes = optionalString(payload, "notes") ?? optionalString(evidenceSource, "notes") ?? "";
     const findings = qaObjectArray(payload, "findings");
     const candidateBugs = qaObjectArray(payload, "candidate_bugs");
@@ -315,19 +340,23 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
     const planJson = jsonText({
         schema_version: 1,
         phase: "qa",
+        ...ownerFields,
         checklist: checklist.length > 0 ? checklist : defaultQaChecklist(status),
         acceptance_criteria: testedAcceptanceCriteria
     });
     const evidenceJson = jsonText({
         schema_version: 1,
         phase: "qa",
+        ...ownerFields,
         commands,
         browser_checks: browserChecks,
+        sidecars,
         notes
     });
     const findingsJson = jsonText({
         schema_version: 1,
         phase: "qa",
+        ...ownerFields,
         findings,
         candidate_bugs: candidateBugs
     });
@@ -347,6 +376,7 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
     const verdictWithoutHash = {
         schema_version: numberOrDefault(payload.schema_version, 1),
         phase: "qa",
+        ...ownerFields,
         status,
         summary: requiredString(payload, "summary"),
         tested_acceptance_criteria: testedAcceptanceCriteria,
@@ -378,6 +408,7 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
     return {
         phase: "qa",
         workItemId: config.workItemId,
+        ...artifactReferenceOwnerFields(config),
         repoPath: path.resolve(config.worktreePath),
         path: verdictPath,
         reportPath,
@@ -386,6 +417,59 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
         producedBy
     };
 }
+async function validateQaSidecarReferences(worktreePath, workItemId, sidecars, ownerType, ownerId) {
+    if (sidecars.length === 0) {
+        return [];
+    }
+    const artifactRoot = ownerType && ownerId
+        ? artifactRootForOwner(worktreePath, ownerType, ownerId)
+        : artifactRootFor(worktreePath, workItemId);
+    const qaSidecarRoot = path.resolve(artifactRoot, "qa");
+    const validated = [];
+    for (const [index, sidecar] of sidecars.entries()) {
+        if (!sidecar || typeof sidecar !== "object" || Array.isArray(sidecar)) {
+            throw new Error(`sidecars[${index}] must be an object.`);
+        }
+        const record = sidecar;
+        const sidecarPath = optionalString(record, "path");
+        const contentHash = optionalString(record, "content_hash");
+        const bytes = record.bytes;
+        if (!sidecarPath || !contentHash || typeof bytes !== "number" || !Number.isFinite(bytes) || bytes <= 0) {
+            throw new Error(`sidecars[${index}] must include path, content_hash, and positive bytes.`);
+        }
+        if (path.isAbsolute(sidecarPath)) {
+            throw new Error(`sidecars[${index}].path must be relative to the worktree.`);
+        }
+        const fullPath = path.resolve(worktreePath, sidecarPath);
+        if (!isPathUnderRoot(qaSidecarRoot, fullPath)) {
+            throw new Error(`sidecars[${index}].path must be under ${artifactOwnerRelativeRoot(ownerType, ownerId, workItemId)}/qa/.`);
+        }
+        const stat = await fs.lstat(fullPath).catch((error) => {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                throw new Error(`sidecars[${index}].path does not exist: ${sidecarPath}`);
+            }
+            throw error;
+        });
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`sidecars[${index}].path must reference a regular file.`);
+        }
+        await ensureNoSymbolicLinkPathSegments(qaSidecarRoot, path.dirname(fullPath), `sidecars[${index}].path must not traverse symbolic links.`);
+        if (stat.size !== bytes) {
+            throw new Error(`sidecars[${index}].bytes does not match the referenced file.`);
+        }
+        const actualHash = await sha256File(fullPath);
+        if (actualHash !== contentHash.trim().toLowerCase()) {
+            throw new Error(`sidecars[${index}].content_hash does not match the referenced file.`);
+        }
+        validated.push({
+            ...record,
+            path: path.relative(worktreePath, fullPath).split(path.sep).join("/"),
+            content_hash: actualHash,
+            bytes: stat.size
+        });
+    }
+    return validated;
+}
 export async function readCompletionArtifact(worktreePath, workItemId, phase) {
     const artifactPath = completionArtifactJsonPath(worktreePath, workItemId, phase);
     const reportPath = completionArtifactReportPath(worktreePath, workItemId, phase);
@@ -430,6 +514,8 @@ export function parseCompletionMcpArgs(argv) {
     let worktreePath = null;
     let workItemId = null;
     let phase = "implementation";
+    let ownerType;
+    let ownerId;
     let producedBy;
     let developCycle = false;
     for (let index = 1; index < argv.length; index += 1) {
@@ -440,6 +526,15 @@ export function parseCompletionMcpArgs(argv) {
         else if (arg === "--work-item-id") {
             workItemId = argv[++index] ?? null;
         }
+        else if (arg === "--owner-type") {
+            ownerType = normalizedOwnerType(argv[++index]);
+            if (!ownerType) {
+                return { ok: false, error: "mcp --owner-type must be work_item or story." };
+            }
+        }
+        else if (arg === "--owner-id") {
+            ownerId = argv[++index] ?? undefined;
+        }
         else if (arg === "--phase") {
             const rawPhase = argv[++index];
             const parsedPhase = parseStrictCompletionPhase(rawPhase);
@@ -466,6 +561,8 @@ export function parseCompletionMcpArgs(argv) {
         config: {
             worktreePath: path.resolve(worktreePath),
             workItemId,
+            ownerType,
+            ownerId,
             phase,
             producedBy,
             redactionSecrets: parseCompletionRedactionSecrets(process.env[completionRedactionSecretsEnv]),
@@ -753,15 +850,25 @@ function toolInputSchema(phase) {
             },
             browser_checks: {
                 type: "array",
-                description: "Browser/manual UI checks with URL, action, observed result, screenshot/trace references, console/network notes, and status when applicable.",
-                items: evidenceObjectSchema(["summary"], {
+                description: "Browser/manual UI checks with URL or route, action, observed result, screenshot/trace references, console/network notes, and status.",
+                items: evidenceObjectSchema(["summary", "status"], {
                     summary: { type: "string" },
                     url: { type: "string" },
+                    route: { type: "string" },
                     status: { type: "string" },
                     screenshot: { type: "string" },
                     trace: { type: "string" }
                 })
             },
+            sidecars: {
+                type: "array",
+                description: "Optional QA sidecar files already written under .forge/work-items/<id>/artifacts/qa/ with path/content_hash/bytes metadata.",
+                items: evidenceObjectSchema(["path", "content_hash", "bytes"], {
+                    path: { type: "string" },
+                    content_hash: { type: "string" },
+                    bytes: { type: "number" }
+                })
+            },
             notes: { type: "string", description: "Additional QA evidence notes." },
             evidence: {
                 type: "object",
@@ -954,6 +1061,7 @@ function validateQaPayloadShape(payload, status) {
     const evidenceSource = qaEvidenceSource(payload);
     const commands = qaArray(payload, "commands", evidenceSource);
     const browserChecks = qaArray(payload, "browser_checks", evidenceSource);
+    const sidecars = qaArray(payload, "sidecars", evidenceSource);
     const notes = optionalString(payload, "notes") ?? optionalString(evidenceSource, "notes") ?? "";
     const testedAcceptanceCriteria = qaStringArray(payload, "tested_acceptance_criteria");
     const findings = qaObjectArray(payload, "findings");
@@ -991,10 +1099,23 @@ function validateQaPayloadShape(payload, status) {
         requireEvidenceRecord(browserCheck, `browser_checks[${index}]`);
         const record = browserCheck;
         requireNonEmptyStringRecord(record, "summary", `browser_checks[${index}].`);
+        requireNonEmptyStringRecord(record, "status", `browser_checks[${index}].`);
         const checkStatus = optionalString(record, "status");
         if (status === "pass" && checkStatus && normalizedString(checkStatus) !== "pass") {
             throw new Error(`browser_checks[${index}].status must be pass when QA status is pass.`);
         }
+        if (!optionalString(record, "url") && !optionalString(record, "route")) {
+            throw new Error(`browser_checks[${index}] must include url or route.`);
+        }
+    }
+    for (const [index, sidecar] of sidecars.entries()) {
+        requireEvidenceRecord(sidecar, `sidecars[${index}]`);
+        const record = sidecar;
+        requireNonEmptyStringRecord(record, "path", `sidecars[${index}].`);
+        requireNonEmptyStringRecord(record, "content_hash", `sidecars[${index}].`);
+        if (typeof record.bytes !== "number" || !Number.isFinite(record.bytes) || record.bytes <= 0) {
+            throw new Error(`sidecars[${index}].bytes must be greater than 0.`);
+        }
     }
     for (const [index, finding] of findings.entries()) {
         requireNonEmptyStringRecord(finding, "id", `findings[${index}].`);
@@ -1075,6 +1196,8 @@ function normalizeArtifactPayload(payload, defaults) {
     normalized.schema_version = numberOrDefault(normalized.schema_version, 1);
     normalized.phase = defaults.phase;
     normalized.work_item_id = defaults.workItemId;
+    const ownerFields = artifactOwnerFields(defaults);
+    Object.assign(normalized, ownerFields);
     normalized.status = defaults.status;
     normalized.produced_by = defaults.producedBy;
     return normalized;
@@ -1328,6 +1451,36 @@ function hasSubstantiveJsonValue(value) {
 function normalizedString(value) {
     return typeof value === "string" ? value.trim().toLowerCase().replace(/-/g, "_") : "";
 }
+function normalizedOwnerType(value) {
+    const normalized = normalizedString(value);
+    return normalized === "work_item" || normalized === "story" ? normalized : undefined;
+}
+function artifactOwnerFields(config) {
+    const ownerType = normalizedOwnerType(config.ownerType);
+    const ownerId = config.ownerId?.trim();
+    if (!ownerType && !ownerId) {
+        return {};
+    }
+    return {
+        owner_type: ownerType ?? "work_item",
+        owner_id: ownerId || config.workItemId
+    };
+}
+function artifactReferenceOwnerFields(config) {
+    const owner = artifactOwnerFields(config);
+    return owner.owner_type && owner.owner_id
+        ? { ownerType: owner.owner_type, ownerId: owner.owner_id }
+        : {};
+}
+function artifactOwnerDirectory(ownerType) {
+    return normalizedOwnerType(ownerType) === "story" ? "stories" : "work-items";
+}
+function artifactOwnerRelativeRoot(ownerType, ownerId, workItemId) {
+    const owner = artifactOwnerFields({ workItemId, ownerType, ownerId });
+    return owner.owner_type && owner.owner_id
+        ? [".forge", artifactOwnerDirectory(owner.owner_type), owner.owner_id, "artifacts"].join("/")
+        : [".forge", "work-items", workItemId, "artifacts"].join("/");
+}
 function defaultQaChecklist(status) {
     return [
         "Review the validated work item against acceptance criteria.",
@@ -1338,6 +1491,9 @@ function defaultQaChecklist(status) {
 function qaArtifactRelativePath(workItemId, fileName) {
     return [".forge", "work-items", workItemId, "artifacts", fileName].join("/");
 }
+function qaArtifactRelativePathForOwner(ownerType, ownerId, fileName) {
+    return [".forge", artifactOwnerDirectory(ownerType), ownerId, "artifacts", fileName].join("/");
+}
 function jsonText(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }

package/dist/session/provider-cli/provider-cli.service.js

@@ -6,6 +6,7 @@ import readline from "node:readline";
 import { promisify } from "node:util";
 import { GitClient } from "../../shared/git/git.js";
 import { resolveCursorAgentDirectLaunch } from "../../shared/cursor-agent/cursor-agent.launch.js";
+import { ensureNoSymbolicLinkPathSegments, isPathUnderRoot, sha256File } from "../qa-sidecar-validation.js";
 import { buildSpecBody, selectLaneCommand } from "../../worktree/artifact-injector.js";
 import { codexMcpConfigArgs, completionPhaseFromDispatch, completionPromptForDevelopCycle, completionPromptForPhase, completionRedactionEnv, expectedCompletionToolName, prepareCompletionToolRuntime, readCompletionArtifact, usesDevelopCycleCompletion, writeCompletionArtifact, artifactRootFor } from "../phase-completion.js";
 import { addUsage, buildProviderUsageEvent, emptyUsage, hasUsage, readUsageNumber } from "./provider-usage.js";
@@ -171,7 +172,7 @@ export class ProcessBackedProviderCliService {
             eventType: "completion_tools_configured"
         });
         const outputState = createProviderOutputState(dispatch.execution.provider);
-        const liveQaEvents = new LiveQaArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, context.emit);
+        const liveQaEvents = new LiveQaArtifactEmitter(worktree.worktreePath, dispatch.workItem.id, dispatch, context.emit);
         let result;
         try {
             liveQaEvents.start();
@@ -211,6 +212,7 @@ export class ProcessBackedProviderCliService {
                 ? "Provider CLI QA completed but did not produce the complete durable QA artifact bundle."
                 : "Provider CLI QA completed but did not call the Forge QA completion tool.");
         }
+        enforceQaBrowserLaunchTargetGate(dispatch, qaArtifact);
         if (!liveQaEvents.hasEmitted()) {
             await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
             await emitQaStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, qaArtifact);
@@ -356,7 +358,18 @@ export class DeterministicProviderCliService {
             content: `Planning ${dispatch.execution.provider} QA checks through forge-bridge.`,
             eventType: "qa_plan"
         });
-        const summary = "All checks passed. forge-bridge QA completed.";
+        const qaBrowser = dispatch.qaBrowser;
+        const launchTarget = qaBrowser?.launchTarget ?? null;
+        const missingLaunchTarget = qaBrowser?.required === true && !hasLaunchTarget(launchTarget);
+        const browserSidecar = !missingLaunchTarget && qaBrowser?.required === true && launchTarget
+            ? deterministicBrowserSidecar(dispatch.workItem.id, launchTarget)
+            : null;
+        const browserChecks = browserSidecar && launchTarget
+            ? [deterministicBrowserCheck(launchTarget, browserSidecar.relativePath)]
+            : [];
+        const summary = missingLaunchTarget
+            ? "QA blocked because browser testing is required but no app launch target was provided."
+            : "All checks passed. forge-bridge QA completed.";
         const qaArtifact = await writeQaArtifacts({
             worktreePath: worktree.worktreePath,
             workItemId: dispatch.workItem.id,
@@ -365,13 +378,17 @@ export class DeterministicProviderCliService {
             provider: dispatch.execution.provider,
             model: dispatch.execution.model,
             command: "forge-bridge deterministic QA",
-            summary
+            summary,
+            status: missingLaunchTarget ? "blocked" : "pass",
+            blockerReason: missingLaunchTarget ? "missing_app_launch_target" : null,
+            browserChecks,
+            sidecarFiles: browserSidecar ? [browserSidecar] : []
         });
         await emitQaArtifactRecorded(context.emit, worktree.worktreePath, qaArtifact);
         await emitQaStructuredEvents(context.emit, worktree.worktreePath, dispatch.workItem.id, qaArtifact);
         await context.emit(buildProviderUsageEvent(dispatch, estimatedDeterministicUsage()));
         return {
-            summary: "forge-bridge QA passed.",
+            summary: missingLaunchTarget ? "forge-bridge QA blocked." : "forge-bridge QA passed.",
             artifact: qaArtifact,
             artifacts: [qaArtifact]
         };
@@ -483,9 +500,62 @@ const qaArtifactFileNames = {
     verdict: "qa.verdict.json",
     report: "qa.report.md"
 };
+function hasLaunchTarget(target) {
+    return Boolean(target?.url?.trim()
+        || target?.ready_url?.trim()
+        || target?.command?.trim()
+        || (target?.routes ?? []).some((route) => route.trim().length > 0));
+}
+function deterministicBrowserSidecar(workItemId, target) {
+    const route = primaryLaunchRoute(target);
+    return {
+        relativePath: qaArtifactRelativePath(workItemId, "qa/screenshots/deterministic-browser-check.txt"),
+        content: `Deterministic Forge QA browser evidence\nRoute: ${route}\nConsole errors: []\nNetwork errors: []\nResponsive checks: desktop, mobile\n`
+    };
+}
+function deterministicBrowserCheck(target, screenshotPath) {
+    const route = primaryLaunchRoute(target);
+    return {
+        route,
+        url: route,
+        status: "pass",
+        summary: "Deterministic browser QA exercised the configured launch target.",
+        actions: ["open launch target", "walk acceptance criteria", "check console/network summaries", "check responsive viewport"],
+        screenshots: [screenshotPath],
+        console_errors: [],
+        network_errors: [],
+        responsive_checks: ["desktop", "mobile"]
+    };
+}
+function primaryLaunchRoute(target) {
+    return target.ready_url?.trim()
+        || target.url?.trim()
+        || target.routes.find((route) => route.trim().length > 0)?.trim()
+        || "app launch command";
+}
+async function writeQaSidecarFiles(worktreePath, files) {
+    const sidecars = [];
+    for (const file of files) {
+        const fullPath = path.resolve(worktreePath, file.relativePath);
+        const relativePath = path.relative(worktreePath, fullPath).split(path.sep).join("/");
+        if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+            throw new Error(`QA sidecar path must stay under the worktree: ${file.relativePath}`);
+        }
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, file.content, "utf8");
+        sidecars.push({
+            path: relativePath,
+            content_hash: sha256(file.content),
+            bytes: Buffer.byteLength(file.content, "utf8")
+        });
+    }
+    return sidecars;
+}
 async function writeQaArtifacts(request) {
     const artifactRoot = artifactRootFor(request.worktreePath, request.workItemId);
     await fs.mkdir(artifactRoot, { recursive: true });
+    const sidecars = await writeQaSidecarFiles(request.worktreePath, request.sidecarFiles ?? []);
+    const status = request.status ?? "pass";
     const criterion = request.acceptanceCriteria.trim() || "Forge QA evidence exists";
     const relativeEvidencePath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.evidence);
     const relativeFindingsPath = qaArtifactRelativePath(request.workItemId, qaArtifactFileNames.findings);
@@ -503,15 +573,18 @@ async function writeQaArtifacts(request) {
     const evidenceJson = jsonText({
         schema_version: 1,
         phase: "qa",
-        commands: [
-            {
-                command: request.command,
-                exit_code: 0,
-                status: "pass",
-                summary: `${request.provider} QA completed successfully.`
-            }
-        ],
-        browser_checks: [],
+        commands: status === "blocked"
+            ? []
+            : [
+                {
+                    command: request.command,
+                    exit_code: 0,
+                    status: "pass",
+                    summary: `${request.provider} QA completed successfully.`
+                }
+            ],
+        browser_checks: request.browserChecks ?? [],
+        sidecars,
         notes: request.summary
     });
     const findingsJson = jsonText({
@@ -523,12 +596,12 @@ async function writeQaArtifacts(request) {
     const verdictJson = jsonText({
         schema_version: 1,
         phase: "qa",
-        status: "pass",
+        status,
         summary: request.summary,
-        tested_acceptance_criteria: [criterion],
+        tested_acceptance_criteria: status === "blocked" ? [] : [criterion],
         finding_ids: [],
         candidate_bug_ids: [],
-        blocker_reason: null,
+        blocker_reason: status === "blocked" ? request.blockerReason ?? "inconclusive" : null,
         evidence_path: relativeEvidencePath,
         findings_path: relativeFindingsPath,
         report_path: relativeReportPath
@@ -546,7 +619,7 @@ async function writeQaArtifacts(request) {
         verdictJson,
         report,
         producedBy: request.producedBy,
-        status: "pass",
+        status,
         phase: "qa"
     };
 }
@@ -570,6 +643,7 @@ async function readQaCompletionArtifactBundle(worktreePath, workItemId) {
     if (!artifact || !await hasCompleteQaArtifactBundle(worktreePath, workItemId)) {
         return null;
     }
+    await validateQaBundleSidecarReferences(worktreePath, workItemId);
     return artifact;
 }
 async function hasCompleteQaArtifactBundle(worktreePath, workItemId) {
@@ -590,6 +664,59 @@ async function hasCompleteQaArtifactBundle(worktreePath, workItemId) {
     }
     return true;
 }
+function enforceQaBrowserLaunchTargetGate(dispatch, artifact) {
+    const qaBrowser = dispatch.qaBrowser;
+    if (!qaBrowser?.required || hasLaunchTarget(qaBrowser.launchTarget ?? null)) {
+        return;
+    }
+    const verdict = parseJsonLine(artifact.verdictJson) ?? {};
+    const status = normalizedString(stringField(verdict, "status") ?? artifact.status ?? "");
+    const blockerReason = normalizedString(stringField(verdict, "blocker_reason") ?? "");
+    if (status !== "blocked" || blockerReason !== "missing_app_launch_target") {
+        throw new Error("QA browser testing is required but no app launch target was provided; provider must return blocked with blocker_reason missing_app_launch_target.");
+    }
+}
+async function validateQaBundleSidecarReferences(worktreePath, workItemId) {
+    const artifactRoot = artifactRootFor(worktreePath, workItemId);
+    const evidence = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.evidence));
+    const sidecars = arrayField(evidence, "sidecars");
+    if (sidecars.length === 0) {
+        return;
+    }
+    const qaSidecarRoot = path.resolve(artifactRoot, "qa");
+    for (const [index, sidecar] of sidecars.entries()) {
+        const sidecarPath = stringField(sidecar, "path");
+        const expectedHash = stringField(sidecar, "content_hash");
+        const expectedBytes = sidecar.bytes;
+        if (!sidecarPath || !expectedHash || typeof expectedBytes !== "number" || !Number.isFinite(expectedBytes) || expectedBytes <= 0) {
+            throw new Error(`QA sidecar ${index} must include path, content_hash, and positive bytes.`);
+        }
+        if (path.isAbsolute(sidecarPath)) {
+            throw new Error(`QA sidecar ${index} path must be relative to the worktree.`);
+        }
+        const fullPath = path.resolve(worktreePath, sidecarPath);
+        if (!isPathUnderRoot(qaSidecarRoot, fullPath)) {
+            throw new Error(`QA sidecar ${index} path must be under .forge/work-items/${workItemId}/artifacts/qa/.`);
+        }
+        const stat = await fs.lstat(fullPath).catch((error) => {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                throw new Error(`QA sidecar ${index} file does not exist: ${sidecarPath}`);
+            }
+            throw error;
+        });
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`QA sidecar ${index} must reference a regular file.`);
+        }
+        await ensureNoSymbolicLinkPathSegments(qaSidecarRoot, path.dirname(fullPath), `QA sidecar ${index} path must not traverse symbolic links.`);
+        if (stat.size !== expectedBytes) {
+            throw new Error(`QA sidecar ${index} bytes do not match the referenced file.`);
+        }
+        const actualHash = await sha256File(fullPath);
+        if (actualHash !== expectedHash.trim().toLowerCase()) {
+            throw new Error(`QA sidecar ${index} content_hash does not match the referenced file.`);
+        }
+    }
+}
 async function emitQaStructuredEvents(emit, worktreePath, workItemId, artifact) {
     const artifactRoot = artifactRootFor(worktreePath, workItemId);
     const plan = await readJsonObjectFile(path.join(artifactRoot, qaArtifactFileNames.plan));
@@ -634,13 +761,15 @@ async function emitQaStructuredEvents(emit, worktreePath, workItemId, artifact)
 class LiveQaArtifactEmitter {
     worktreePath;
     workItemId;
+    dispatch;
     emit;
     emitted = false;
     timer = null;
     pending = Promise.resolve();
-    constructor(worktreePath, workItemId, emit) {
+    constructor(worktreePath, workItemId, dispatch, emit) {
         this.worktreePath = worktreePath;
         this.workItemId = workItemId;
+        this.dispatch = dispatch;
         this.emit = emit;
     }
     start() {
@@ -673,6 +802,7 @@ class LiveQaArtifactEmitter {
         if (!artifact) {
             return;
         }
+        enforceQaBrowserLaunchTargetGate(this.dispatch, artifact);
         this.emitted = true;
         await emitQaArtifactRecorded(this.emit, this.worktreePath, artifact);
         await emitQaStructuredEvents(this.emit, this.worktreePath, this.workItemId, artifact);
@@ -1071,6 +1201,7 @@ function buildImplementationPrompt(dispatch, phase = completionPhaseFromDispatch
 
 Read .forge/work-items/${dispatch.workItem.id}/spec.md and any prior phase artifacts required by this phase.
 ${phaseWorkInstruction(phase)}
+${qaReworkImplementationInstruction(dispatch)}
 Use the repository's existing conventions. Run relevant tests when practical.
 Forge owns protocol files: worktree prep, injected .forge commands/hooks/skills, phase verdict artifacts, reports, and commits.
 Read Forge-provided context under .forge when needed, but do not edit .forge files or create Forge verdict/report artifacts by hand.
@@ -1084,6 +1215,7 @@ function buildDevelopCyclePrompt(dispatch, phase = completionPhaseFromDispatch(d
 
 Read .forge/work-items/${dispatch.workItem.id}/spec.md, implement the work item, self-review the diff, then validate it in this same provider session.
 Start in the ${phase.replace(/_/g, " ")} phase. Do not stop after implementation if it passes; continue through self-review and validation using the next instruction returned by each completion tool.
+${qaReworkImplementationInstruction(dispatch)}
 Use the repository's existing conventions. Run relevant tests when practical.
 Forge owns protocol files: worktree prep, injected .forge commands/hooks/skills, phase verdict artifacts, reports, and commits.
 Read Forge-provided context under .forge when needed, but do not edit .forge files or create Forge verdict/report artifacts by hand.
@@ -1092,6 +1224,28 @@ ${completionPromptForDevelopCycle(phase)}
 
 Finish with a concise summary of changed files and verification after the validation completion tool has accepted the work, or after the current phase tool records a non-pass blocker.`;
 }
+function qaReworkImplementationInstruction(dispatch) {
+    if (!dispatch.qaRework) {
+        return "";
+    }
+    return `
+QA rework context:
+- Attempt ${dispatch.qaRework.attempt}/${dispatch.qaRework.maxAttempts}
+- Rework packet: ${dispatch.qaRework.packetPath}
+- Required QA finding IDs: ${dispatch.qaRework.findingIds.join(", ")}
+Read the packet JSON and fix or explicitly dispute each listed finding. The implementation completion artifact must include resolved_findings entries for every required QA ID with qa_id, status, summary, evidence, changed_files, tests_added_or_updated, and regression_evidence.`;
+}
+function qaReworkRetestInstruction(dispatch) {
+    if (!dispatch.qaRework) {
+        return "";
+    }
+    return `
+QA retest context:
+- Rework attempt ${dispatch.qaRework.attempt}/${dispatch.qaRework.maxAttempts}
+- Rework packet: ${dispatch.qaRework.packetPath}
+- Priority finding IDs: ${dispatch.qaRework.findingIds.join(", ")}
+Prioritize retesting the listed QA findings and their required regressions before deciding pass, needs_rework, or blocked.`;
+}
 function phaseWorkInstruction(phase) {
     if (phase === "self_review") {
         return "Review the implementation diff, apply safe fixes when needed, and record remaining risks explicitly.";
@@ -1101,6 +1255,21 @@ function phaseWorkInstruction(phase) {
     }
     return "Implement the work item and keep the change focused.";
 }
+function qaBrowserInstruction(dispatch) {
+    const qaBrowser = dispatch.qaBrowser;
+    if (!qaBrowser) {
+        return "Browser/app launch context: not provided by Forge.";
+    }
+    const launchTarget = qaBrowser.launchTarget;
+    if (qaBrowser.required && !hasLaunchTarget(launchTarget ?? null)) {
+        return `Browser/app launch context:\n- UI/browser QA is required for this item.\n- No app launch target was provided.\n- Return blocked with blocker_reason: missing_app_launch_target instead of pretending browser testing occurred.\n- Artifact sidecars path when available: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
+    }
+    if (!launchTarget) {
+        return `Browser/app launch context:\n- UI/browser QA is not required by Forge heuristics for this item.\n- If you determine browser testing is needed, return blocked with blocker_reason: missing_app_launch_target unless you can safely identify a launch target from the repo.\n- Browser sidecars path: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
+    }
+    const routes = launchTarget.routes.length > 0 ? launchTarget.routes.join(", ") : "not specified";
+    return `Browser/app launch context:\n- Browser QA required: ${qaBrowser.required ? "yes" : "no, unless the diff/AC requires it"}\n- URL: ${launchTarget.url || "not specified"}\n- Ready URL: ${launchTarget.ready_url || "not specified"}\n- Launch command: ${launchTarget.command || "not specified"}\n- Working directory: ${launchTarget.working_directory || "repo root"}\n- Routes to cover: ${routes}\n- Notes: ${launchTarget.notes || "none"}\n- Browser sidecars path: ${qaBrowser.artifactsPath || `.forge/work-items/${dispatch.workItem.id}/artifacts/qa`}`;
+}
 function buildQaPrompt(dispatch) {
     return `You are Forge's QA lane running locally in a prepared git worktree.
 
@@ -1119,8 +1288,10 @@ System info / environment notes:
 ${dispatch.workItem.systemInfo || "Not provided."}
 
 Inspect the validated implementation and Forge artifacts under .forge/work-items/${dispatch.workItem.id}/artifacts/ when present, especially implementation, self-review, and validation evidence.
+${qaBrowserInstruction(dispatch)}
+${qaReworkRetestInstruction(dispatch)}
 QA is read-mostly: inspect code, run commands, and exercise browser/app flows when available, but do not edit product source or tests.
-Record concrete evidence. For UI/browser work, include browser_checks with URLs, actions, observed results, screenshots/traces when available, and console/network notes.
+Record concrete evidence. For UI/browser work, include browser_checks with URLs/routes, actions, observed results, screenshots/traces when available, console errors, failed network requests, and responsive checks. Store browser sidecars under .forge/work-items/${dispatch.workItem.id}/artifacts/qa/.
 Report in-scope defects as actionable findings with repro steps, expected/actual behavior, evidence, likely area, required fix, and required regression.
 Out-of-scope or follow-up issues belong in candidate_bugs instead of blocking the current item.
 
@@ -1483,6 +1654,9 @@ function stringField(source, key) {
     const value = source[key];
     return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
+function normalizedString(value) {
+    return value.trim().toLowerCase().replace(/-/g, "_");
+}
 function isNodeError(error) {
     return error instanceof Error && "code" in error;
 }

package/dist/session/qa-sidecar-validation.d.ts

@@ -0,0 +1,3 @@
+export declare function isPathUnderRoot(root: string, target: string): boolean;
+export declare function ensureNoSymbolicLinkPathSegments(root: string, targetDirectory: string, errorMessage: string): Promise<void>;
+export declare function sha256File(filePath: string): Promise<string>;

package/dist/session/qa-sidecar-validation.js

@@ -0,0 +1,44 @@
+import crypto from "node:crypto";
+import { createReadStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+export function isPathUnderRoot(root, target) {
+    const relative = path.relative(path.resolve(root), path.resolve(target));
+    return Boolean(relative)
+        && relative !== ".."
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative);
+}
+export async function ensureNoSymbolicLinkPathSegments(root, targetDirectory, errorMessage) {
+    const resolvedRoot = path.resolve(root);
+    const resolvedTargetDirectory = path.resolve(targetDirectory);
+    const relative = path.relative(resolvedRoot, resolvedTargetDirectory);
+    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);
+        if (stat.isSymbolicLink()) {
+            throw new Error(errorMessage);
+        }
+    }
+}
+export async function sha256File(filePath) {
+    const hash = crypto.createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}

package/dist/session/session.types.d.ts

@@ -11,6 +11,30 @@ export interface RunOnceDispatchPacket {
     readonly apiKeySecretGrant?: ApiKeySecretGrant | null;
     readonly artifacts: readonly DispatchResolvedArtifact[];
     readonly warmPathOverrides?: readonly string[];
+    readonly qaBrowser?: DispatchQaBrowserContext | null;
+    readonly qaRework?: DispatchQaReworkContext | null;
+}
+export interface DispatchQaBrowserContext {
+    readonly required: boolean;
+    readonly launchTarget?: DispatchQaAppLaunchTarget | null;
+    readonly artifactsPath: string;
+    readonly missingTargetReason?: string | null;
+}
+export interface DispatchQaAppLaunchTarget {
+    readonly url?: string | null;
+    readonly command?: string | null;
+    readonly working_directory?: string | null;
+    readonly ready_url?: string | null;
+    readonly routes: readonly string[];
+    readonly notes?: string | null;
+}
+export interface DispatchQaReworkContext {
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    readonly packetPath: string;
+    readonly packetJson: string;
+    readonly findingIds: readonly string[];
+    readonly findings: readonly Record<string, unknown>[];
 }
 export interface DispatchResolvedArtifact {
     readonly kind: string;
@@ -41,6 +65,9 @@ export interface DispatchRepo {
 }
 export interface DispatchCycleRun {
     readonly id: string;
+    readonly ownerType?: string | null;
+    readonly ownerId?: string | null;
+    readonly workItemId?: string | null;
     readonly kind: string;
     readonly phase: string;
     readonly requestedBase: string;
@@ -56,6 +83,9 @@ export interface DispatchSession {
 }
 export interface DispatchLease {
     readonly id: string;
+    readonly ownerType?: string | null;
+    readonly ownerId?: string | null;
+    readonly workItemId?: string | null;
     readonly worktreeKey: string;
     readonly lane: string;
     readonly fencingToken: string;
@@ -71,6 +101,7 @@ export interface DispatchExecution {
     readonly role: string;
     readonly lane: string;
     readonly requiresApiKeySecretGrant: boolean;
+    readonly runnerRepoLocalPath?: string | null;
 }
 export interface ApiKeySecretGrant {
     readonly grantId: string;

package/dist/session/session.types.js

@@ -17,7 +17,9 @@ export function parseRunOnceDispatchPacket(value) {
         serverLocal: parseServerLocal(packet.serverLocal),
         apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant),
         artifacts: parseArtifacts(packet.artifacts),
-        warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides)
+        warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides),
+        qaBrowser: parseQaBrowser(packet.qaBrowser),
+        qaRework: parseQaRework(packet.qaRework)
     };
 }
 export function failureResult(summary, events = []) {
@@ -55,6 +57,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 +81,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 +101,8 @@ 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 parseApiKeySecretGrant(value) {
@@ -138,6 +147,70 @@ 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 parseArtifacts(value) {
     if (value === undefined || value === null) {
         return [];
@@ -189,6 +262,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.caea7216568f";
+export declare const forgeBridgeVersion = "0.1.1-dev.e52b249f07a8";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.1-dev.caea7216568f";
+export const forgeBridgeVersion = "0.1.1-dev.e52b249f07a8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loucompanion/forge-bridge",
-  "version": "0.1.1-dev.caea7216568f",
+  "version": "0.1.1-dev.e52b249f07a8",
   "description": "Forge runner bridge CLI for connecting local developer machines to Forge dispatch.",
   "license": "UNLICENSED",
   "type": "module",