@loucompanion/forge-bridge 0.1.1-dev.65ea6889412c → 0.1.1-dev.718bdb0018b9

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.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"];
@@ -304,6 +305,7 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
     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));
     const notes = optionalString(payload, "notes") ?? optionalString(evidenceSource, "notes") ?? "";
     const findings = qaObjectArray(payload, "findings");
     const candidateBugs = qaObjectArray(payload, "candidate_bugs");
@@ -323,6 +325,7 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
         phase: "qa",
         commands,
         browser_checks: browserChecks,
+        sidecars,
         notes
     });
     const findingsJson = jsonText({
@@ -386,6 +389,57 @@ async function writeQaCompletionArtifact(config, payload, status, producedBy) {
         producedBy
     };
 }
+async function validateQaSidecarReferences(worktreePath, workItemId, sidecars) {
+    if (sidecars.length === 0) {
+        return [];
+    }
+    const artifactRoot = 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 .forge/work-items/${workItemId}/artifacts/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);
@@ -753,15 +807,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 +1018,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 +1056,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}].`);

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);
@@ -1125,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.
 
@@ -1143,9 +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.
 
@@ -1508,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,8 +11,23 @@ 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;
@@ -80,6 +95,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

@@ -18,6 +18,7 @@ export function parseRunOnceDispatchPacket(value) {
         apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant),
         artifacts: parseArtifacts(packet.artifacts),
         warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides),
+        qaBrowser: parseQaBrowser(packet.qaBrowser),
         qaRework: parseQaRework(packet.qaRework)
     };
 }
@@ -94,7 +95,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) {
@@ -139,6 +141,43 @@ 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;
@@ -217,6 +256,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.65ea6889412c";
+export declare const forgeBridgeVersion = "0.1.1-dev.718bdb0018b9";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.1-dev.65ea6889412c";
+export const forgeBridgeVersion = "0.1.1-dev.718bdb0018b9";

package/package.json

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