@loucompanion/forge-bridge 0.1.1-dev.242bb53ef13f → 0.1.1-dev.8dcbc6245e51

package/README.md

@@ -31,6 +31,7 @@ The bridge can also read connection settings from environment variables:
 - `FORGE_DEVICE_NAME`
 - `FORGE_REPO_ROOT`
 - `FORGE_CLI_PROVIDERS`
+- `FORGE_CODEX_MODELS` / `FORGE_CURSOR_MODELS` (optional comma-separated model ids advertised in runner capabilities)
 
 ## Repo-local development
 

package/dist/bridge/bridge.service.js

@@ -168,7 +168,7 @@ export class ForgeBridgeService {
     }
     capabilities() {
         return {
-            schemaVersion: 1,
+            schemaVersion: 2,
             activeSessionCount: this.activeSessions.size,
             cliProviders: this.config.cliProviders,
             providerStatuses: this.config.providerStatuses,
@@ -264,7 +264,7 @@ export function defaultBridgeServiceConfig(overrides = {}) {
         defaultRepoRoot: process.env.FORGE_REPO_ROOT ?? defaults.defaultRepoRoot,
         cleanupWorktrees: process.env.FORGE_CLEANUP_WORKTREES !== "false" && defaults.cleanupWorktrees,
         cliProviders,
-        providerStatuses: Object.fromEntries(cliProviders.map((provider) => [provider, { signedIn: true, version: "" }])),
+        providerStatuses: providerStatusesFor(cliProviders),
         projectLabels: splitCsv(process.env.FORGE_PROJECT_LABELS ?? ""),
         repoMappings: [],
         os: process.platform,
@@ -294,6 +294,13 @@ function normalizeServerUrl(serverUrl) {
 function positiveFiniteNumber(value, fallback) {
     return Number.isFinite(value) && value > 0 ? value : fallback;
 }
+function providerStatusesFor(providers) {
+    return Object.fromEntries(providers.map((provider) => [provider, { signedIn: true, version: "", models: configuredModelsFor(provider) }]));
+}
+function configuredModelsFor(provider) {
+    const envName = `FORGE_${provider.replace(/[^a-zA-Z0-9]/g, "_").toUpperCase()}_MODELS`;
+    return splitCsv(process.env[envName] ?? "");
+}
 function splitCsv(value) {
     return value
         .split(",")

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

@@ -28,6 +28,7 @@ export interface BridgeRepoMapping {
 export interface BridgeProviderStatus {
     readonly signedIn?: boolean | null;
     readonly version?: string | null;
+    readonly models?: readonly string[] | null;
 }
 export interface BridgeCapabilities {
     readonly schemaVersion?: number | null;

package/dist/cli/local-config.d.ts

@@ -1,6 +1,6 @@
 import type { BridgeProviderStatus, BridgeRepoMapping, BridgeServiceConfig } from "../bridge/bridge.types.js";
 export interface BridgeLocalConfig {
-    readonly schemaVersion: 1;
+    readonly schemaVersion: 1 | 2;
     readonly serverUrl?: string;
     readonly runnerId?: string;
     readonly deviceToken?: string;

package/dist/cli/local-config.js

@@ -46,7 +46,7 @@ export function applyLocalConfigDefaults(config, local) {
         defaultRepoRoot: process.env.FORGE_REPO_ROOT ?? local.defaultRepoRoot ?? config.defaultRepoRoot,
         cleanupWorktrees: local.cleanupWorktrees ?? config.cleanupWorktrees,
         cliProviders,
-        providerStatuses: local.providerStatuses ?? providerStatusesFor(cliProviders),
+        providerStatuses: normalizeProviderStatuses(local.providerStatuses) ?? providerStatusesFor(cliProviders),
         projectLabels: local.projectLabels ?? config.projectLabels,
         repoMappings: local.repoMappings ?? config.repoMappings,
         sandboxProfiles: local.sandboxProfiles ?? config.sandboxProfiles,
@@ -83,7 +83,7 @@ export async function removeRepoMapping(label) {
     return { config: next, removed: after.length !== before.length };
 }
 export function providerStatusesFor(providers) {
-    return Object.fromEntries(providers.map((provider) => [provider, { signedIn: true, version: "" }]));
+    return Object.fromEntries(providers.map((provider) => [provider, { signedIn: true, version: "", models: configuredModelsFor(provider) }]));
 }
 function parseLocalConfig(raw) {
     if (!raw.trim()) {
@@ -93,7 +93,7 @@ function parseLocalConfig(raw) {
 }
 function normalizeLocalConfig(config) {
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         serverUrl: cleanString(config.serverUrl),
         runnerId: cleanString(config.runnerId),
         deviceToken: cleanString(config.deviceToken),
@@ -101,7 +101,7 @@ function normalizeLocalConfig(config) {
         defaultRepoRoot: cleanString(config.defaultRepoRoot),
         cleanupWorktrees: config.cleanupWorktrees,
         cliProviders: cleanList(config.cliProviders),
-        providerStatuses: config.providerStatuses,
+        providerStatuses: normalizeProviderStatuses(config.providerStatuses),
         projectLabels: cleanList(config.projectLabels),
         repoMappings: normalizeRepoMappings(config.repoMappings),
         sandboxProfiles: cleanList(config.sandboxProfiles),
@@ -110,10 +110,39 @@ function normalizeLocalConfig(config) {
 }
 function emptyConfig() {
     return {
-        schemaVersion: 1,
+        schemaVersion: 2,
         repoMappings: []
     };
 }
+function normalizeProviderStatuses(values) {
+    if (!values)
+        return undefined;
+    const entries = [];
+    for (const [provider, status] of Object.entries(values)) {
+        const key = provider.trim();
+        if (!key)
+            continue;
+        entries.push([
+            key,
+            {
+                signedIn: status?.signedIn ?? true,
+                version: cleanString(status?.version),
+                models: cleanList(status?.models) ?? configuredModelsFor(key)
+            }
+        ]);
+    }
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function configuredModelsFor(provider) {
+    const envName = `FORGE_${provider.replace(/[^a-zA-Z0-9]/g, "_").toUpperCase()}_MODELS`;
+    return splitCsv(process.env[envName] ?? "");
+}
+function splitCsv(value) {
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
 function normalizeRepoMappings(values) {
     return (values ?? [])
         .filter((mapping) => !!mapping.label?.trim() && !!mapping.localPath?.trim())

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

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { GitClient } from "../../shared/git/git.js";
+import { buildSpecBody, selectLaneCommand } from "../../worktree/artifact-injector.js";
 export class DeterministicProviderCliService {
     git;
     constructor(git = new GitClient()) {
@@ -11,13 +12,23 @@ export class DeterministicProviderCliService {
         const { dispatch, worktree } = context;
         const providerCommand = buildProviderCliCommand(dispatch);
         const providerCommandText = formatProviderCliCommand(providerCommand);
-        const metadataRoot = path.join(worktree.repoPath, ".forge", "work-items", dispatch.workItem.id);
+        const metadataRoot = path.join(worktree.worktreePath, ".forge", "work-items", dispatch.workItem.id);
         const artifactRoot = path.join(metadataRoot, "artifacts");
         await fs.mkdir(artifactRoot, { recursive: true });
-        const specBody = `---\nwork_item_id: ${dispatch.workItem.id}\nstatus: approved\nlane: ${dispatch.execution.lane}\nprovider: ${yamlQuotedScalar(dispatch.execution.provider)}\nmodel: ${yamlQuotedScalar(dispatch.execution.model)}\nprovider_command: ${yamlQuotedScalar(providerCommandText)}\n---\n\n# Forge bridge implementation spec\n\nImplement **${dispatch.workItem.title}**.\n\nAcceptance:\n- prepare a task-scoped git worktree\n- emit newline JSON runner events\n- produce Forge phase artifacts\n`;
+        const laneCommand = selectLaneCommand(dispatch.artifacts, dispatch.execution.lane, dispatch.cycleRun.phase);
+        if (!laneCommand) {
+            throw new Error(`Lane command for lane '${dispatch.execution.lane}' phase '${dispatch.cycleRun.phase}' was not resolved.`);
+        }
+        const specBody = `${buildSpecBody(laneCommand, dispatch.workItem)}
+## Execution
+
+- Provider: ${singleLine(dispatch.execution.provider)}
+- Model: ${singleLine(dispatch.execution.model)}
+- Command: ${providerCommandText}
+`;
         const specPath = path.join(metadataRoot, "spec.md");
         await fs.writeFile(specPath, specBody, "utf8");
-        await fs.writeFile(path.join(metadataRoot, "spec.meta.json"), JSON.stringify({ schema_version: 1, status: "approved", produced_by: "forge-bridge" }) + "\n", "utf8");
+        await fs.writeFile(path.join(metadataRoot, "spec.meta.json"), JSON.stringify({ schema_version: 1, status: "approved", produced_by: "forge-lane-command" }) + "\n", "utf8");
         const changesetPath = path.join(worktree.worktreePath, "FORGE_PHASE5_CHANGESET.md");
         const changesetBody = `# Forge Phase 5 bridge changeset\n\nWork item: ${dispatch.workItem.id}\nTitle: ${dispatch.workItem.title}\nBranch: ${worktree.branchName}\nProvider: ${singleLine(dispatch.execution.provider)}\nModel: ${singleLine(dispatch.execution.model)}\nCommand: ${providerCommandText}\n\nThis deterministic file is written by forge-bridge run-once through the shared session/worktree service path.\n`;
         await fs.writeFile(changesetPath, changesetBody, "utf8");
@@ -51,14 +62,14 @@ export class DeterministicProviderCliService {
         return {
             summary: `forge-bridge completed ${worktree.branchName}.`,
             spec: {
-                repoPath: worktree.repoPath,
+                repoPath: worktree.worktreePath,
                 path: specPath,
                 body: specBody,
-                producedBy: "forge-bridge",
+                producedBy: "forge-lane-command",
                 status: "approved"
             },
             artifact: {
-                repoPath: worktree.repoPath,
+                repoPath: worktree.worktreePath,
                 path: artifactPath,
                 verdictJson,
                 report,

package/dist/session/session.service.js

@@ -30,7 +30,9 @@ export class BridgeSessionService {
             workItem: dispatch.workItem,
             baseBranch: dispatch.cycleRun.baseBranch || dispatch.cycleRun.requestedBase,
             allowedRepoRoot: dispatch.serverLocal.repoRoot,
-            cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees
+            cleanupWorktrees: dispatch.serverLocal.cleanupWorktrees,
+            artifacts: dispatch.artifacts,
+            warmPathOverrides: dispatch.warmPathOverrides
         });
         throwIfAborted(signal);
         await emit({
@@ -39,6 +41,9 @@ export class BridgeSessionService {
             content: `Prepared worktree ${worktree.branchName}.`,
             eventType: "worktree_prepared"
         });
+        if (worktree.dependencyWarm) {
+            await emitDependencyWarmEvents(worktree.dependencyWarm, emit);
+        }
         try {
             throwIfAborted(signal);
             const isQa = dispatch.execution.role.toLowerCase() === "qa" || dispatch.execution.lane.toLowerCase() === "qa";
@@ -90,3 +95,29 @@ function validateApiKeySecretGrant(dispatch) {
 function exactSecrets(dispatch) {
     return dispatch.apiKeySecretGrant?.secret ? [dispatch.apiKeySecretGrant.secret] : [];
 }
+async function emitDependencyWarmEvents(warm, emit) {
+    if (warm.linked.length > 0) {
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Warmed dependencies via link: ${warm.linked.join(", ")}.`,
+            eventType: "dependencies_warmed"
+        });
+    }
+    for (const fallback of warm.fallbacks) {
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Dependency install fallback (${fallback.ecosystem}): ${fallback.reason} Ran \`${fallback.command}\` in ${fallback.packageRoot}.`,
+            eventType: "dependencies_install_fallback"
+        });
+    }
+    if (warm.skipped.length > 0) {
+        await emit({
+            role: "runner",
+            kind: "checkpoint",
+            content: `Skipped warming missing dependency paths: ${warm.skipped.join(", ")}.`,
+            eventType: "dependencies_warm_skipped"
+        });
+    }
+}

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

@@ -9,6 +9,17 @@ export interface RunOnceDispatchPacket {
     readonly execution: DispatchExecution;
     readonly serverLocal: DispatchServerLocalConfig;
     readonly apiKeySecretGrant?: ApiKeySecretGrant | null;
+    readonly artifacts: readonly DispatchResolvedArtifact[];
+    readonly warmPathOverrides?: readonly string[];
+}
+export interface DispatchResolvedArtifact {
+    readonly kind: string;
+    readonly slug: string;
+    readonly scope: string;
+    readonly body: string;
+    readonly contentHash: string;
+    readonly lane?: string | null;
+    readonly event?: string | null;
 }
 export interface DispatchWorkItem {
     readonly id: string;

package/dist/session/session.types.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 export function parseRunOnceDispatchPacket(value) {
     const packet = asObject(value, "dispatch packet");
     const schemaVersion = requiredNumber(packet, "schemaVersion");
@@ -14,7 +15,9 @@ export function parseRunOnceDispatchPacket(value) {
         lease: parseLease(packet.lease),
         execution: parseExecution(packet.execution),
         serverLocal: parseServerLocal(packet.serverLocal),
-        apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant)
+        apiKeySecretGrant: parseApiKeySecretGrant(packet.apiKeySecretGrant),
+        artifacts: parseArtifacts(packet.artifacts),
+        warmPathOverrides: parseWarmPathOverrides(packet.warmPathOverrides)
     };
 }
 export function failureResult(summary, events = []) {
@@ -112,6 +115,49 @@ function parseServerLocal(value) {
         cleanupWorktrees: requiredBoolean(serverLocal, "cleanupWorktrees")
     };
 }
+function parseWarmPathOverrides(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("warmPathOverrides must be an array when provided.");
+    }
+    return value.map((entry, index) => parseWarmPathOverride(entry, index));
+}
+function parseWarmPathOverride(entry, index) {
+    if (typeof entry !== "string" || entry.trim().length === 0) {
+        throw new Error(`warmPathOverrides[${index}] must be a non-empty string.`);
+    }
+    const trimmed = entry.trim();
+    if (path.isAbsolute(trimmed) || path.posix.isAbsolute(trimmed) || path.win32.isAbsolute(trimmed)) {
+        throw new Error(`warmPathOverrides[${index}] must be a relative path.`);
+    }
+    const segments = trimmed.split(/[\\/]+/).filter(Boolean);
+    if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+        throw new Error(`warmPathOverrides[${index}] must not contain path traversal.`);
+    }
+    return segments.join("/");
+}
+function parseArtifacts(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error("artifacts must be an array when provided.");
+    }
+    return value.map((entry, index) => {
+        const artifact = asObject(entry, `artifacts[${index}]`);
+        return {
+            kind: requiredString(artifact, "kind"),
+            slug: requiredString(artifact, "slug"),
+            scope: requiredString(artifact, "scope"),
+            body: optionalString(artifact, "body") ?? "",
+            contentHash: requiredString(artifact, "contentHash"),
+            lane: optionalString(artifact, "lane"),
+            event: optionalString(artifact, "event")
+        };
+    });
+}
 function asObject(value, label) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error(`${label} must be an object.`);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.0";
+export declare const forgeBridgeVersion = "0.1.1-dev.8dcbc6245e51";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.0";
+export const forgeBridgeVersion = "0.1.1-dev.8dcbc6245e51";

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

@@ -0,0 +1,11 @@
+import type { DispatchResolvedArtifact } from "../session/session.types.js";
+export declare function injectWorktreeArtifacts(worktreePath: string, artifacts: readonly DispatchResolvedArtifact[]): Promise<void>;
+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;
+export declare function buildSpecBody(laneCommand: DispatchResolvedArtifact, workItem: {
+    readonly id: string;
+    readonly title: string;
+    readonly description: string;
+    readonly acceptanceCriteria: string;
+}): string;

package/dist/worktree/artifact-injector.js

@@ -0,0 +1,104 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+export async function injectWorktreeArtifacts(worktreePath, artifacts) {
+    for (const artifact of artifacts) {
+        await writeArtifact(worktreePath, artifact);
+    }
+}
+export async function writeArtifact(worktreePath, artifact) {
+    const writtenHash = sha256(artifact.body);
+    if (writtenHash !== artifact.contentHash.toLowerCase()) {
+        throw new Error(`Injected artifact '${artifact.slug}' content_hash mismatch (expected ${artifact.contentHash}, got ${writtenHash}).`);
+    }
+    const kindFolder = kindToFolder(artifact.kind);
+    const scope = safeArtifactSegment("scope", artifact.scope);
+    const slug = safeArtifactSegment("slug", artifact.slug);
+    const forgeRoot = path.resolve(worktreePath, ".forge");
+    const targetDir = path.resolve(forgeRoot, kindFolder, scope);
+    assertInside(forgeRoot, targetDir, "Artifact directory");
+    await fs.mkdir(targetDir, { recursive: true });
+    const filePath = path.resolve(targetDir, `${slug}.md`);
+    assertInside(forgeRoot, filePath, "Artifact file");
+    await fs.writeFile(filePath, artifact.body, "utf8");
+}
+export function selectLaneCommand(artifacts, lane, phase) {
+    const slug = resolveCommandSlug(lane, phase).toLowerCase();
+    return artifacts.find((artifact) => normalizedArtifactKind(artifact.kind) === "command" && artifact.slug.trim().toLowerCase() === slug);
+}
+export function resolveCommandSlug(lane, phase) {
+    const normalizedPhase = phase.trim().toLowerCase();
+    if (normalizedPhase === "self_review") {
+        return "self-review-prompt";
+    }
+    if (normalizedPhase === "rework") {
+        return "rework-prompt";
+    }
+    switch (lane.trim().toLowerCase()) {
+        case "architect":
+            return "architect-prompt";
+        case "qa":
+            return "qa-prompt";
+        default:
+            return "dev-prompt";
+    }
+}
+export function buildSpecBody(laneCommand, workItem) {
+    const prompt = laneCommand.body.replaceAll("{workItemId}", workItem.id);
+    return `---
+work_item_id: ${workItem.id}
+status: approved
+lane: ${laneCommand.lane ?? "develop"}
+command_slug: ${laneCommand.slug}
+---
+
+${prompt}
+
+---
+
+# Work item: ${workItem.title}
+
+${workItem.description}
+
+## Acceptance criteria
+
+${workItem.acceptanceCriteria}
+`;
+}
+function kindToFolder(kind) {
+    switch (normalizedArtifactKind(kind)) {
+        case "command":
+            return "commands";
+        case "hook":
+            return "hooks";
+        case "skill":
+            return "skills";
+        default:
+            throw new Error(`Unsupported artifact kind '${kind}'.`);
+    }
+}
+function normalizedArtifactKind(kind) {
+    return kind.trim().toLowerCase();
+}
+function safeArtifactSegment(label, value) {
+    const trimmed = value.trim();
+    if (!trimmed
+        || trimmed === "."
+        || trimmed === ".."
+        || /[\\/]/.test(trimmed)
+        || path.isAbsolute(trimmed)
+        || !/^[A-Za-z0-9._-]+$/.test(trimmed)) {
+        throw new Error(`Artifact ${label} must be a safe path segment.`);
+    }
+    return trimmed;
+}
+function assertInside(root, candidate, label) {
+    const relative = path.relative(root, candidate);
+    if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+        return;
+    }
+    throw new Error(`${label} must stay under ${root}.`);
+}
+function sha256(content) {
+    return crypto.createHash("sha256").update(content).digest("hex");
+}

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

@@ -0,0 +1,32 @@
+export type DependencyEcosystem = "node" | "dotnet" | "python";
+export interface WarmPathEntry {
+    readonly relativePath: string;
+    readonly ecosystem: DependencyEcosystem;
+    readonly packageRoot: string;
+}
+export interface WarmDependenciesRequest {
+    readonly baseCheckoutPath: string;
+    readonly worktreePath: string;
+    readonly allowedRoot: string;
+    readonly warmPathOverrides?: readonly string[];
+}
+export interface InstallFallbackResult {
+    readonly ecosystem: DependencyEcosystem;
+    readonly packageRoot: string;
+    readonly reason: string;
+    readonly command: string;
+}
+export interface WarmDependenciesResult {
+    readonly linked: readonly string[];
+    readonly skipped: readonly string[];
+    readonly fallbacks: readonly InstallFallbackResult[];
+}
+export interface CommandExecutor {
+    run(cwd: string, command: string, args: readonly string[]): Promise<void>;
+}
+export declare function detectWarmPaths(repoRoot: string, warmPathOverrides?: readonly string[]): Promise<WarmPathEntry[]>;
+export declare function warmWorktreeDependencies(request: WarmDependenciesRequest, executor?: CommandExecutor): Promise<WarmDependenciesResult>;
+export declare function createDirectoryLink(sourcePath: string, targetPath: string, allowedRoot: string): Promise<void>;
+export declare function lockfilesDiffer(baseCheckoutPath: string, worktreePath: string, packageRootRelative: string): Promise<boolean>;
+export declare function requiresInstallFallback(entry: WarmPathEntry, baseCheckoutPath: string, worktreePath: string, sourceExists: boolean): Promise<string | null>;
+export declare function declaresNativeModules(packageRootPath: string): Promise<boolean>;

package/dist/worktree/dependency-warmer.js

@@ -0,0 +1,297 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { NodeProcessRunner } from "../shared/process/process.js";
+import { isSubPath } from "../shared/path/path.js";
+const SKIP_DIR_NAMES = new Set([
+    ".git",
+    "node_modules",
+    ".venv",
+    "bin",
+    "obj",
+    ".forge-worktrees",
+    ".forge"
+]);
+const NATIVE_MODULE_HINTS = [
+    "node-gyp",
+    "bcrypt",
+    "sharp",
+    "esbuild",
+    "sqlite3",
+    "better-sqlite3",
+    "@swc/core"
+];
+export async function detectWarmPaths(repoRoot, warmPathOverrides = []) {
+    const entries = new Map();
+    await collectDetectedPaths(repoRoot, repoRoot, entries, 0);
+    for (const override of warmPathOverrides) {
+        const normalized = normalizeRelativePath(override);
+        if (!normalized) {
+            continue;
+        }
+        const packageRoot = await resolvePackageRoot(repoRoot, normalized);
+        entries.set(normalized, {
+            relativePath: normalized,
+            ecosystem: inferEcosystemFromPath(normalized),
+            packageRoot
+        });
+    }
+    return [...entries.values()];
+}
+export async function warmWorktreeDependencies(request, executor = defaultCommandExecutor) {
+    const baseCheckoutPath = path.resolve(request.baseCheckoutPath);
+    const worktreePath = path.resolve(request.worktreePath);
+    const allowedRoot = path.resolve(request.allowedRoot);
+    assertWithinRoot(allowedRoot, baseCheckoutPath, "Base checkout");
+    assertWithinRoot(allowedRoot, worktreePath, "Worktree");
+    const warmPaths = await detectWarmPaths(baseCheckoutPath, request.warmPathOverrides ?? []);
+    const linked = [];
+    const skipped = [];
+    const fallbacks = [];
+    for (const entry of warmPaths) {
+        const sourcePath = path.join(baseCheckoutPath, entry.relativePath);
+        const targetPath = path.join(worktreePath, entry.relativePath);
+        assertWithinRoot(allowedRoot, targetPath, "Warm target");
+        const sourceExists = await directoryExists(sourcePath);
+        const fallbackReason = await resolveFallbackReason(entry, baseCheckoutPath, worktreePath, sourceExists);
+        if (fallbackReason) {
+            const install = await runInstallFallback(entry, worktreePath, fallbackReason, executor);
+            fallbacks.push(install);
+            continue;
+        }
+        if (!sourceExists) {
+            skipped.push(entry.relativePath);
+            continue;
+        }
+        await createDirectoryLink(sourcePath, targetPath, allowedRoot);
+        linked.push(entry.relativePath);
+    }
+    return { linked, skipped, fallbacks };
+}
+export async function createDirectoryLink(sourcePath, targetPath, allowedRoot) {
+    const resolvedSource = path.resolve(sourcePath);
+    const resolvedTarget = path.resolve(targetPath);
+    const resolvedRoot = path.resolve(allowedRoot);
+    assertWithinRoot(resolvedRoot, resolvedSource, "Link source");
+    assertWithinRoot(resolvedRoot, resolvedTarget, "Link target");
+    assertWithinRoot(resolvedRoot, path.dirname(resolvedTarget), "Link target parent");
+    const stat = await fs.stat(resolvedSource).catch(() => null);
+    if (!stat?.isDirectory()) {
+        throw new Error(`Link source must be an existing directory: ${resolvedSource}`);
+    }
+    await fs.rm(resolvedTarget, { recursive: true, force: true });
+    await fs.mkdir(path.dirname(resolvedTarget), { recursive: true });
+    if (process.platform === "win32") {
+        await fs.symlink(resolvedSource, resolvedTarget, "junction");
+        return;
+    }
+    await fs.symlink(resolvedSource, resolvedTarget, "dir");
+}
+async function collectDetectedPaths(repoRoot, currentDir, entries, depth) {
+    if (depth > 6) {
+        return;
+    }
+    const relativeDir = path.relative(repoRoot, currentDir);
+    const normalizedDir = relativeDir.length === 0 ? "" : normalizeRelativePath(relativeDir);
+    if (normalizedDir) {
+        const packageJsonPath = path.join(currentDir, "package.json");
+        if (await pathExists(packageJsonPath)) {
+            addEntry(entries, repoRoot, normalizedDir, "node_modules", "node");
+        }
+        if (await hasPythonMarker(currentDir)) {
+            addEntry(entries, repoRoot, normalizedDir, ".venv", "python");
+        }
+        if (await hasDotNetMarker(currentDir)) {
+            const binRelative = joinRelative(normalizedDir, "bin");
+            const objRelative = joinRelative(normalizedDir, "obj");
+            if (await directoryExists(path.join(repoRoot, binRelative))) {
+                addEntry(entries, repoRoot, normalizedDir, "bin", "dotnet", binRelative);
+            }
+            if (await directoryExists(path.join(repoRoot, objRelative))) {
+                addEntry(entries, repoRoot, normalizedDir, "obj", "dotnet", objRelative);
+            }
+        }
+    }
+    else {
+        if (await pathExists(path.join(currentDir, "package.json"))) {
+            addEntry(entries, repoRoot, "", "node_modules", "node");
+        }
+        if (await hasPythonMarker(currentDir)) {
+            addEntry(entries, repoRoot, "", ".venv", "python");
+        }
+        if (await hasDotNetMarker(currentDir)) {
+            if (await directoryExists(path.join(repoRoot, "bin"))) {
+                addEntry(entries, repoRoot, "", "bin", "dotnet", "bin");
+            }
+            if (await directoryExists(path.join(repoRoot, "obj"))) {
+                addEntry(entries, repoRoot, "", "obj", "dotnet", "obj");
+            }
+        }
+    }
+    const children = await fs.readdir(currentDir, { withFileTypes: true }).catch(() => []);
+    for (const child of children) {
+        if (!child.isDirectory() || SKIP_DIR_NAMES.has(child.name) || child.name.startsWith(".")) {
+            continue;
+        }
+        await collectDetectedPaths(repoRoot, path.join(currentDir, child.name), entries, depth + 1);
+    }
+}
+function addEntry(entries, repoRoot, packageRootRelative, folderName, ecosystem, explicitRelativePath) {
+    const relativePath = explicitRelativePath ?? joinRelative(packageRootRelative, folderName);
+    entries.set(relativePath, {
+        relativePath,
+        ecosystem,
+        packageRoot: packageRootRelative.length > 0 ? packageRootRelative : "."
+    });
+}
+async function resolveFallbackReason(entry, baseCheckoutPath, worktreePath, sourceExists) {
+    if (entry.ecosystem === "node") {
+        if (!sourceExists) {
+            return "Base checkout is missing node_modules.";
+        }
+        if (await lockfilesDiffer(baseCheckoutPath, worktreePath, entry.packageRoot)) {
+            return "Lockfile differs between base checkout and worktree.";
+        }
+    }
+    if (entry.ecosystem === "python" && !sourceExists) {
+        return "Base checkout is missing .venv.";
+    }
+    return null;
+}
+export async function lockfilesDiffer(baseCheckoutPath, worktreePath, packageRootRelative) {
+    const lockfileNames = ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "npm-shrinkwrap.json"];
+    const packageRoot = packageRootRelative === "." ? "" : packageRootRelative;
+    for (const lockfile of lockfileNames) {
+        const baseLock = path.join(baseCheckoutPath, packageRoot, lockfile);
+        const worktreeLock = path.join(worktreePath, packageRoot, lockfile);
+        const baseExists = await pathExists(baseLock);
+        const worktreeExists = await pathExists(worktreeLock);
+        if (baseExists !== worktreeExists) {
+            return true;
+        }
+        if (!baseExists) {
+            continue;
+        }
+        const baseHash = await sha256File(baseLock);
+        const worktreeHash = await sha256File(worktreeLock);
+        if (baseHash !== worktreeHash) {
+            return true;
+        }
+    }
+    return false;
+}
+async function runInstallFallback(entry, worktreePath, reason, executor) {
+    const cwd = path.join(worktreePath, entry.packageRoot === "." ? "" : entry.packageRoot);
+    if (entry.ecosystem === "node") {
+        const lockPath = path.join(cwd, "package-lock.json");
+        const args = (await pathExists(lockPath)) ? ["ci"] : ["install"];
+        await executor.run(cwd, "npm", args);
+        return { ecosystem: entry.ecosystem, packageRoot: entry.packageRoot, reason, command: `npm ${args.join(" ")}` };
+    }
+    if (entry.ecosystem === "python") {
+        await executor.run(cwd, "python", ["-m", "venv", ".venv"]);
+        const requirements = path.join(cwd, "requirements.txt");
+        if (await pathExists(requirements)) {
+            const pip = process.platform === "win32" ? path.join(".venv", "Scripts", "pip") : path.join(".venv", "bin", "pip");
+            await executor.run(cwd, pip, ["install", "-r", "requirements.txt"]);
+            return {
+                ecosystem: entry.ecosystem,
+                packageRoot: entry.packageRoot,
+                reason,
+                command: "python -m venv .venv && pip install -r requirements.txt"
+            };
+        }
+        return {
+            ecosystem: entry.ecosystem,
+            packageRoot: entry.packageRoot,
+            reason,
+            command: "python -m venv .venv"
+        };
+    }
+    await executor.run(cwd, "dotnet", ["restore"]);
+    return {
+        ecosystem: entry.ecosystem,
+        packageRoot: entry.packageRoot,
+        reason,
+        command: "dotnet restore"
+    };
+}
+export async function requiresInstallFallback(entry, baseCheckoutPath, worktreePath, sourceExists) {
+    return resolveFallbackReason(entry, baseCheckoutPath, worktreePath, sourceExists);
+}
+export async function declaresNativeModules(packageRootPath) {
+    const packageJsonPath = path.join(packageRootPath, "package.json");
+    if (!(await pathExists(packageJsonPath))) {
+        return false;
+    }
+    const raw = await fs.readFile(packageJsonPath, "utf8");
+    const lower = raw.toLowerCase();
+    return NATIVE_MODULE_HINTS.some((hint) => lower.includes(`"${hint}"`));
+}
+async function hasPythonMarker(dir) {
+    return (await pathExists(path.join(dir, "pyproject.toml")))
+        || (await pathExists(path.join(dir, "requirements.txt")));
+}
+async function hasDotNetMarker(dir) {
+    const entries = await fs.readdir(dir).catch(() => []);
+    return entries.some((name) => name.endsWith(".csproj") || name.endsWith(".sln"));
+}
+async function resolvePackageRoot(repoRoot, relativePath) {
+    const segments = relativePath.split("/").filter(Boolean);
+    if (segments.length === 0) {
+        return ".";
+    }
+    const last = segments[segments.length - 1];
+    if (last === "node_modules" || last === ".venv" || last === "bin" || last === "obj") {
+        const parent = segments.slice(0, -1).join("/");
+        return parent.length > 0 ? parent : ".";
+    }
+    const candidate = path.join(repoRoot, ...segments);
+    if (await pathExists(path.join(candidate, "package.json"))) {
+        return segments.join("/");
+    }
+    return segments.slice(0, -1).join("/") || ".";
+}
+function inferEcosystemFromPath(relativePath) {
+    const base = path.basename(relativePath);
+    if (base === ".venv") {
+        return "python";
+    }
+    if (base === "bin" || base === "obj") {
+        return "dotnet";
+    }
+    return "node";
+}
+function joinRelative(packageRootRelative, folderName) {
+    return packageRootRelative.length > 0
+        ? `${packageRootRelative}/${folderName}`.replace(/\\/g, "/")
+        : folderName;
+}
+function normalizeRelativePath(value) {
+    return value.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+function assertWithinRoot(root, candidate, label) {
+    if (!isSubPath(root, candidate)) {
+        throw new Error(`${label} must stay under ${root}.`);
+    }
+}
+async function directoryExists(inputPath) {
+    const stat = await fs.stat(inputPath).catch(() => null);
+    return stat?.isDirectory() ?? false;
+}
+async function pathExists(inputPath) {
+    return (await fs.stat(inputPath).catch(() => null)) !== null;
+}
+async function sha256File(filePath) {
+    const crypto = await import("node:crypto");
+    const content = await fs.readFile(filePath);
+    return crypto.createHash("sha256").update(content).digest("hex");
+}
+const defaultCommandExecutor = {
+    async run(cwd, command, args) {
+        const result = await defaultProcessRunner.run({ command, cwd, args });
+        if (result.exitCode !== 0) {
+            throw new Error(`${command} ${args.join(" ")} failed (${result.exitCode}): ${result.stderr.trim()}`);
+        }
+    }
+};
+const defaultProcessRunner = new NodeProcessRunner();

package/dist/worktree/index.d.ts

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

package/dist/worktree/index.js

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

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

@@ -7,6 +7,8 @@ export declare class GitWorktreeService implements WorktreeService {
     prepare(request: WorktreePrepareRequest): Promise<WorktreeHandle>;
     release(handle: WorktreeHandle): Promise<void>;
     private resolveRepoPath;
+    private ensureBaseBranch;
+    private gitRefExists;
     private ensureGitIdentity;
 }
 export declare function normalizeBranchName(value: string | null | undefined, fallback: string): string;

package/dist/worktree/worktree.service.js

@@ -2,6 +2,8 @@ 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 { warmWorktreeDependencies } from "./dependency-warmer.js";
 export class GitWorktreeService {
     git;
     constructor(git = new GitClient()) {
@@ -9,9 +11,10 @@ export class GitWorktreeService {
     }
     async prepare(request) {
         const allowedRoot = await ensureDirectory(request.allowedRepoRoot);
-        const repoPath = await this.resolveRepoPath(request.repo, allowedRoot);
         const baseBranch = normalizeBranchName(request.baseBranch, "develop");
+        const repoPath = await this.resolveRepoPath(request.repo, allowedRoot, baseBranch);
         await this.ensureGitIdentity(repoPath);
+        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");
@@ -34,12 +37,22 @@ export class GitWorktreeService {
             }
         }
         await this.ensureGitIdentity(resolvedWorktreePath);
+        if (request.artifacts.length > 0) {
+            await injectWorktreeArtifacts(resolvedWorktreePath, request.artifacts);
+        }
+        const dependencyWarm = await warmWorktreeDependencies({
+            baseCheckoutPath: repoPath,
+            worktreePath: resolvedWorktreePath,
+            allowedRoot,
+            warmPathOverrides: request.warmPathOverrides
+        });
         return {
             repoPath,
             worktreePath: resolvedWorktreePath,
             branchName,
             baseBranch,
-            cleanupWorktrees: request.cleanupWorktrees
+            cleanupWorktrees: request.cleanupWorktrees,
+            dependencyWarm
         };
     }
     async release(handle) {
@@ -54,7 +67,7 @@ export class GitWorktreeService {
             await fs.rm(handle.worktreePath, { recursive: true, force: true });
         }
     }
-    async resolveRepoPath(repo, allowedRoot) {
+    async resolveRepoPath(repo, allowedRoot, baseBranch) {
         if (repo.serverLocalPath && repo.serverLocalPath.trim().length > 0) {
             const requestedPath = await resolveExistingDirectoryPath(repo.serverLocalPath);
             if (!isSubPath(allowedRoot, requestedPath) || !(await gitMetadataExists(requestedPath, allowedRoot))) {
@@ -67,12 +80,28 @@ export class GitWorktreeService {
         }
         const repoPath = path.join(allowedRoot, `${safeSegment(repo.name, "repo")}-${repo.id.replace(/-/g, "")}`);
         if (!(await gitMetadataExists(repoPath, allowedRoot))) {
-            await fs.mkdir(repoPath, { recursive: true });
-            await this.git.run(repoPath, ["init", "-b", normalizeBranchName(repo.defaultBranch, "develop")]);
-            await this.ensureGitIdentity(repoPath);
-            await fs.writeFile(path.join(repoPath, "README.md"), `# ${repo.name}\n`, "utf8");
-            await this.git.run(repoPath, ["add", "README.md"]);
-            await this.git.run(repoPath, ["commit", "-m", "seed forge bridge repo"]);
+            const repoPathExists = await pathExists(repoPath);
+            if (repoPathExists) {
+                throw new Error(`Repository path ${repoPath} exists but is not a git checkout.`);
+            }
+            if (isCloneableRemote(repo.remoteUrl)) {
+                await fs.mkdir(path.dirname(repoPath), { recursive: true });
+                try {
+                    await this.git.run(path.dirname(repoPath), ["clone", "--origin", "origin", repo.remoteUrl.trim(), repoPath]);
+                }
+                catch (err) {
+                    await fs.rm(repoPath, { recursive: true, force: true });
+                    throw err;
+                }
+            }
+            else {
+                await fs.mkdir(repoPath, { recursive: true });
+                await this.git.run(repoPath, ["init", "-b", baseBranch]);
+                await this.ensureGitIdentity(repoPath);
+                await fs.writeFile(path.join(repoPath, "README.md"), `# ${repo.name}\n`, "utf8");
+                await this.git.run(repoPath, ["add", "README.md"]);
+                await this.git.run(repoPath, ["commit", "-m", "seed forge bridge repo"]);
+            }
         }
         const resolved = await resolveExistingDirectoryPath(repoPath);
         if (!isSubPath(allowedRoot, resolved)) {
@@ -80,11 +109,36 @@ export class GitWorktreeService {
         }
         return resolved;
     }
+    async ensureBaseBranch(repoPath, baseBranch) {
+        if (await this.gitRefExists(repoPath, `refs/heads/${baseBranch}`)) {
+            return;
+        }
+        const origin = await this.git.run(repoPath, ["remote", "get-url", "origin"]).catch(() => "");
+        if (origin.trim().length === 0) {
+            throw new Error(`Base branch '${baseBranch}' was not found in the local checkout.`);
+        }
+        await this.git.run(repoPath, ["fetch", "origin", `${baseBranch}:refs/remotes/origin/${baseBranch}`]).catch(() => "");
+        if (await this.gitRefExists(repoPath, `refs/remotes/origin/${baseBranch}`)) {
+            await this.git.run(repoPath, ["branch", baseBranch, `refs/remotes/origin/${baseBranch}`]);
+            return;
+        }
+        throw new Error(`Base branch '${baseBranch}' was not found locally or on origin.`);
+    }
+    async gitRefExists(repoPath, gitRef) {
+        return this.git.run(repoPath, ["show-ref", "--verify", "--quiet", gitRef]).then(() => true).catch(() => false);
+    }
     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"]);
     }
 }
+function isCloneableRemote(remoteUrl) {
+    const trimmed = remoteUrl?.trim() ?? "";
+    if (trimmed.length === 0 || trimmed.startsWith("local://")) {
+        return false;
+    }
+    return trimmed.startsWith("git@") || trimmed.includes("://") || path.isAbsolute(trimmed);
+}
 export function normalizeBranchName(value, fallback) {
     const branch = (value?.trim() || fallback).trim();
     if (branch.length === 0 ||
@@ -133,6 +187,9 @@ async function gitMetadataExists(repoPath, allowedRoot) {
     const resolvedGitDir = await resolveExistingDirectoryPath(gitDirPath);
     return isSubPath(allowedRoot, resolvedGitDir);
 }
+async function pathExists(inputPath) {
+    return fs.stat(inputPath).then(() => true).catch(() => false);
+}
 async function directoryExists(inputPath) {
     const stat = await fs.stat(inputPath).catch(() => null);
     return stat?.isDirectory() ?? false;

package/dist/worktree/worktree.types.d.ts

@@ -1,10 +1,13 @@
-import type { DispatchRepo, DispatchWorkItem } from "../session/session.types.js";
+import type { DispatchRepo, DispatchWorkItem, DispatchResolvedArtifact } from "../session/session.types.js";
+import type { WarmDependenciesResult } from "./dependency-warmer.js";
 export interface WorktreePrepareRequest {
     readonly repo: DispatchRepo;
     readonly workItem: DispatchWorkItem;
     readonly baseBranch: string;
     readonly allowedRepoRoot: string;
     readonly cleanupWorktrees: boolean;
+    readonly artifacts: readonly DispatchResolvedArtifact[];
+    readonly warmPathOverrides?: readonly string[];
 }
 export interface WorktreeHandle {
     readonly repoPath: string;
@@ -12,4 +15,5 @@ export interface WorktreeHandle {
     readonly branchName: string;
     readonly baseBranch: string;
     readonly cleanupWorktrees: boolean;
+    readonly dependencyWarm?: WarmDependenciesResult;
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@loucompanion/forge-bridge",
-  "version": "0.1.1-dev.242bb53ef13f",
+  "version": "0.1.1-dev.8dcbc6245e51",
   "description": "Forge runner bridge CLI for connecting local developer machines to Forge dispatch.",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {
-    "forge-bridge": "./dist/cli/bin.js"
+    "forge-bridge": "dist/cli/bin.js"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",