forgeos 0.1.0-alpha.67 → 0.1.0-alpha.68

package/scripts/install-agent-fabric-skill.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { basename, dirname, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+function sourceInventory(directory) {
+  const files = [];
+  function visit(base, relative = '') {
+    for (const entry of readdirSync(base, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (!relative && ['runtime.json', 'installation.json'].includes(entry.name)) continue;
+      const name = `${relative}/${entry.name}`;
+      if (entry.isDirectory()) visit(resolve(base, entry.name), name);
+      else files.push(name.slice(1));
+    }
+  }
+  visit(directory);
+  return files;
+}
+function sourceDigest(directory, inventory) {
+  const hash = createHash('sha256');
+  for (const name of inventory) {
+    const file = resolve(directory, name);
+    try {
+      const stat = lstatSync(file);
+      hash.update(JSON.stringify([name, stat.isSymbolicLink() ? 'link' : 'file']));
+      hash.update(stat.isSymbolicLink() ? readlinkSync(file) : readFileSync(file));
+    } catch { return null; }
+  }
+  return hash.digest('hex');
+}
+function canonicalPath(path) {
+  try { return realpathSync(path); } catch {
+    const parent = dirname(path);
+    if (parent === path) throw new Error(`Cannot resolve destination: ${path}`);
+    return resolve(canonicalPath(parent), basename(path));
+  }
+}
+try {
+  const args = process.argv.slice(2);
+  const known = new Set(['--dest', '--runtime', '--dry-run', '--replace', '--help']);
+  const options = {};
+  for (let index = 0; index < args.length; index++) {
+    const flag = args[index];
+    if (!known.has(flag)) throw new Error(`Unknown option: ${flag}`);
+    if (flag === '--dest' || flag === '--runtime') {
+      if (!args[index + 1] || args[index + 1].startsWith('--')) throw new Error(`${flag} requires a path`);
+      options[flag] = args[++index];
+    } else options[flag] = true;
+  }
+  if (options['--help']) {
+    process.stdout.write('Install portable Agent Fabric skill: --dest <skills-root> --runtime <forge.mjs> --dry-run --replace\nDefaults: ~/.agents/skills and this package runtime. No MCP or hooks are configured.\n');
+  } else {
+    const source = resolve(packageRoot, '.agents/skills/forge-agent-fabric');
+    const skillsRoot = resolve(options['--dest'] || resolve(homedir(), '.agents/skills'));
+    const target = resolve(skillsRoot, 'forge-agent-fabric');
+    const runtime = realpathSync(resolve(options['--runtime'] || resolve(packageRoot, 'bin/forge.mjs')));
+    const marker = resolve(target, 'installation.json');
+    let installed = {};
+    let owned = false;
+    if (existsSync(marker)) {
+      try { installed = JSON.parse(readFileSync(marker, 'utf8')); owned = installed.installer === 'forgeos-agent-fabric-skill'; } catch {}
+    }
+    if (existsSync(target) && !owned && !options['--replace']) {
+      throw new Error(`Existing skill is not managed by this installer: ${target}. Review it and use --replace to preserve a backup and replace it.`);
+    }
+    const normalize = (path) => process.platform === 'win32' ? path.toLowerCase() : path;
+    const canonicalSource = normalize(canonicalPath(source));
+    const canonicalTarget = normalize(canonicalPath(target));
+    if (canonicalTarget === canonicalSource || canonicalTarget.startsWith(`${canonicalSource}${sep}`) || canonicalSource.startsWith(`${canonicalTarget}${sep}`)) {
+      throw new Error('Installation destination must differ from the packaged source skill.');
+    }
+    const inventory = sourceInventory(source);
+    const digest = sourceDigest(source, inventory);
+    if (!digest) throw new Error('Packaged skill contains unreadable source files.');
+    let existingRuntime = {};
+    try { existingRuntime = JSON.parse(readFileSync(resolve(target, 'runtime.json'), 'utf8')); } catch {}
+    const unchanged = owned && installed.sourceDigest === digest && sourceDigest(target, inventory) === digest && existingRuntime.cliPath === runtime && existingRuntime.nodeExecutable === process.execPath;
+    const result = { target, cliPath: runtime, nodeExecutable: process.execPath, dryRun: !!options['--dry-run'], replacesExisting: existsSync(target), unchanged };
+    if (!options['--dry-run'] && !unchanged) {
+      // Stage outside the discovery root so incomplete or backup copies are not skills.
+      const stagingRoot = resolve(dirname(skillsRoot), 'skill-backups');
+      mkdirSync(stagingRoot, { recursive: true });
+      const staged = resolve(stagingRoot, `forge-agent-fabric-stage-${randomUUID()}`);
+      cpSync(source, staged, { recursive: true, verbatimSymlinks: true });
+      writeFileSync(resolve(staged, 'runtime.json'), `${JSON.stringify({ cliPath: runtime, nodeExecutable: process.execPath }, null, 2)}\n`);
+      writeFileSync(resolve(staged, 'installation.json'), `${JSON.stringify({ installer: 'forgeos-agent-fabric-skill', version: 1, sourceDigest: digest }, null, 2)}\n`);
+      mkdirSync(skillsRoot, { recursive: true });
+      if (existsSync(target)) {
+        result.backup = resolve(stagingRoot, `forge-agent-fabric-backup-${randomUUID()}`);
+        renameSync(target, result.backup);
+      }
+      try { renameSync(staged, target); } catch (error) {
+        if (result.backup && !existsSync(target)) renameSync(result.backup, target);
+        throw error;
+      }
+    }
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

package/src/forge/_generated/releaseManifest.json

@@ -1 +1 @@
-{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.67","releaseId":"forgeos@0.1.0-alpha.67+unknown","schemaVersion":"0.1.0"}
+{"defaultProvider":"local","diagnostics":[],"env":{"deployEnv":"FORGE_DEPLOY_ENV","deployId":"FORGE_DEPLOY_ID","publicReleaseId":"NEXT_PUBLIC_FORGE_RELEASE_ID","releaseId":"FORGE_RELEASE_ID"},"gitSha":"unknown","optionalProviders":["local","sentry-compatible","sentry","glitchtip","bugsink","otel","custom"],"packageName":"forgeos","packageVersion":"0.1.0-alpha.68","releaseId":"forgeos@0.1.0-alpha.68+unknown","schemaVersion":"0.1.0"}

package/src/forge/_generated/releaseManifest.ts

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.67 input=cad72fb61cedf1a3702763e37d3d5706a149a8719284ec9090a960aa3a4e1e61 content=ffe58b6ba6641fa97fccc9a8c5cfec32c0df3dd112985346eb3ede12613986a1
+// @forge-generated generator=0.1.0-alpha.68 input=eb85ce79777e8854119a312edd29262099578bdd5f8be82c03b5f0caae80f391 content=146d6370b923fb349aebc9c7cab538dab545ebbadccabe2f67f16e4018c91fb9
 export const releaseManifest = {
   "defaultProvider": "local",
   "diagnostics": [],
@@ -19,7 +19,7 @@ export const releaseManifest = {
     "custom"
   ],
   "packageName": "forgeos",
-  "packageVersion": "0.1.0-alpha.67",
-  "releaseId": "forgeos@0.1.0-alpha.67+unknown",
+  "packageVersion": "0.1.0-alpha.68",
+  "releaseId": "forgeos@0.1.0-alpha.68+unknown",
   "schemaVersion": "0.1.0"
 } as const;

package/src/forge/agent-fabric/local-task-server.ts

@@ -10,7 +10,8 @@ import { AttachedTaskError } from "./attached-task-contract.ts";
 import { AgentFabricError, isAgentFabricError } from "./errors.ts";
 import { LocalTaskService, type LocalTaskStatus } from "./local-task-service.ts";
 import type { LocalMemoryEntry } from "./local-intelligence.ts";
-import { localFabricPath } from "./local-paths.ts";
+import { localFabricPath } from "./local-paths.ts";
+import { applyFabricProfile } from "./project-profile.ts";
 
 const MAX_REQUEST_BYTES = 40 * 1024;
 const ENDPOINT_FILENAME = "owner-endpoint.json";
@@ -51,7 +52,7 @@ function processIsAlive(pid: number): boolean {
   }
 }
 
-function readEndpoint(repositoryRoot: string): OwnerEndpoint | null {
+function readEndpoint(repositoryRoot: string, pruneStale = true): OwnerEndpoint | null {
   const path = endpointPath(repositoryRoot);
   if (!existsSync(path)) return null;
   if (lstatSync(path).isSymbolicLink()) {
@@ -73,7 +74,7 @@ function readEndpoint(repositoryRoot: string): OwnerEndpoint | null {
   if (!processIsAlive(item.pid!)) {
     // A killed owner cannot hold PGlite. Remove only the exact endpoint bytes
     // read above; a replacement means another owner is starting.
-    if (readFileSync(path).equals(bytes)) unlinkSync(path);
+    if (pruneStale && readFileSync(path).equals(bytes)) unlinkSync(path);
     return null;
   }
   return item as OwnerEndpoint;
@@ -141,11 +142,33 @@ function dispatchMemory(service: LocalTaskService, action: LocalMemoryAction, re
   return { deleted: service.forgetMemory(request.id) };
 }
 
-export interface LocalTaskOwnerServer {
+export interface LocalTaskOwnerServer {
   repositoryRoot: string;
   port: number;
   close(): Promise<void>;
-}
+}
+
+/** Authenticated and read-only. Endpoint secrets never leave this module. */
+export async function probeLocalOwner(repositoryRoot: string): Promise<{ repositoryRoot: string; pid: number; port: number } | null> {
+  const endpoint = readEndpoint(realpathSync(repositoryRoot), false);
+  if (!endpoint) return null;
+  const request = (action: string, body: object) => fetch(`http://127.0.0.1:${endpoint.port}/v1/${action}`, {
+    method: "POST", headers: { Authorization: `Bearer ${endpoint.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body), redirect: "manual", signal: AbortSignal.timeout(2000),
+  });
+  const response = await request("owner-health", {});
+  if (response.ok) {
+    const health = await response.json() as { ok?: boolean; repositoryRoot?: string; pid?: number };
+    if (!health.ok || health.repositoryRoot !== endpoint.repositoryRoot || health.pid !== endpoint.pid) throw new Error("Agent Fabric owner identity does not match its endpoint");
+  } else {
+    // Owners started before portable integration already expose this read-only action.
+    if (response.status !== 404) throw new Error("Agent Fabric owner health check failed");
+    const legacy = await request("run-status", { runId: "fabric-owner-health-probe" });
+    const value = await legacy.json() as { code?: string };
+    if (legacy.status !== 400 || value.code !== "AF_RUN_NOT_FOUND") throw new Error("Agent Fabric owner cannot be authenticated; inspect it before restarting");
+  }
+  return { repositoryRoot: endpoint.repositoryRoot, pid: endpoint.pid, port: endpoint.port };
+}
 
 /** One PGlite owner shared by CLI clients and the read/proposal MCP adapter. */
 export async function serveLocalTasks(
@@ -174,10 +197,14 @@ export async function serveLocalTasks(
     listener = createServer((request, response: ServerResponse) => {
       response.setHeader("Content-Type", "application/json; charset=utf-8");
       response.setHeader("Cache-Control", "no-store");
-      if (!published || !authorized(request, published)) {
+      if (!published || !authorized(request, published)) {
         response.writeHead(403).end(JSON.stringify({ ok: false, error: "unauthorized" }));
-        return;
-      }
+        return;
+      }
+      if (request.method === "POST" && request.url === "/v1/owner-health") {
+        response.writeHead(200).end(JSON.stringify({ ok: true, repositoryRoot: root, pid: process.pid }));
+        return;
+      }
       const action = request.url?.slice("/v1/".length) as LocalTaskAction | LocalMemoryAction | AttachedTaskAction | ManagedRunAction;
       if (request.method !== "POST" || !request.url?.startsWith("/v1/") ||
           (!isAttachedTaskAction(action) && !isManagedRunAction(action) && !["propose", "status", "evidence", "review", "run", "cancel", "reconcile", "verify", "recover-verification", "review-result", "memory-add", "memory-list", "memory-delete"].includes(action))) {
@@ -303,9 +330,10 @@ export async function requestAttachedTask(repositoryRoot: string, action: Attach
 }
 
 /** Managed runs always use the single authenticated owner, including bounded event waits. */
-export async function requestManagedRun(repositoryRoot: string, action: ManagedRunAction,
-  body: Record<string, unknown>): Promise<unknown> {
-  if (!isManagedRunAction(action)) throw new AgentFabricError("AF_INVALID_STATE", "Unknown managed run action");
+export async function requestManagedRun(repositoryRoot: string, action: ManagedRunAction,
+  body: Record<string, unknown>): Promise<unknown> {
+  if (!isManagedRunAction(action)) throw new AgentFabricError("AF_INVALID_STATE", "Unknown managed run action");
+  if (action === "run-start") body = await applyFabricProfile(repositoryRoot, body);
   const endpoint = readEndpoint(realpathSync(repositoryRoot));
   if (!endpoint) throw new AgentFabricError("AF_INVALID_STATE", "Agent Fabric local owner is not running; start forge fabric serve");
   let response: Response;

package/src/forge/agent-fabric/managed-run-store.ts

@@ -13,6 +13,16 @@ interface RecordFile { state: ManagedRunState; receipts: Receipt[] }
 export interface ManagedTransactionOptions { requestId?: string; fingerprint?: string; expectedVersion?: number }
 const MAX_RECORD = 32 * 1024 * 1024;
 const missing = (error: unknown) => (error as NodeJS.ErrnoException).code === "ENOENT";
+async function readLock(path: string): Promise<string> {
+  const deadline = Date.now() + 1000;
+  for (;;) {
+    try { return await readFile(path, "utf8"); }
+    catch (error) {
+      if (!["EPERM", "EACCES", "EBUSY"].includes((error as NodeJS.ErrnoException).code ?? "") || Date.now() >= deadline) throw error;
+      await new Promise(resolve => setTimeout(resolve, 20));
+    }
+  }
+}
 const statuses = ["preparing", "running", "paused", "blocked", "canceling", "canceled", "publishing", "completed", "failed"];
 /** Windows readers/AV may briefly hold the destination; never unlink its atomic predecessor. */
 async function replaceRecord(temp: string, destination: string): Promise<void> {
@@ -95,10 +105,10 @@ export class ManagedRunStore {
     try {
       while (true) {
         await assertAttachedSafePath(this.root, lock);
-        try { await link(candidate, lock); return async () => { await assertAttachedSafePath(this.root, lock); if (await readFile(lock, "utf8") !== ownerBytes) managedFail("AF_RUN_LOCK", "Lock ownership changed"); await unlink(lock); }; }
-        catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+        try { await link(candidate, lock); return async () => { await assertAttachedSafePath(this.root, lock); if (await readLock(lock) !== ownerBytes) managedFail("AF_RUN_LOCK", "Lock ownership changed"); await unlink(lock); }; }
+        catch (error) { if (!["EEXIST", "EPERM", "EACCES", "EBUSY"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error; }
         try {
-          assert((await lstat(lock)).isFile(), "Unsupported lock"); const raw = await readFile(lock, "utf8"), previous = JSON.parse(raw);
+          assert((await lstat(lock)).isFile(), "Unsupported lock"); const raw = await readLock(lock), previous = JSON.parse(raw);
           if (Number.isSafeInteger(previous.pid) && previous.pid > 0 && !alive(previous.pid)) {
             await assertAttachedSafePath(this.root, claim); reclaimDeadGuard(claim); let claimed = false;
             try { await link(candidate, claim); claimed = true; if (readFileSync(lock, "utf8") === raw) unlinkSync(lock); }

package/src/forge/agent-fabric/project-profile.ts

@@ -0,0 +1,50 @@
+import { lstat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { localFabricPath } from "./local-paths.ts";
+import type { ManagedRunSpec } from "./managed-run-contract.ts";
+
+export interface FabricProjectProfile {
+  schemaVersion: 1;
+  maxConcurrency?: number;
+  environment?: ManagedRunSpec["environment"];
+  verificationCommands?: string[][];
+}
+
+/** An optional declarative profile; reading it never executes project commands. */
+export async function readFabricProfile(root: string): Promise<FabricProjectProfile | null> {
+  localFabricPath(root);
+  const path = join(root, ".forge", "fabric.json");
+  let stat;
+  try { stat = await lstat(path); } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw error; }
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 16 * 1024) throw new Error("Invalid Agent Fabric project profile file");
+  const value = JSON.parse(await readFile(path, "utf8")) as FabricProjectProfile;
+  if (!value || typeof value !== "object" || Array.isArray(value) || value.schemaVersion !== 1 || Object.keys(value).some(key => !["schemaVersion", "maxConcurrency", "environment", "verificationCommands"].includes(key))) throw new Error("Invalid Agent Fabric project profile");
+  if (value.maxConcurrency !== undefined && (!Number.isSafeInteger(value.maxConcurrency) || value.maxConcurrency < 1 || value.maxConcurrency > 4)) throw new Error("Profile maxConcurrency must be between 1 and 4");
+  const env = value.environment;
+  if (env !== undefined) {
+    if (!env || typeof env !== "object" || Array.isArray(env) || Object.keys(env).some(key => !["mode", "ignoreScripts", "registry", "timeoutMs"].includes(key))) throw new Error("Invalid profile environment");
+    if (env.mode !== undefined && !["auto", "none"].includes(env.mode)) throw new Error("Invalid profile environment mode");
+    if (env.ignoreScripts !== undefined && typeof env.ignoreScripts !== "boolean") throw new Error("Invalid profile ignoreScripts");
+    if (env.timeoutMs !== undefined && (!Number.isSafeInteger(env.timeoutMs) || env.timeoutMs < 100 || env.timeoutMs > 1800000)) throw new Error("Invalid profile environment deadline");
+    if (env.registry !== undefined) {
+      if (typeof env.registry !== "string") throw new Error("Invalid profile registry");
+      const url = new URL(env.registry);
+      if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) throw new Error("Profile registry requires HTTPS without embedded credentials");
+    }
+  }
+  if (value.verificationCommands !== undefined && (!Array.isArray(value.verificationCommands) || value.verificationCommands.length > 20 || value.verificationCommands.some(argv => !Array.isArray(argv) || !argv.length || argv.length > 40 || argv.some(arg => typeof arg !== "string" || !arg || arg.length > 4096 || arg.includes("\0"))))) throw new Error("Invalid profile verification commands");
+  return value;
+}
+
+/** Explicit per-run values win. Suggested checks are never silently appended to a DAG. */
+export async function applyFabricProfile(root: string, spec: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const profile = await readFabricProfile(root);
+  if (!profile) return spec;
+  const result = structuredClone(spec);
+  if (profile.environment && (result.environment === undefined || (result.environment && typeof result.environment === "object" && !Array.isArray(result.environment)))) result.environment = { ...profile.environment, ...(result.environment as object ?? {}) };
+  if (profile.maxConcurrency && result.workflow && typeof result.workflow === "object" && !Array.isArray(result.workflow)) {
+    const workflow = result.workflow as Record<string, unknown>;
+    if (workflow.limits === undefined || (workflow.limits && typeof workflow.limits === "object" && !Array.isArray(workflow.limits))) workflow.limits = { maxConcurrency: profile.maxConcurrency, ...(workflow.limits as object ?? {}) };
+  }
+  return result;
+}

package/src/forge/agent-fabric/project-registry.ts

@@ -0,0 +1,120 @@
+import { createHash, randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+
+const execute = promisify(execFile);
+export interface FabricProject { id: string; root: string }
+export interface FabricRegistryOptions { registryDirectory?: string; id?: string }
+const validId = (id: string) => /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(id);
+const identity = (root: string) => process.platform === "win32" ? root.toLowerCase() : root;
+const absent = (error: unknown) => (error as NodeJS.ErrnoException).code === "ENOENT";
+const busy = (error: unknown) => ["EEXIST", "EPERM", "EACCES"].includes((error as NodeJS.ErrnoException).code ?? "");
+
+/** Recover only a validated startup lock whose process demonstrably no longer exists. */
+export async function recoverFabricLock(path: string): Promise<boolean> {
+  const recovery = `${path}.recovery`;
+  await checkPath(recovery);
+  try { await writeFile(recovery, JSON.stringify({ pid: process.pid }), { flag: "wx", mode: 0o600 }); }
+  catch (error) { if (busy(error)) return false; throw error; }
+  try {
+    let contents: string;
+    try {
+      const stat = await lstat(path);
+      if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024) throw new Error("Invalid Agent Fabric startup lock");
+      contents = await readFile(path, "utf8");
+    } catch (error) { if (absent(error)) return true; if (busy(error)) return false; throw error; }
+    if (!contents) return false; // Another process may still be completing exclusive creation.
+    let pid: unknown;
+    try { pid = (JSON.parse(contents) as { pid?: unknown })?.pid; } catch { throw new Error("Invalid Agent Fabric startup lock"); }
+    if (!Number.isSafeInteger(pid) || (pid as number) <= 0) throw new Error("Invalid Agent Fabric startup lock pid");
+    try { process.kill(pid as number, 0); return false; }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") return false; }
+    // Locks are only replaced after removal. Compare bytes before deleting our observed lock.
+    try { if (await readFile(path, "utf8") !== contents) return false; await unlink(path); return true; }
+    catch (error) { if (absent(error)) return true; throw error; }
+  } finally { await unlink(recovery); }
+}
+
+/** Git is the project authority, including when invoked from a monorepo subdirectory. */
+export async function resolveFabricRoot(directory: string): Promise<string> {
+  const cwd = await realpath(resolve(directory));
+  const { stdout } = await execute("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", windowsHide: true, timeout: 10_000, maxBuffer: 16_384 });
+  const root = await realpath(stdout.trim());
+  await execute("git", ["rev-parse", "--verify", "HEAD"], { cwd: root, windowsHide: true, timeout: 10_000, maxBuffer: 16_384 });
+  return root;
+}
+
+export function fabricRegistryDirectory(options: FabricRegistryOptions = {}): string {
+  return resolve(options.registryDirectory ?? join(homedir(), ".forge", "agent-fabric"));
+}
+
+async function checkPath(path: string): Promise<void> {
+  const parent = dirname(path);
+  if (parent !== path) await checkPath(parent);
+  const stat = await lstat(path).catch(error => { if (absent(error)) return undefined; throw error; });
+  if (stat?.isSymbolicLink()) throw new Error("Agent Fabric registry cannot traverse symbolic links");
+}
+
+async function readRegistry(directory: string): Promise<FabricProject[]> {
+  const path = join(directory, "projects.json");
+  await checkPath(path);
+  let data: Buffer;
+  try { const stat = await lstat(path); if (!stat.isFile() || stat.size > 256 * 1024) throw new Error("Invalid Agent Fabric registry file"); data = await readFile(path); }
+  catch (error) { if (absent(error)) return []; throw error; }
+  const value = JSON.parse(data.toString("utf8")) as { schemaVersion?: unknown; projects?: unknown };
+  if (!value || value.schemaVersion !== 1 || !Array.isArray(value.projects) || value.projects.length > 1000) throw new Error("Invalid Agent Fabric project registry");
+  const entries = value.projects as FabricProject[];
+  const ids = new Set<string>(), roots = new Set<string>();
+  for (const entry of entries) {
+    if (!entry || Object.keys(entry).sort().join(",") !== "id,root" || typeof entry.id !== "string" || !validId(entry.id) || typeof entry.root !== "string" || !isAbsolute(entry.root) || ids.has(entry.id) || roots.has(identity(entry.root))) throw new Error("Invalid or duplicate Agent Fabric project registration");
+    ids.add(entry.id); roots.add(identity(entry.root));
+  }
+  return entries;
+}
+
+export async function listFabricProjects(options: FabricRegistryOptions = {}): Promise<FabricProject[]> {
+  return readRegistry(fabricRegistryDirectory(options));
+}
+
+export async function registerFabricProject(directory: string, options: FabricRegistryOptions = {}): Promise<FabricProject> {
+  const root = await resolveFabricRoot(directory);
+  const registry = fabricRegistryDirectory(options);
+  const id = options.id ?? `${basename(root).replace(/[^a-zA-Z0-9._-]/g, "-").replace(/^[^a-zA-Z0-9]+/, "").slice(0, 48) || "project"}-${createHash("sha256").update(identity(root)).digest("hex").slice(0, 12)}`;
+  if (!validId(id)) throw new Error("Invalid Agent Fabric project id");
+  await checkPath(registry); await mkdir(registry, { recursive: true, mode: 0o700 });
+  const lock = join(registry, "projects.lock");
+  const deadline = Date.now() + 5000;
+  for (;;) {
+    await checkPath(lock);
+    try { await writeFile(lock, JSON.stringify({ pid: process.pid }), { flag: "wx", mode: 0o600 }); break; }
+    catch (error) { if (!busy(error)) throw error; if (Date.now() >= deadline) throw new Error("Agent Fabric project registry is busy; retry or inspect projects.lock and projects.lock.recovery after their owners exit"); if (await recoverFabricLock(lock)) continue; await new Promise(resolve => setTimeout(resolve, 30)); }
+  }
+  const stage = join(registry, `projects-${randomUUID()}.tmp`);
+  try {
+    const entries = await readRegistry(registry);
+    const sameRoot = entries.find(entry => identity(entry.root) === identity(root));
+    if (sameRoot) { if (options.id && sameRoot.id !== options.id) throw new Error("Project already registered with another id"); return sameRoot; }
+    if (entries.some(entry => entry.id === id)) throw new Error("Project id already belongs to another repository");
+    if (entries.length >= 1000) throw new Error("Agent Fabric project registry is full");
+    const project = { id, root }; entries.push(project); entries.sort((a, b) => a.id.localeCompare(b.id));
+    await writeFile(stage, `${JSON.stringify({ schemaVersion: 1, projects: entries }, null, 2)}\n`, { flag: "wx", mode: 0o600 });
+    await rename(stage, join(registry, "projects.json"));
+    return project;
+  } finally {
+    try { await unlink(stage).catch(error => { if (!absent(error)) throw error; }); }
+    finally { if (await readFile(lock, "utf8") === JSON.stringify({ pid: process.pid })) await unlink(lock); }
+  }
+}
+
+/** Recheck the registration so moved paths or replaced symlinks cannot redirect a run. */
+export async function resolveFabricProject(id: string, options: FabricRegistryOptions = {}): Promise<string> {
+  if (!validId(id)) throw new Error("Invalid Agent Fabric project id");
+  const project = (await listFabricProjects(options)).find(entry => entry.id === id);
+  if (!project) throw new Error("Agent Fabric project is not registered");
+  const root = await resolveFabricRoot(project.root);
+  if (identity(root) !== identity(project.root)) throw new Error("Agent Fabric registered repository root changed; register its new location explicitly");
+  return root;
+}

package/src/forge/agent-fabric/project-runtime.ts

@@ -0,0 +1,85 @@
+import { spawn, execFile } from "node:child_process";
+import { lstat, mkdir, open, readFile, unlink, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { localFabricPath } from "./local-paths.ts";
+import { probeLocalOwner } from "./local-task-server.ts";
+import { recoverFabricLock, resolveFabricRoot } from "./project-registry.ts";
+import { readFabricProfile } from "./project-profile.ts";
+
+const execute = promisify(execFile);
+const cliPath = fileURLToPath(new URL("../../../bin/forge.mjs", import.meta.url));
+export interface FabricOwnerOptions { cliPath?: string; nodeExecutable?: string; startupTimeoutMs?: number }
+const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
+
+export async function fabricProjectDoctor(directory: string) {
+  const root = await resolveFabricRoot(directory);
+  const profile = await readFabricProfile(root);
+  const owner = await probeLocalOwner(root).then(value => ({ running: value !== null, ...(value ?? {}) })).catch(error => ({ running: false, error: error instanceof Error ? error.message : "Owner probe failed" }));
+  const sdkAvailable = await import("@openai/codex-sdk").then(module => typeof module.Codex === "function").catch(() => false);
+  const auth = await execute("codex", ["login", "status"], { windowsHide: true, timeout: 5000, maxBuffer: 8192 }).then(() => "authenticated" as const).catch(() => "not_verified" as const);
+  return { ok: sdkAvailable && !("error" in owner), repositoryRoot: root,
+    runtime: { cliPath, nodeExecutable: process.execPath, sdkAvailable }, owner, profile,
+    codexAuthentication: auth, managedExecution: true, hooksRequired: false,
+    nextActions: [...(!sdkAvailable ? ["Install the selected Forge runtime's dependencies"] : []), ...(!owner.running ? ["forge fabric ensure-owner --json"] : []), ...(auth !== "authenticated" ? ["codex login status"] : [])] };
+}
+
+/** Start only an owner, never a worker, and reuse an authenticated owner for this exact root. */
+export async function ensureFabricOwner(directory: string, options: FabricOwnerOptions = {}): Promise<{ repositoryRoot: string; pid: number; port: number; started: boolean }> {
+  const root = await resolveFabricRoot(directory);
+  const existing = await probeLocalOwner(root);
+  if (existing) return { ...existing, started: false };
+  const state = localFabricPath(root);
+  await mkdir(state, { recursive: true, mode: 0o700 });
+  const lock = localFabricPath(root, "owner-start.lock");
+  const deadline = Date.now() + (options.startupTimeoutMs ?? 30_000);
+  for (;;) {
+    try { await writeFile(lock, JSON.stringify({ pid: process.pid }), { flag: "wx", mode: 0o600 }); break; }
+    catch (error) {
+      if (!["EEXIST", "EPERM", "EACCES"].includes((error as NodeJS.ErrnoException).code ?? "")) throw error;
+      const peer = await probeLocalOwner(root); if (peer) return { ...peer, started: false };
+      // Never recover a live or unverified process's lock solely on a timer.
+      if (Date.now() >= deadline) throw new Error("Agent Fabric owner startup is busy; inspect owner-start.lock and owner-start.lock.recovery after their processes exit");
+      if (await recoverFabricLock(lock)) continue;
+      await delay(100);
+    }
+  }
+  try {
+    const peer = await probeLocalOwner(root); if (peer) return { ...peer, started: false };
+    const logPath = localFabricPath(root, "owner.log");
+    const stat = await lstat(logPath).catch(error => { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; });
+    if (stat && !stat.isFile()) throw new Error("Agent Fabric owner log is not a regular file");
+    let node = options.nodeExecutable ?? process.execPath;
+    if (!options.nodeExecutable && process.versions.bun) node = (await execute("node", ["-p", "process.execPath"], { windowsHide: true, timeout: 5000 })).stdout.trim();
+    const log = await open(logPath, "a", 0o600);
+    let child: ReturnType<typeof spawn>;
+    let failure: string | undefined;
+    try {
+      child = spawn(node, [options.cliPath ?? cliPath, "fabric", "serve", "--json"], {
+        cwd: root, detached: true, windowsHide: true, stdio: ["ignore", log.fd, log.fd],
+      });
+      child.once("error", error => { failure = error.message; });
+      child.once("exit", (code, signal) => { failure = `owner exited (${code ?? signal})`; });
+    } finally { await log.close(); }
+    child.unref();
+    try {
+      while (Date.now() < deadline) {
+        const owner = await probeLocalOwner(root);
+        if (owner) {
+          if (owner.pid !== child.pid) child.kill();
+          return { ...owner, started: owner.pid === child.pid };
+        }
+        if (failure) throw new Error(`Agent Fabric ${failure}; inspect ${logPath}`);
+        await delay(100);
+      }
+      throw new Error(`Agent Fabric owner startup timed out; inspect ${logPath}`);
+    } catch (error) {
+      // Only this exact spawned child is ours to stop if startup did not complete.
+      child.kill();
+      throw error;
+    }
+  } finally {
+    const contents = await readFile(lock, "utf8");
+    if (contents === JSON.stringify({ pid: process.pid })) await unlink(lock);
+  }
+}

package/src/forge/agent-memory/mcp.ts

@@ -7,7 +7,8 @@ import { ingestEnvelope, runAgentMemoryCommand } from "./bridge.ts";
 import { normalizeAgentEvent } from "./normalize.ts";
 import { MANAGED_RUN_ACTIONS, requestManagedRun, ATTACHED_TASK_ACTIONS, isAttachedTaskRead, requestAttachedTask, requestLocalTask } from "../agent-fabric/local-task-server.ts";
 import { LocalChangeReviewService } from "../agent-fabric/local-change-review-service.ts";
-import { CODEX_EVENTS, CODEX_HOOK_RUNNER_RELATIVE, CODEX_MCP_HOOK_TOOL } from "./sources/codex.ts";
+import { CODEX_EVENTS, CODEX_HOOK_RUNNER_RELATIVE, CODEX_MCP_HOOK_TOOL } from "./sources/codex.ts";
+import { listFabricProjects, registerFabricProject, resolveFabricProject } from "../agent-fabric/project-registry.ts";
 
 
 const managedCommon = { runId: { type: "string" }, requestId: { type: "string" }, expectedVersion: { type: "integer", minimum: 1 } };
@@ -54,14 +55,21 @@ function managedRunSchema(action: typeof MANAGED_RUN_ACTIONS[number]): Record<st
     required: ["request"], additionalProperties: false };
 }
 
-interface JsonRpcRequest {
+interface JsonRpcRequest {
   jsonrpc?: "2.0";
   id?: string | number | null;
   method: string;
   params?: Record<string, unknown>;
-}
-
-export async function handleMcpRequest(workspaceRoot: string, request: JsonRpcRequest): Promise<Record<string, unknown> | null> {
+}
+
+export interface FabricMcpOptions { registryDirectory?: string }
+
+function projectAwareSchema(schema: Record<string, unknown>): Record<string, unknown> {
+  return { ...schema, properties: { ...(schema.properties as Record<string, unknown>),
+    projectId: { type: "string", minLength: 1, description: "Registered project identifier. Omit to use the MCP server's original workspace." } } };
+}
+
+export async function handleMcpRequest(workspaceRoot: string, request: JsonRpcRequest, options: FabricMcpOptions = {}): Promise<Record<string, unknown> | null> {
   if (request.method.startsWith("notifications/")) {
     return null;
   }
@@ -75,7 +83,15 @@ export async function handleMcpRequest(workspaceRoot: string, request: JsonRpcRe
     }
     if (request.method === "tools/list") {
       return response(request.id, {
-        tools: [
+        tools: [
+          { name: "fabric_project_register", description: "Explicitly register a Git project root for isolated Agent Fabric routing. Does not start workers.",
+            inputSchema: { type: "object", properties: { root: { type: "string", minLength: 1, description: "Absolute path to the Git project or one of its subdirectories." }, id: { type: "string", minLength: 1 } }, required: ["root"], additionalProperties: false } },
+          { name: "fabric_project_list", description: "List registered Agent Fabric projects and their canonical roots.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+          { name: "fabric_project_doctor", description: "Diagnose the selected project's runtime and owner without starting workers.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+          { name: "fabric_owner_start", description: "Ensure the selected project's isolated owner is running. Does not start a workflow or model.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false } },
           ...MANAGED_RUN_ACTIONS.map((action) => ({
             name: `fabric_${action.replaceAll("-", "_")}`,
             description: action === "run-start"
@@ -190,7 +206,8 @@ export async function handleMcpRequest(workspaceRoot: string, request: JsonRpcRe
               additionalProperties: false,
             },
           },
-        ],
+        ].map((tool) => tool.name.startsWith("fabric_") && tool.name !== "fabric_project_register" && tool.name !== "fabric_project_list"
+          ? { ...tool, inputSchema: projectAwareSchema(tool.inputSchema) } : tool),
       });
     }
     if (request.method === "tools/call") {
@@ -199,9 +216,18 @@ export async function handleMcpRequest(workspaceRoot: string, request: JsonRpcRe
       const args = params.arguments && typeof params.arguments === "object" && !Array.isArray(params.arguments)
         ? params.arguments as Record<string, unknown>
         : {};
-      const result = await runTool(workspaceRoot, name, args);
-      if (name !== CODEX_MCP_HOOK_TOOL) {
-        await logMcpToolCall(workspaceRoot, name, args, "completed").catch(() => undefined);
+      let toolRoot = workspaceRoot;
+      const toolArgs = { ...args };
+      if (name.startsWith("fabric_") && name !== "fabric_project_register" && name !== "fabric_project_list" && "projectId" in toolArgs) {
+        if (typeof toolArgs.projectId !== "string" || !toolArgs.projectId.trim()) throw new Error("projectId must be a non-empty registered project identifier");
+        toolRoot = await resolveFabricProject(toolArgs.projectId, options);
+        delete toolArgs.projectId;
+      }
+      const toolResult = await runTool(toolRoot, name, toolArgs, options);
+      const result = typeof args.projectId === "string" && name.startsWith("fabric_") && toolResult && typeof toolResult === "object"
+        ? { ...toolResult, projectContext: { id: args.projectId, root: toolRoot } } : toolResult;
+      if (name !== CODEX_MCP_HOOK_TOOL) {
+        await logMcpToolCall(toolRoot, name, args, "completed").catch(() => undefined);
       }
       return response(request.id, {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -242,7 +268,25 @@ export async function runMcpServe(workspaceRoot: string): Promise<number> {
   return 0;
 }
 
-async function runTool(workspaceRoot: string, name: string, args: Record<string, unknown>): Promise<unknown> {
+async function runTool(workspaceRoot: string, name: string, args: Record<string, unknown>, options: FabricMcpOptions): Promise<unknown> {
+  if (name === "fabric_project_register") {
+    if (Object.keys(args).some(key => key !== "root" && key !== "id") || typeof args.root !== "string" || !isAbsolute(args.root) ||
+        ("id" in args && (typeof args.id !== "string" || !args.id.trim()))) throw new Error("fabric_project_register requires an absolute root and optional id");
+    return { ok: true, project: await registerFabricProject(args.root, { ...options, ...(typeof args.id === "string" ? { id: args.id } : {}) }) };
+  }
+  if (name === "fabric_project_list") {
+    if (Object.keys(args).length) throw new Error("fabric_project_list accepts no arguments");
+    return { ok: true, projects: await listFabricProjects(options) };
+  }
+  if (name === "fabric_project_doctor" || name === "fabric_owner_start") {
+    if (Object.keys(args).length) throw new Error(`${name} accepts only optional projectId`);
+    const { ensureFabricOwner, fabricProjectDoctor } = await import("../agent-fabric/project-runtime.ts");
+    if (name === "fabric_project_doctor") {
+      const diagnostics = await fabricProjectDoctor(workspaceRoot);
+      return { ok: diagnostics.ok, diagnostics };
+    }
+    return { ok: true, owner: await ensureFabricOwner(workspaceRoot) };
+  }
   const managedAction = MANAGED_RUN_ACTIONS.find((action) => name === `fabric_${action.replaceAll("-", "_")}`);
   if (managedAction) {
     const read = managedAction === "run-status";
@@ -310,7 +354,9 @@ async function runTool(workspaceRoot: string, name: string, args: Record<string,
       schemaVersion: 1,
       protocolKernel: "p0a_available",
       boundedModelAdapter: "p0b_a_available",
-      codingTaskControl: "local_owner_service_required",
+      codingTaskControl: "local_owner_service_required",
+      projectRouting: { supported: true, registrationRequired: true, defaultWorkspace: realpathSync(workspaceRoot),
+        ownerIsolation: "per_project", hooks: "server_workspace_only", tools: ["fabric_project_register", "fabric_project_list", "fabric_project_doctor", "fabric_owner_start"] },
       managedExecution: { supported: true, runningOwnerRequired: true, scheduler: "owner_managed",
         executors: ["codex", "command"], startDispatchesWork: true, boundedEventWaitMs: 30_000,
         codexMayConsumeCredits: true, controls: ["steer", "pause", "resume", "cancel", "reconcile"],