forgeos 0.1.0-alpha.68 → 0.1.0-alpha.69

package/src/forge/agent-fabric/managed-workspace.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { chmod, lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { tmpdir } from "node:os";
 import { stableStringify } from "./canonical.ts";
@@ -10,12 +10,15 @@ import { verifyManagedEnvironment, type ManagedEnvironment } from "./managed-env
 export interface ManagedBase { root: string; runId: string; head: string; scope: string[]; digest: string; baselineDirectory: string; contextScope?: string[]; contextDigest?: string }
 export interface ManagedFile { path: string; beforeDigest: string | null; contentBase64: string | null; mode?: number }
 export interface ManagedArtifact { digest: string; files: ManagedFile[] }
-interface Entry { path: string; digest: string; mode: number; contentBase64: string }
+interface Entry { path: string; digest: string; mode: number; contentBase64?: string; readonlySize?: number }
 interface Inventory { files: Entry[]; digest: string }
 interface WorkspaceMetadata { baseDigest: string; runId: string; attemptId: string; directory: string; input: Inventory }
 const runFile = promisify(execFile);
 // Baselines include generated Forge graphs (~10MiB); output artifacts retain the smaller bound.
 const MAX_FILES = 20_000, MAX_BYTES = 128 * 1024 * 1024, MAX_SNAPSHOT_FILE_BYTES = 16 * 1024 * 1024, MAX_ARTIFACT_FILE_BYTES = 8 * 1024 * 1024;
+// Large assets outside the editable/context scope stay in Git clones. Only their
+// streaming fingerprints enter inventories; editable snapshots retain their limits.
+const MAX_READONLY_ASSET_BYTES = 512 * 1024 * 1024, MAX_READONLY_BYTES = 1024 * 1024 * 1024;
 const hash = (data: string | Uint8Array) => `sha256:${createHash("sha256").update(data).digest("hex")}`;
 function assert(value: unknown, message: string): asserts value { if (!value) throw new Error(`managed workspace: ${message}`); }
 function pathName(value: string): string {
@@ -34,7 +37,7 @@ async function safePath(root: string, path: string): Promise<string> {
   return absolute;
 }
 async function git(root: string, args: string[]) { return (await runFile("git", ["-C", root, ...args], { windowsHide: true, maxBuffer: 16 * 1024 * 1024 })).stdout.trim(); }
-const contextNames = ["package.json", "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", "yarn.lock", ".yarnrc.yml", "bun.lock", "bun.lockb", "bunfig.toml"];
+const contextNames = ["package.json", "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", "yarn.lock", ".yarnrc.yml", "bun.lock", "bun.lockb", "bunfig.toml", "forge.manifest.json"];
 async function readonlyContextPaths(root: string, scope: string[]): Promise<string[]> {
   const tracked = (await git(root, ["ls-files", "-z"])).split("\0").filter(Boolean);
   const result = new Set(tracked.filter(path => contextNames.includes(path.split("/").at(-1)!) && !withinScope(path, scope)));
@@ -44,8 +47,28 @@ async function readonlyContextPaths(root: string, scope: string[]): Promise<stri
 async function currentContextMatches(base: ManagedBase): Promise<boolean> {
   return base.contextScope === undefined || (await inventory(base.root, base.contextScope)).digest === base.contextDigest;
 }
-async function inventory(root: string, scope?: string[], excluded: string[] = []): Promise<Inventory> {
-  const files: Entry[] = []; let bytes = 0;
+function inventoryDigest(files: Entry[]): string {
+  return hash(JSON.stringify(files.map(({ path, digest, mode, readonlySize }) => ({ path, digest, mode, ...(readonlySize === undefined ? {} : { readonlySize }) }))));
+}
+function entryContent(file: Entry): string { assert(typeof file.contentBase64 === "string" && file.readonlySize === undefined, "read-only asset cannot be materialized or published"); return file.contentBase64; }
+async function readonlyAssetDigest(absolute: string, size: number): Promise<string> {
+  const handle = await open(absolute, "r");
+  try {
+    const before = await handle.stat();
+    assert(before.isFile() && before.size === size, "asset changed before hashing");
+    const digest = createHash("sha256"); let bytes = 0;
+    for await (const chunk of handle.createReadStream({ autoClose: false, highWaterMark: 256 * 1024 })) {
+      bytes += chunk.length; assert(bytes <= size && bytes <= MAX_READONLY_ASSET_BYTES, "asset changed or size bound exceeded"); digest.update(chunk);
+    }
+    const after = await handle.stat(), current = await lstat(absolute);
+    assert(bytes === size && after.size === before.size && after.mtimeMs === before.mtimeMs && after.ctimeMs === before.ctimeMs
+      && current.isFile() && !current.isSymbolicLink() && current.ino === before.ino && current.size === before.size
+      && current.mtimeMs === before.mtimeMs && current.ctimeMs === before.ctimeMs, "asset changed during hashing");
+    return `sha256:${digest.digest("hex")}`;
+  } finally { await handle.close(); }
+}
+async function inventory(root: string, scope?: string[], excluded: string[] = [], boundedScope: string[] = []): Promise<Inventory> {
+  const files: Entry[] = []; let bytes = 0, readonlyBytes = 0;
   const visit = async (directory: string, prefix: string) => {
     for (const name of (await readdir(directory)).sort()) {
       if (!prefix && name.toLowerCase() === ".git") continue;
@@ -56,7 +79,14 @@ async function inventory(root: string, scope?: string[], excluded: string[] = []
       assert(!stat.isSymbolicLink(), "symlink rejected");
       if (stat.isDirectory()) await visit(absolute, path);
       else {
-        assert(stat.isFile(), "special file rejected"); assert(stat.size <= MAX_SNAPSHOT_FILE_BYTES, "file size bound exceeded");
+        assert(stat.isFile(), "special file rejected"); assert(files.length < MAX_FILES, "snapshot bound exceeded");
+        if (stat.size > MAX_SNAPSHOT_FILE_BYTES && !scope && !withinScope(path, boundedScope)) {
+          readonlyBytes += stat.size;
+          assert(stat.size <= MAX_READONLY_ASSET_BYTES && readonlyBytes <= MAX_READONLY_BYTES, "read-only asset size bound exceeded");
+          files.push({ path, digest: await readonlyAssetDigest(absolute, stat.size), mode: stat.mode & 0o111 ? 0o755 : 0o644, readonlySize: stat.size });
+          continue;
+        }
+        assert(stat.size <= MAX_SNAPSHOT_FILE_BYTES, "file size bound exceeded");
         const content = await readFile(absolute); bytes += content.length;
         assert(bytes <= MAX_BYTES && files.length < MAX_FILES, "snapshot bound exceeded");
         files.push({ path, digest: hash(content), mode: stat.mode & 0o111 ? 0o755 : 0o644, contentBase64: content.toString("base64") });
@@ -65,11 +95,15 @@ async function inventory(root: string, scope?: string[], excluded: string[] = []
   };
   await visit(resolve(root), ""); files.sort((a, b) => a.path.localeCompare(b.path));
   assert(new Set(files.map(file => file.path.toLowerCase())).size === files.length, "case-colliding paths rejected");
-  return { files, digest: hash(JSON.stringify(files.map(({ path, digest, mode }) => ({ path, digest, mode })))) };
+  return { files, digest: inventoryDigest(files) };
+}
+function workspaceInventory(base: ManagedBase, directory: string, excluded: string[] = []): Promise<Inventory> {
+  return inventory(directory, undefined, excluded, [...base.scope, ...(base.contextScope ?? [])]);
 }
-async function setFile(root: string, file: { path: string; contentBase64: string | null; mode?: number }) {
+async function setFile(root: string, file: { path: string; contentBase64?: string | null; mode?: number }) {
   const absolute = await safePath(root, file.path);
   if (file.contentBase64 === null) { try { const stat = await lstat(absolute); assert(stat.isFile(), "delete target is not a regular file"); await rm(absolute); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } return; }
+  assert(typeof file.contentBase64 === "string", "read-only asset cannot be materialized or published");
   await mkdir(dirname(absolute), { recursive: true }); await writeFile(absolute, Buffer.from(file.contentBase64, "base64")); await chmod(absolute, file.mode ?? 0o644);
 }
 async function clone(root: string, prefix: string): Promise<string> {
@@ -96,6 +130,7 @@ function applyEntries(input: Entry[], artifacts: ManagedArtifact[], scope: strin
   const map = new Map(input.map(file => [file.path, { ...file }]));
   for (const artifact of artifacts) { validateArtifact(artifact, scope); for (const file of artifact.files) {
     const before = map.get(file.path); assert((before?.digest ?? null) === file.beforeDigest, `conflicting beforeimage: ${file.path}`);
+    assert(before?.readonlySize === undefined, "read-only asset cannot be changed by artifacts");
     if (file.contentBase64 === null) { assert(before, "deletion of missing file"); map.delete(file.path); }
     else map.set(file.path, { path: file.path, digest: hash(Buffer.from(file.contentBase64, "base64")), mode: file.mode ?? before?.mode ?? 0o644, contentBase64: file.contentBase64 });
   } }
@@ -110,7 +145,7 @@ async function validateBase(base: ManagedBase) {
   assert(stableStringify(marker) === stableStringify(base), "base identity mismatch");
   if (base.contextScope !== undefined) { assert(Array.isArray(base.contextScope) && base.contextScope.length <= 1000 && /^sha256:[a-f0-9]{64}$/.test(base.contextDigest ?? ""), "invalid context metadata"); for (const path of base.contextScope) pathName(path); }
   const baselineDigest = await readFile(join(base.baselineDirectory, ".git", "forge-managed-baseline-digest"), "utf8");
-  assert((await inventory(base.baselineDirectory)).digest === baselineDigest && (await inventory(base.baselineDirectory, base.scope)).digest === base.digest, "immutable baseline modified");
+  assert((await workspaceInventory(base, base.baselineDirectory)).digest === baselineDigest && (await inventory(base.baselineDirectory, base.scope)).digest === base.digest, "immutable baseline modified");
 }
 export async function captureManagedBase(root: string, runId: string, scope: string[]): Promise<ManagedBase> {
   root = resolve(root); assert(typeof runId === "string" && runId.trim().length > 0, "runId required"); scope = scopes(scope);
@@ -124,17 +159,17 @@ export async function captureManagedBase(root: string, runId: string, scope: str
   assert((await inventory(root, scope)).digest === snapshot.digest && (await inventory(root, contextScope)).digest === context.digest && await git(root, ["rev-parse", "HEAD"]) === head, "source changed during capture");
   const base: ManagedBase = { root, runId, head, scope, digest: snapshot.digest, baselineDirectory, ...(contextScope.length ? { contextScope, contextDigest: context.digest } : {}) };
   await writeFile(join(baselineDirectory, ".git", "forge-managed-base.json"), JSON.stringify(base));
-  await writeFile(join(baselineDirectory, ".git", "forge-managed-baseline-digest"), (await inventory(baselineDirectory)).digest); return base;
+  await writeFile(join(baselineDirectory, ".git", "forge-managed-baseline-digest"), (await workspaceInventory(base, baselineDirectory)).digest); return base;
 }
 export async function prepareManagedWorkspace(base: ManagedBase, attemptId: string, dependencies: ManagedArtifact[]): Promise<{ directory: string; inputDigest: string }> {
   await validateBase(base); assert(typeof attemptId === "string" && attemptId.trim().length > 0, "attemptId required");
-  const baseline = await inventory(base.baselineDirectory), desired = applyEntries(baseline.files, dependencies, base.scope), directory = await clone(base.baselineDirectory, "forge-managed-attempt-");
+  const baseline = await workspaceInventory(base, base.baselineDirectory), desired = applyEntries(baseline.files, dependencies, base.scope), directory = await clone(base.baselineDirectory, "forge-managed-attempt-");
   await git(directory, ["checkout", "--quiet", "--detach", base.head]);
-  const initial = await inventory(directory);
+  const initial = await workspaceInventory(base, directory);
   const desiredByPath = new Map(desired.map(file => [file.path, file])), initialByPath = new Map(initial.files.map(file => [file.path, file]));
   for (const file of initial.files) if (!desiredByPath.has(file.path)) await setFile(directory, { path: file.path, contentBase64: null });
   for (const file of desired) if (initialByPath.get(file.path)?.digest !== file.digest || initialByPath.get(file.path)?.mode !== file.mode) await setFile(directory, file);
-  const input = await inventory(directory), metadata: WorkspaceMetadata = { baseDigest: base.digest, runId: base.runId, attemptId, directory, input };
+  const input = await workspaceInventory(base, directory), metadata: WorkspaceMetadata = { baseDigest: base.digest, runId: base.runId, attemptId, directory, input };
   await writeFile(join(directory, ".git", "forge-managed-input.json"), JSON.stringify(metadata)); return { directory, inputDigest: input.digest };
 }
 export async function captureManagedArtifact(base: ManagedBase, workspaceDirectory: string, writeScope: string[], expectedInputDigest: string, environment?: ManagedEnvironment): Promise<ManagedArtifact> {
@@ -142,14 +177,17 @@ export async function captureManagedArtifact(base: ManagedBase, workspaceDirecto
   workspaceDirectory = resolve(workspaceDirectory);
   const metadata = JSON.parse(await readFile(join(workspaceDirectory, ".git", "forge-managed-input.json"), "utf8")) as WorkspaceMetadata;
   assert(metadata.directory === workspaceDirectory && metadata.baseDigest === base.digest && metadata.runId === base.runId, "workspace identity mismatch");
-  assert(/^sha256:[a-f0-9]{64}$/.test(expectedInputDigest) && metadata.input.digest === expectedInputDigest && metadata.input.digest === hash(JSON.stringify(metadata.input.files.map(({ path, digest, mode }) => ({ path, digest, mode })))) && metadata.input.files.every(file => hash(Buffer.from(file.contentBase64, "base64")) === file.digest), "input inventory corrupted or coordinator digest mismatch");
+  assert(/^sha256:[a-f0-9]{64}$/.test(expectedInputDigest) && metadata.input.digest === expectedInputDigest && metadata.input.digest === inventoryDigest(metadata.input.files)
+    && metadata.input.files.every(file => file.readonlySize === undefined ? typeof file.contentBase64 === "string" && hash(Buffer.from(file.contentBase64, "base64")) === file.digest
+      : file.contentBase64 === undefined && Number.isSafeInteger(file.readonlySize) && file.readonlySize > MAX_SNAPSHOT_FILE_BYTES && file.readonlySize <= MAX_READONLY_ASSET_BYTES
+        && !withinScope(file.path, [...base.scope, ...(base.contextScope ?? [])]) && /^sha256:[a-f0-9]{64}$/.test(file.digest)), "input inventory corrupted or coordinator digest mismatch");
   if (environment) { assert(environment.directory === workspaceDirectory, "environment belongs to another checkout"); await verifyManagedEnvironment(environment); assert(!metadata.input.files.some(file => environment.derivedPaths.some(path => file.path === path || file.path.startsWith(`${path}/`))), "derived environment would conceal captured source"); }
-  const current = await inventory(workspaceDirectory, undefined, environment?.derivedPaths ?? []), prior = new Map(metadata.input.files.map(file => [file.path, file])), after = new Map(current.files.map(file => [file.path, file]));
+  const current = await workspaceInventory(base, workspaceDirectory, environment?.derivedPaths ?? []), prior = new Map(metadata.input.files.map(file => [file.path, file])), after = new Map(current.files.map(file => [file.path, file]));
   const files: ManagedFile[] = [];
   for (const path of [...new Set([...prior.keys(), ...after.keys()])].sort()) {
     const before = prior.get(path), next = after.get(path); if (before?.digest === next?.digest && before?.mode === next?.mode) continue;
     assert(withinScope(path, writeScope), `unauthorized change: ${path}`);
-    files.push({ path, beforeDigest: before?.digest ?? null, contentBase64: next?.contentBase64 ?? null, ...(next ? { mode: next.mode } : {}) });
+    files.push({ path, beforeDigest: before?.digest ?? null, contentBase64: next ? entryContent(next) : null, ...(next ? { mode: next.mode } : {}) });
   }
   const artifact = { digest: artifactDigest(files), files }; validateArtifact(artifact, writeScope); return artifact;
 }
@@ -165,7 +203,7 @@ export async function publishManagedArtifacts(base: ManagedBase, artifacts: Mana
   const stageParent = await safePath(base.root, ".forge/local/agent-fabric/publication-staging");
   await mkdir(stageParent, { recursive: true }); await safePath(base.root, ".forge/local/agent-fabric/publication-staging");
   const stage = await mkdtemp(join(stageParent, "publication-"));
-  for (let index = 0; index < changedFiles.length; index++) { const file = desired.get(changedFiles[index]); if (file) await writeFile(join(stage, `${index}`), Buffer.from(file.contentBase64, "base64")); }
+  for (let index = 0; index < changedFiles.length; index++) { const file = desired.get(changedFiles[index]); if (file) await writeFile(join(stage, `${index}`), Buffer.from(entryContent(file), "base64")); }
   assert((await inventory(base.root, base.scope)).digest === before.digest && await currentContextMatches(base), "source or context changed before publication");
   const applied: { path: string; writtenDigest: string | null; writtenMode: number | null }[] = [];
   try {
@@ -202,7 +240,7 @@ export async function publishManagedArtifacts(base: ManagedBase, artifacts: Mana
 export async function previewManagedArtifacts(base: ManagedBase, artifacts: ManagedArtifact[]): Promise<{ digest: string; changedFiles: string[] }> {
   await validateBase(base); const before = await inventory(base.baselineDirectory, base.scope), after = applyEntries(before.files, artifacts, base.scope);
   const old = new Map(before.files.map(file => [file.path, file])), desired = new Map(after.map(file => [file.path, file]));
-  return { digest: hash(JSON.stringify(after.map(({ path, digest, mode }) => ({ path, digest, mode })))), changedFiles: [...new Set([...old.keys(), ...desired.keys()])].filter(path => old.get(path)?.digest !== desired.get(path)?.digest || old.get(path)?.mode !== desired.get(path)?.mode).sort() };
+  return { digest: inventoryDigest(after), changedFiles: [...new Set([...old.keys(), ...desired.keys()])].filter(path => old.get(path)?.digest !== desired.get(path)?.digest || old.get(path)?.mode !== desired.get(path)?.mode).sort() };
 }
 /** Crash recovery confirms only a completely materialized publication. It never writes. */
 export async function confirmManagedPublication(base: ManagedBase, artifacts: ManagedArtifact[]): Promise<boolean> {

package/src/forge/agent-fabric/repository-context.ts

@@ -0,0 +1,83 @@
+import { readRepositoryManifest } from "../repository-manifest/index.ts";
+import { analyzeRepository } from "../repository-analysis/analyze.ts";
+import { repositoryContext } from "../repository-analysis/context.ts";
+import { readRepositorySnapshot } from "../repository-analysis/context.ts";
+import { existsSync } from "node:fs";
+import { readRuntimeObservation, runtimeSourceDigest, selectRuntimeObservation } from "../repository-analysis/runtime-observation.ts";
+import { join } from "node:path";
+import { selectRepositoryContext } from "../repository-analysis/retrieval.ts";
+import { selectRepositoryChecks } from "../repository-analysis/check-selection.ts";
+import { repositoryQualitySummary, type RepositoryQualitySummary } from "../repository-analysis/quality.ts";
+
+export interface FabricRepositoryContextMetadata {
+  provider: "repository";
+  phase: "prepared-input";
+  status: "ready" | "unavailable";
+  sourceRoot: string;
+  cloneRoot: string;
+  snapshotId?: string;
+  diagnostics: string[];
+  quality?: RepositoryQualitySummary;
+  runtime?: { reportId: string; environmentId: string; phase: "source-observed-matching-input" };
+}
+
+/** Optional static maps, taken from the clone after upstream composition and preparation.
+ * Nothing is written: an analysis cache in the clone would violate artifact write scope.
+ * Suggested checks are never executed here and maps never relax publication obligations.
+ */
+export async function prepareFabricRepositoryContext(sourceRoot: string, cloneRoot: string, query: string, scope: string[] = []): Promise<{ metadata: FabricRepositoryContextMetadata; prompt: string } | undefined> {
+  let loaded: ReturnType<typeof readRepositoryManifest>;
+  try { loaded = readRepositoryManifest(cloneRoot); }
+  catch { loaded = { manifest: null, diagnostics: ["Repository manifest cannot be read safely"] }; }
+  const { manifest, diagnostics } = loaded;
+  if (!manifest && !diagnostics.length) return undefined;
+  // JSON parser diagnostics can echo source values. Public worker metadata needs only
+  // an actionable status; detailed manifest validation is a separate user operation.
+  const metadata: FabricRepositoryContextMetadata = { provider: "repository", phase: "prepared-input", status: "unavailable", sourceRoot, cloneRoot, diagnostics: diagnostics.length ? ["Repository manifest missing, invalid or unsafe"] : [] };
+  if (!manifest) return { metadata, prompt: "Repository maps unavailable: invalid manifest. Inspect the code directly; no analysis result is claimed." };
+  try {
+    const snapshot = await analyzeRepository(cloneRoot, manifest, { write: false, factsCacheRoot: join(sourceRoot, ".forge", "repository") });
+    // Executor prompts are natural-language instructions, not CAIR query programs.
+    const context = await repositoryContext(cloneRoot, snapshot, `locate ${query.slice(0, 1000)}`, { snapshotId: snapshot.snapshotId, maxChars: 12000, limit: 20, includeSource: false });
+    metadata.snapshotId = snapshot.snapshotId;
+    metadata.diagnostics = context.diagnostics.slice(0, 20).map(item => item.slice(0, 512));
+    if (!context.ok) return { metadata, prompt: "Repository maps unavailable or stale. Inspect current clone files directly; do not reuse source-checkout analysis." };
+    metadata.quality = repositoryQualitySummary(snapshot);
+    const selection = selectRepositoryContext(snapshot, query, { writeScope: scope, maxChars: 10000, maxNodes: 30, maxEdges: 30 });
+    const checks = selectRepositoryChecks(snapshot, { scope, nodeIds: selection.nodes.map(node => node.id) }).checks.slice(0, 10);
+    // An observation is supplementary evidence about the source input, never an
+    // assertion that the SDK worker ran the application. Upstream composition or
+    // another manifest/scenario must invalidate reuse even when task files match.
+    let runtime: unknown;
+    if (existsSync(join(sourceRoot, ".forge/repository/runtime-observation.json"))) {
+      try {
+        const sourceSnapshot = readRepositorySnapshot(sourceRoot);
+        if (sourceSnapshot) {
+          const report = readRuntimeObservation(sourceRoot, sourceSnapshot);
+          if (report.binding.manifestHash === snapshot.manifestHash && report.binding.scenarioHash === snapshot.scenarioHash
+            && runtimeSourceDigest(cloneRoot, manifest) === report.binding.inputDigest) {
+            runtime = selectRuntimeObservation(report, { query, scope: [...new Set(selection.nodes.map(node => node.component))], maxChars: 4000 });
+            metadata.runtime = { reportId: report.reportId, environmentId: report.environmentId, phase: "source-observed-matching-input" };
+          }
+        }
+      } catch { /* Missing/stale observations cannot downgrade valid static maps. */ }
+    }
+    const packet = { ...selection, cloneRoot, quality: metadata.quality, coverage: { found: snapshot.coverage.found, analyzed: snapshot.coverage.analyzed,
+      unsupported: snapshot.coverage.unsupported, errors: snapshot.coverage.errors, limitations: snapshot.coverage.limitations.slice(0, 10) },
+      suggestedCheckIds: checks.map(check => ({ id: check.id, component: check.component })), suggestedChecks: checks, runtime };
+    if (JSON.stringify(packet).length > 16000 && runtime) { delete packet.runtime; delete metadata.runtime; packet.truncated = true; }
+    while (JSON.stringify(packet).length > 16000 && packet.suggestedChecks.length) { packet.suggestedChecks.pop(); packet.suggestedCheckIds.pop(); packet.truncated = true; }
+    const serialized = JSON.stringify(packet);
+    const text = serialized.length <= 16000 ? serialized : JSON.stringify({ snapshotId: snapshot.snapshotId, cloneRoot, truncated: true, reason: "Context packet exceeded budget; inspect clone directly" });
+    metadata.status = "ready";
+    return { metadata, prompt: `Repository analysis of THIS prepared clone (static evidence, not executed coverage). Optional runtime evidence was observed in an independent source copy with matching input, not executed in this worker clone; it describes only its recorded scenario and time. Source project identity: ${sourceRoot}. Ready means input prepared, not semantic completeness. Snapshot handles apply only to this snapshot. Read-only neighbors never extend write scope. Suggested checks are informational; only authorized workflow executors run checks. Maps do not replace required review, verification or file scope.\n${text}` };
+  } catch {
+    // Analysis is an optional aid. Do not expose parser exceptions or claim a fallback
+    // graph from the source checkout; the existing worker and publication gates remain.
+    metadata.status = "unavailable";
+    delete metadata.quality;
+    delete metadata.runtime;
+    metadata.diagnostics = ["Repository analysis unavailable in this prepared clone"];
+    return { metadata, prompt: "Repository analysis failed in this clone. Inspect the current files directly; no map evidence is available." };
+  }
+}

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

@@ -9,6 +9,7 @@ import { MANAGED_RUN_ACTIONS, requestManagedRun, ATTACHED_TASK_ACTIONS, isAttach
 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 { listFabricProjects, registerFabricProject, resolveFabricProject } from "../agent-fabric/project-registry.ts";
+import { runRepositoryCommand } from "../cli/repository.ts";
 
 
 const managedCommon = { runId: { type: "string" }, requestId: { type: "string" }, expectedVersion: { type: "integer", minimum: 1 } };
@@ -84,6 +85,12 @@ export async function handleMcpRequest(workspaceRoot: string, request: JsonRpcRe
     if (request.method === "tools/list") {
       return response(request.id, {
         tools: [
+          { name: "fabric_repository_discover", description: "Propose a repository analysis manifest without writing files or executing project tools.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
+          { name: "fabric_repository_analyze", description: "Analyze repository sources statically. write=true explicitly saves local map artifacts; never starts models, builds or containers.", inputSchema: { type: "object", properties: { write: { type: "boolean", default: false } }, additionalProperties: false } },
+          { name: "fabric_repository_context", description: "Read bounded snapshot-bound repository maps and evidence. Requires previously saved analysis.", inputSchema: { type: "object", properties: { query: { type: "string", maxLength: 2000 }, snapshotId: { type: "string", maxLength: 2000 }, limit: { type: "integer", minimum: 1, maximum: 100 }, maxChars: { type: "integer", minimum: 2048, maximum: 50000 }, cursor: { type: "string", maxLength: 1000 } }, additionalProperties: false } },
+          { name: "fabric_repository_runtime_plan", description: "Review manifest-declared runtime commands and artifacts without executing them.", inputSchema: { type: "object", properties: { environmentId: { type: "string", maxLength: 80 }, observationId: { type: "string", maxLength: 80 } }, required: ["environmentId"], additionalProperties: false } },
+          { name: "fabric_repository_runtime_observe", description: "Explicitly execute trusted manifest commands in a temporary source copy. May install dependencies, access network or containers as declared; this is filesystem isolation, not an OS sandbox. Review the plan first. Requires execute=true; write=true saves a sanitized local report.", inputSchema: { type: "object", properties: { environmentId: { type: "string", maxLength: 80 }, observationId: { type: "string", maxLength: 80 }, execute: { const: true }, write: { type: "boolean", default: false } }, required: ["environmentId", "execute"], additionalProperties: false } },
+          { name: "fabric_repository_runtime_context", description: "Read bounded current runtime evidence; rejects expired reports and changed inputs. Does not start processes.", inputSchema: { type: "object", properties: { environmentId: { type: "string", maxLength: 80 }, query: { type: "string", maxLength: 2000 }, maxChars: { type: "integer", minimum: 2048, maximum: 16000 } }, additionalProperties: false } },
           { 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.",
@@ -226,7 +233,7 @@ export async function handleMcpRequest(workspaceRoot: string, request: JsonRpcRe
       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) {
+      if (name !== CODEX_MCP_HOOK_TOOL && !name.startsWith("fabric_repository_")) {
         await logMcpToolCall(toolRoot, name, args, "completed").catch(() => undefined);
       }
       return response(request.id, {
@@ -269,6 +276,36 @@ export async function runMcpServe(workspaceRoot: string): Promise<number> {
 }
 
 async function runTool(workspaceRoot: string, name: string, args: Record<string, unknown>, options: FabricMcpOptions): Promise<unknown> {
+  if (name.startsWith("fabric_repository_")) {
+    const action = name.slice("fabric_repository_".length).replaceAll("_", "-");
+    if (!["discover", "analyze", "context", "runtime-plan", "runtime-observe", "runtime-context"].includes(action)) throw new Error("Unknown repository operation");
+    const allowed = action === "runtime-plan" ? ["environmentId", "observationId"] : action === "runtime-observe" ? ["environmentId", "observationId", "execute", "write"] : action === "runtime-context" ? ["environmentId", "query", "maxChars"] : action === "context" ? ["query", "snapshotId", "limit", "maxChars", "cursor"] : action === "analyze" ? ["write"] : [];
+    if (Object.keys(args).some(key => !allowed.includes(key))) throw new Error("Unknown repository argument");
+    for (const [key, max] of [["query", 2000], ["snapshotId", 2000], ["cursor", 1000]] as const) if (key in args && (typeof args[key] !== "string" || (args[key] as string).length > max)) throw new Error(`Invalid ${key}`);
+    for (const [key, min, max] of [["limit", 1, 100], ["maxChars", 2048, 50000]] as const) if (key in args && (!Number.isSafeInteger(args[key]) || (args[key] as number) < min || (args[key] as number) > max)) throw new Error(`Invalid ${key}`);
+    if ("write" in args && typeof args.write !== "boolean") throw new Error("write must be boolean");
+    for (const key of ["environmentId", "observationId"]) if (key in args && (typeof args[key] !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/.test(args[key] as string))) throw new Error("Invalid runtime label");
+    if ("execute" in args && args.execute !== true) throw new Error("Runtime execution requires execute=true");
+    const result = await runRepositoryCommand({ action: action as import("../cli/repository.ts").RepositoryCliOptions["action"], cwd: workspaceRoot, root: workspaceRoot,
+      json: true, write: args.write === true, query: args.query as string | undefined, snapshotId: args.snapshotId as string | undefined,
+      limit: args.limit as number | undefined, maxChars: args.maxChars as number | undefined, cursor: args.cursor as string | undefined,
+      environmentId: args.environmentId as string | undefined, observationId: args.observationId as string | undefined, execute: args.execute === true });
+    const { snapshot, ...compact } = result;
+    if (action === "runtime-observe" && result.report) {
+      const report = result.report as import("../repository-analysis/runtime-observation.ts").RuntimeObservationReport;
+      const { selectRuntimeObservation } = await import("../repository-analysis/runtime-observation.ts");
+      return { ok: result.ok, exitCode: result.exitCode, wroteArtifacts: result.wroteArtifacts, reportId: report.reportId,
+        observations: report.observations.map(item => ({ id: item.id, component: item.component, status: item.status, factCount: item.facts.length, artifactCount: item.artifacts.length })),
+        context: selectRuntimeObservation(report, { maxChars: 4000 }), nextAction: "fabric_repository_runtime_context" };
+    }
+    if (snapshot) {
+      const coverage = (snapshot as import("../repository-analysis/types.ts").RepositorySnapshot).coverage;
+      return { ...compact, coverage: { ...coverage, diagnostics: coverage.diagnostics.slice(0, 20), ignoredPaths: coverage.ignoredPaths.slice(0, 20), limitations: coverage.limitations.slice(0, 20),
+        omitted: { diagnostics: Math.max(0, coverage.diagnostics.length - 20), ignoredPaths: Math.max(0, coverage.ignoredPaths.length - 20), limitations: Math.max(0, coverage.limitations.length - 20) } },
+        nextAction: args.write === true ? "fabric_repository_context" : "fabric_repository_analyze with write=true explicitly saves this analysis for later queries" };
+    }
+    return compact;
+  }
   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");

package/src/forge/cair/index.ts

@@ -3,7 +3,9 @@ import type { Diagnostic } from "../compiler/types/diagnostic.ts";
 import { runCairActionScript, statActionInput } from "./actions.ts";
 import { buildCairSnapshot } from "./snapshot.ts";
 import { runCairQuery } from "./query.ts";
-import type { CairCommandOptions, CairCommandResult, CairSnapshotLimits } from "./types.ts";
+import type { CairCommandOptions, CairCommandResult, CairSnapshotLimits } from "./types.ts";
+import { readRepositoryManifest } from "../repository-manifest/index.ts";
+import { readRepositorySnapshot, runRepositoryCairCommand, unavailableRepositoryCairCommand } from "../repository-analysis/context.ts";
 
 export {
   CAIR_SCHEMA_VERSION,
@@ -24,8 +26,18 @@ const QUERY_LIMITS: CairSnapshotLimits = {
   tests: 1_000_000,
 };
 
-export function runCairCommand(options: CairCommandOptions): CairCommandResult {
-  const snapshot = buildCairSnapshot(
+export function runCairCommand(options: CairCommandOptions): CairCommandResult {
+  const repository = readRepositoryManifest(options.workspaceRoot, { manifestPath: options.manifestPath });
+  if (repository.manifest || repository.diagnostics.length > 0) {
+    try {
+      const repositorySnapshot = readRepositorySnapshot(options.workspaceRoot, { cacheRoot: options.cacheRoot });
+      if (repositorySnapshot && repository.diagnostics.length === 0) return runRepositoryCairCommand(options, repositorySnapshot);
+      return unavailableRepositoryCairCommand(options, repository.diagnostics.join("; ") || "Repository snapshot is unavailable; run forge repository analyze first.");
+    } catch (error) {
+      return unavailableRepositoryCairCommand(options, error instanceof Error ? error.message : String(error));
+    }
+  }
+  const snapshot = buildCairSnapshot(
     options.workspaceRoot,
     options.subcommand === "query" || options.subcommand === "action" ? QUERY_LIMITS : undefined,
   );

package/src/forge/cair/types.ts

@@ -18,7 +18,13 @@ export interface CairCommandOptions {
   inputPath?: string;
   dryRun?: boolean;
   plan?: boolean;
-  allowGenerated?: boolean;
+  allowGenerated?: boolean;
+  /** Required when resolving repository snapshot-local handles. */
+  snapshotId?: string;
+  manifestPath?: string;
+  cacheRoot?: string;
+  root?: string;
+  projectId?: string;
 }
 
 export interface CairProjectRef {
@@ -108,7 +114,8 @@ export interface CairSnapshotLimits {
   tests: number;
 }
 
-export interface CairSnapshot {
+export interface CairSnapshot {
+  provider?: "forge-application" | "repository";
   schemaVersion: typeof CAIR_SCHEMA_VERSION;
   kind: "cair.snapshot";
   snapshotId: string;

package/src/forge/cli/commands.ts

@@ -76,6 +76,8 @@ import {
   formatCairJson,
   runCairCommand,
 } from "../cair/index.ts";
+import { runRepositoryCommand } from "./repository.ts";
+import { readRepositoryManifest, resolveRepositoryRoot } from "../repository-manifest/index.ts";
 import { uniqueNextActions } from "./next-actions.ts";
 import {
   formatRunJson,
@@ -1602,6 +1604,8 @@ function runManifestCommand(command: Extract<ForgeCommand, { kind: "manifest" }>
   exitCode: number;
 } {
   if (command.subcommand === "validate") {
+    const checked = readRepositoryManifest(command.workspaceRoot, { manifestPath: command.path });
+    if (checked.manifest || checked.diagnostics.length) return { subcommand: "validate", path: command.path, diagnostics: checked.diagnostics.map(message => createDiagnostic({ severity: "error", code: "FORGE_REPOSITORY_MANIFEST", message })), exitCode: checked.manifest ? 0 : 1 };
     const result = readExternalManifestFile(command.path);
     const hasErrors = result.diagnostics.some((diagnostic) => diagnostic.severity === "error");
     return {
@@ -2304,6 +2308,16 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       return result.exitCode;
     }
     case "cair": {
+      let root: string;
+      try { root = await resolveRepositoryRoot({ cwd: command.options.workspaceRoot, root: command.options.root, projectId: command.options.projectId, manifestPath: command.options.manifestPath }); }
+      catch (error) {
+        const diagnostic = createDiagnostic({ severity: "error", code: "FORGE_REPOSITORY_ROOT", message: (error as Error).message });
+        if (command.options.json || command.options.format === "json") process.stdout.write(formatJsonResult({ ok: false, diagnostics: [diagnostic], exitCode: 1 }));
+        else console.error(`error ${diagnostic.code}: ${diagnostic.message}`);
+        return 1;
+      }
+      const repository = readRepositoryManifest(root, { manifestPath: command.options.manifestPath });
+      if (repository.manifest || repository.diagnostics.length || command.options.root || command.options.projectId) command.options.workspaceRoot = root;
       const result = runCairCommand(command.options);
       process.stdout.write(
         command.options.json || command.options.format === "json"
@@ -2477,6 +2491,11 @@ export async function executeCommand(command: ForgeCommand): Promise<number> {
       }
       return result.exitCode;
     }
+    case "repository": {
+      const result = await runRepositoryCommand(command.options);
+      process.stdout.write(`${JSON.stringify(result, null, command.options.json ? 2 : 2)}\n`);
+      return result.exitCode;
+    }
     case "import": {
       const result = runBrownfieldImportCommand(command.options);
       if (command.options.json) {

package/src/forge/cli/main.ts

@@ -5,10 +5,21 @@ import { executeCommand } from "./commands.ts";
 import { hasUnknownOption, parseCli } from "./parse.ts";
 import { formatJsonResult } from "./output.ts";
 import { recordParsedCliCommand } from "../delta/index.ts";
+import { readRepositoryManifest } from "../repository-manifest/index.ts";
 
 function formatHelp(): string {
   return [
     "ForgeOS",
+    "  forge manifest discover --root <path> --json  Propose a repository manifest without writing",
+    "  forge repository analyze --write --json  Analyze Vue/Java/Docker and save a coherent local map",
+    "  forge repository context --query routes --json  Read snapshot-bound repository context",
+    "  forge repository quality --cases tasks.json --json  Evaluate reviewed static task fixtures without running a model",
+    "  forge repository cache-gc --json  Preview cache cleanup; --write applies after retention",
+    "  forge repository benchmark-plan --cases tasks.json --model-config model.json --json  Prepare paired agent experiment",
+    "  forge repository benchmark-report --plan plan.json --observations observations.json --json  Compare supplied evidence",
+    "  forge repository runtime-plan --environment-id local --json  Review declared runtime commands without executing",
+    "  forge repository runtime-observe --environment-id local --execute --write --json  Execute in a temporary source copy and save observations",
+    "  forge repository runtime-context --environment-id local --query checkout --json  Read current, bounded runtime evidence",
     "",
     "Start with one of these:",
     "  forge status --json       Compact project health, handoff state, and next actions",
@@ -249,6 +260,10 @@ export async function main(argv: string[] = process.argv.slice(2)): Promise<numb
 
   const startedAt = Date.now();
   const exitCode = await executeCommand(parsed.command);
+  const repositoryRead = parsed.command.kind === "repository" ||
+    (parsed.command.kind === "manifest" && parsed.command.subcommand === "validate") ||
+    (parsed.command.kind === "cair" && (() => { const repository = readRepositoryManifest(parsed.command.options.workspaceRoot, { manifestPath: parsed.command.options.manifestPath }); return !!repository.manifest || repository.diagnostics.length > 0; })());
+  if (repositoryRead) return exitCode;
   await recordParsedCliCommand({
     command: parsed.command,
     argv,