forgeos 0.1.0-alpha.21 → 0.1.0-alpha.23

package/src/forge/cli/parse.ts

@@ -112,7 +112,7 @@ export type ForgeCommand =
       json: boolean;
       workspaceRoot: string;
     }
-  | { kind: "doctor"; target?: "project" | "windows" | "agent"; agentTarget?: AgentAdapterTarget; json: boolean; workspaceRoot: string }
+  | { kind: "doctor"; target?: "project" | "windows" | "agent" | "delta"; agentTarget?: AgentAdapterTarget; json: boolean; workspaceRoot: string }
   | { kind: "setup"; target: "windows"; json: boolean; yes: boolean; workspaceRoot: string }
   | {
       kind: "security";
@@ -183,7 +183,19 @@ export type ForgeCommand =
   | { kind: "ui"; options: UiCommandOptions }
   | { kind: "manifest"; subcommand: "validate" | "import"; path: string; json: boolean; workspaceRoot: string }
   | { kind: "import"; options: BrownfieldImportCommandOptions }
-  | { kind: "delta"; subcommand: "status" | "repair"; json: boolean; workspaceRoot: string; dryRun: boolean; yes: boolean; verbose: boolean }
+  | {
+      kind: "delta";
+      subcommand: "status" | "repair" | "compact" | "prune" | "export";
+      json: boolean;
+      workspaceRoot: string;
+      dryRun: boolean;
+      yes: boolean;
+      verbose: boolean;
+      olderThan?: string;
+      output?: string;
+      limit?: number;
+      redacted: boolean;
+    }
   | { kind: "status"; json: boolean; workspaceRoot: string }
   | { kind: "changed"; json: boolean; authoredOnly: boolean; workspaceRoot: string }
   | { kind: "diff"; target: "authored" | "generated" | "full"; json: boolean; workspaceRoot: string }
@@ -212,7 +224,7 @@ export type ForgeCommand =
       force: boolean;
       workspaceRoot: string;
     }
-  | { kind: "timeline"; target?: string; kindFilter?: string; sessionId?: string; limit?: number; json: boolean; rebuild: boolean; forAgent: boolean; workspaceRoot: string }
+  | { kind: "timeline"; target?: string; kindFilter?: string; sessionId?: string; limit?: number; json: boolean; rebuild: boolean; forAgent: boolean; causal: boolean; staleProofs: boolean; workspaceRoot: string }
   | { kind: "explain"; thing: string; json: boolean; workspaceRoot: string }
   | {
       kind: "session";
@@ -480,7 +492,7 @@ export const INSPECT_TARGETS: InspectTarget[] = [
   "map",
 ];
 
-const NEW_TEMPLATES: NewTemplateName[] = ["agent-workroom", "b2b-support-web", "minimal-web"];
+const NEW_TEMPLATES: NewTemplateName[] = ["agent-workroom", "b2b-support-web", "minimal-web", "nuxt-web"];
 const NEW_PACKAGE_MANAGERS: NewPackageManager[] = ["bun", "npm", "pnpm", "yarn"];
 const SELF_HOST_SUBCOMMANDS: SelfHostSubcommand[] = ["compose", "env", "check", "clean"];
 const AGENT_CONTRACT_SUBCOMMANDS: AgentContractSubcommand[] = [
@@ -1015,6 +1027,22 @@ export function parseCli(argv: string[]): ParsedCli {
         (subcommand === "timeline" ? rest[1] : undefined) ??
         (subcommand === "timeline" ? "all" : undefined) ??
         (subcommand === "hooks" || subcommand === "onboard" ? "codex" : "generic");
+      const contextOptionValues = new Set(
+        [
+          parseOptionValue(argv, "--entry"),
+          parseOptionValue(argv, "--change"),
+          parseOptionValue(argv, "--proof"),
+          parseOptionValue(argv, "--event"),
+          parseOptionValue(argv, "--input"),
+          parseOptionValue(argv, "--target"),
+          parseOptionValue(argv, "--file"),
+          limitRaw,
+          pollIntervalRaw,
+        ].filter((value): value is string => typeof value === "string"),
+      );
+      const contextEntry = subcommand === "context"
+        ? rest.slice(1).find((part) => !part.startsWith("--") && !contextOptionValues.has(part))
+        : undefined;
       return {
         command: {
           kind: "agent",
@@ -1031,7 +1059,10 @@ export function parseCli(argv: string[]): ParsedCli {
             eventName: parseOptionValue(argv, "--event"),
             hookAction: subcommand === "hooks" ? rest[1] : undefined,
             input,
-            entry: parseOptionValue(argv, "--entry") ?? (subcommand === "context" && rest[1] !== "--current" ? rest[1] : undefined),
+            entry: parseOptionValue(argv, "--entry") ?? contextEntry,
+            change: parseOptionValue(argv, "--change"),
+            proof: parseOptionValue(argv, "--proof"),
+            handoff: parseFlag(argv, "--handoff"),
             current: parseFlag(argv, "--current"),
             limit: limit ? Math.floor(limit) : undefined,
             watch: parseFlag(argv, "--watch"),
@@ -1152,14 +1183,14 @@ export function parseCli(argv: string[]): ParsedCli {
       };
     }
     case "doctor":
-      if (rest[0] && rest[0] !== "windows" && rest[0] !== "agent") {
-        errors.push("forge doctor supports subcommand: windows or agent");
+      if (rest[0] && rest[0] !== "windows" && rest[0] !== "agent" && rest[0] !== "delta") {
+        errors.push("forge doctor supports subcommand: windows, agent, or delta");
         return { command: null, workspaceRoot, errors };
       }
       return {
         command: {
           kind: "doctor",
-          target: rest[0] === "windows" ? "windows" : rest[0] === "agent" ? "agent" : "project",
+          target: rest[0] === "windows" ? "windows" : rest[0] === "agent" ? "agent" : rest[0] === "delta" ? "delta" : "project",
           agentTarget: rest[0] === "agent"
             ? (parseOptionValue(argv, "--target") as AgentAdapterTarget | undefined) ?? (rest[1] as AgentAdapterTarget | undefined) ?? "codex"
             : undefined,
@@ -1882,10 +1913,12 @@ export function parseCli(argv: string[]): ParsedCli {
     }
     case "delta": {
       const subcommand = rest[0];
-      if (subcommand !== "status" && subcommand !== "repair") {
-        errors.push("forge delta requires subcommand: status or repair");
+      if (subcommand !== "status" && subcommand !== "repair" && subcommand !== "compact" && subcommand !== "prune" && subcommand !== "export") {
+        errors.push("forge delta requires subcommand: status, repair, compact, prune, or export");
         return { command: null, workspaceRoot, errors };
       }
+      const limitRaw = parseOptionValue(argv, "--limit");
+      const limit = limitRaw ? Number(limitRaw) : undefined;
       return {
         command: {
           kind: "delta",
@@ -1894,6 +1927,10 @@ export function parseCli(argv: string[]): ParsedCli {
           dryRun: parseFlag(argv, "--dry-run"),
           yes: parseFlag(argv, "--yes"),
           verbose: parseFlag(argv, "--verbose"),
+          olderThan: parseOptionValue(argv, "--older-than"),
+          output: parseOptionValue(argv, "--output"),
+          limit: Number.isFinite(limit) ? limit : undefined,
+          redacted: parseFlag(argv, "--redacted"),
           workspaceRoot,
         },
         workspaceRoot,
@@ -1933,7 +1970,10 @@ export function parseCli(argv: string[]): ParsedCli {
       const kindFilter = parseOptionValue(argv, "--kind");
       const sessionId = parseOptionValue(argv, "--session");
       const rebuild = rest[0] === "rebuild";
-      const target = rebuild ? undefined : rest.find((item) => item !== kindFilter && item !== limitRaw && item !== sessionId);
+      const optionValues = new Set([limitRaw, kindFilter, sessionId].filter((value): value is string => typeof value === "string"));
+      const target = rebuild
+        ? undefined
+        : rest.find((item) => !item.startsWith("--") && !optionValues.has(item));
       const limit = limitRaw ? Number(limitRaw) : undefined;
       if (limitRaw !== undefined && (!Number.isFinite(limit) || limit! < 1)) {
         errors.push("--limit must be a number >= 1");
@@ -1948,6 +1988,8 @@ export function parseCli(argv: string[]): ParsedCli {
             json: parseFlag(argv, "--json"),
             rebuild,
             forAgent: parseFlag(argv, "--for-agent"),
+            causal: parseFlag(argv, "--causal"),
+            staleProofs: parseFlag(argv, "--stale-proofs"),
             workspaceRoot,
           },
         workspaceRoot,
@@ -2642,6 +2684,8 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--json",
     "--human",
     "--for-agent",
+    "--causal",
+    "--stale-proofs",
     "--dry-run",
     "--plan",
     "--staged",
@@ -2698,6 +2742,9 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--emit",
     "--event",
     "--entry",
+    "--change",
+    "--proof",
+    "--handoff",
     "--current",
     "--trigger",
     "--component",
@@ -2794,6 +2841,8 @@ export function hasUnknownOption(argv: string[]): string | null {
     "--env-file",
     "--skip-startup-console",
     "--redacted",
+    "--older-than",
+    "--output",
     "--mock-ai",
     "--ai",
     "--provider",
@@ -2857,6 +2906,8 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--emit" ||
         arg === "--event" ||
         arg === "--entry" ||
+        arg === "--change" ||
+        arg === "--proof" ||
         arg === "--trigger" ||
         arg === "--component" ||
         arg === "--package" ||
@@ -2901,6 +2952,8 @@ export function hasUnknownOption(argv: string[]): string | null {
         arg === "--db" ||
         arg === "--database-url" ||
         arg === "--limit" ||
+        arg === "--older-than" ||
+        arg === "--output" ||
         arg === "--kind" ||
         arg === "--session" ||
         arg === "--input" ||

package/src/forge/cli/studio.ts

@@ -139,6 +139,15 @@ export interface StudioSnapshotResult {
     commands: string[];
     diffPlan?: DevConsoleDiffPlan;
   };
+  handoff: {
+    previewUrl: string;
+    currentSession?: { id?: string; title?: string; status?: string; confidence?: number };
+    changedFiles?: number;
+    generatedState?: string;
+    deltaHealth?: string;
+    agentContextCommand: string;
+    recommendedCommands: string[];
+  };
   proofs: {
     preview: StudioAttachResult["preview"]["status"];
     generated: StudioAttachResult["posture"]["generated"];
@@ -981,6 +990,13 @@ export async function runStudioSnapshotCommand(options: StudioAttachOptions): Pr
     : undefined;
   const delta = await runDeltaStatus(appRoot);
   const contextPacket = contextPacketFor({ appRoot, posture, commands });
+  const handoff = studioHandoffFor({
+    previewUrl: preview.url,
+    posture,
+    changed: changed.data,
+    delta,
+    commands,
+  });
   const gitState = (changed.data as { git?: { available?: boolean } }).git;
   const changedReadable = changed.ok || gitState?.available === false;
   const ok = posture.state !== "needs-attention" && changedReadable &&
@@ -1006,6 +1022,7 @@ export async function runStudioSnapshotCommand(options: StudioAttachOptions): Pr
     changed: changed.data,
     commands,
     contextPacket,
+    handoff,
     proofs: {
       preview: preview.status,
       generated: posture.generated,
@@ -1019,6 +1036,43 @@ export async function runStudioSnapshotCommand(options: StudioAttachOptions): Pr
   };
 }
 
+function studioHandoffFor(input: {
+  previewUrl: string;
+  posture: StudioSnapshotResult["posture"];
+  changed: Record<string, unknown>;
+  delta: unknown;
+  commands: StudioSnapshotResult["commands"];
+}): StudioSnapshotResult["handoff"] {
+  const changedSummary = input.changed.summary as { changedFiles?: unknown } | undefined;
+  const deltaRecord = input.delta && typeof input.delta === "object" && !Array.isArray(input.delta)
+    ? input.delta as { workSession?: { id?: unknown; title?: unknown; status?: unknown; confidence?: unknown }; details?: { health?: { status?: unknown } } }
+    : undefined;
+  const workSession = deltaRecord?.workSession;
+  return {
+    previewUrl: input.previewUrl,
+    ...(workSession
+      ? {
+          currentSession: {
+            ...(typeof workSession.id === "string" ? { id: workSession.id } : {}),
+            ...(typeof workSession.title === "string" ? { title: workSession.title } : {}),
+            ...(typeof workSession.status === "string" ? { status: workSession.status } : {}),
+            ...(typeof workSession.confidence === "number" ? { confidence: workSession.confidence } : {}),
+          },
+        }
+      : {}),
+    ...(typeof changedSummary?.changedFiles === "number" ? { changedFiles: changedSummary.changedFiles } : {}),
+    generatedState: input.posture.generated?.state,
+    deltaHealth: typeof deltaRecord?.details?.health?.status === "string" ? deltaRecord.details.health.status : undefined,
+    agentContextCommand: "forge agent context --handoff --json",
+    recommendedCommands: [
+      input.commands.handoff,
+      "forge agent context --handoff --json",
+      input.commands.changed,
+      input.commands.doctor,
+    ],
+  };
+}
+
 export async function runStudioWatchCommand(options: StudioAttachOptions): Promise<StudioWatchResult> {
   const snapshot = await runStudioSnapshotCommand(options);
   const intervalMs = Math.max(1000, Math.floor(options.intervalMs ?? 5000));

package/src/forge/cli/verify.ts

@@ -695,6 +695,7 @@ const STRICT_TEST_FALLBACK_MS_BY_PATH: Array<{ pattern: RegExp; estimatedMs: num
   { pattern: /^tests\/templates\/new-b2b-support-web\.test\.ts$/, estimatedMs: 12_000 },
   { pattern: /^tests\/templates\/new-agent-workroom\.test\.ts$/, estimatedMs: 12_000 },
   { pattern: /^tests\/templates\/new-minimal-web\.test\.ts$/, estimatedMs: 12_000 },
+  { pattern: /^tests\/templates\/new-nuxt-web\.test\.ts$/, estimatedMs: 12_000 },
   { pattern: /^tests\/templates\/create-forge-app\.test\.ts$/, estimatedMs: 8_000 },
 ];
 const STRICT_ISOLATED_TEST_PATTERNS = [
@@ -730,6 +731,7 @@ const STRICT_ISOLATED_TEST_PATTERNS = [
   /^tests\/templates\/new-b2b-support-web\.test\.ts$/,
   /^tests\/templates\/new-agent-workroom\.test\.ts$/,
   /^tests\/templates\/new-minimal-web\.test\.ts$/,
+  /^tests\/templates\/new-nuxt-web\.test\.ts$/,
   /^tests\/telemetry\/telemetry-dev-server\.test\.ts$/,
 ];
 const STRICT_SERIAL_TEST_PATTERNS: RegExp[] = [];

package/src/forge/compiler/frontend-graph/build.ts

@@ -229,6 +229,58 @@ function detectRouteUses(file: string, text: string, clientManifest: ClientManif
   return uses;
 }
 
+function localComposableNames(file: string, text: string): string[] {
+  const relName = componentNameForFile(file);
+  const names = [relName.startsWith("use") ? relName : `use${relName.slice(0, 1).toUpperCase()}${relName.slice(1)}`];
+  for (const match of text.matchAll(/export\s+function\s+(use[A-Z][A-Za-z0-9_]*)\s*\(/g)) {
+    if (match[1]) {
+      names.push(match[1]);
+    }
+  }
+  return uniqueSorted(names);
+}
+
+function buildComposableUseIndex(
+  webRoot: string,
+  sourceFiles: string[],
+  clientManifest: ClientManifest,
+): Map<string, ReturnType<typeof detectUses>> {
+  const index = new Map<string, ReturnType<typeof detectUses>>();
+  for (const file of sourceFiles) {
+    const rel = toPosix(relative(webRoot, file));
+    if (!rel.startsWith("composables/") && !rel.startsWith("src/composables/")) {
+      continue;
+    }
+    if (rel.endsWith("/forge.ts") || rel === "composables/forge.ts" || rel === "src/composables/forge.ts") {
+      continue;
+    }
+    const text = nodeFileSystem.readText(file) ?? "";
+    const uses = detectUses(text, clientManifest);
+    for (const name of localComposableNames(file, text)) {
+      index.set(name, uses);
+    }
+  }
+  return index;
+}
+
+function detectLocalComposableUses(
+  text: string,
+  composableUseIndex: Map<string, ReturnType<typeof detectUses>>,
+): ReturnType<typeof detectUses> {
+  let uses: ReturnType<typeof detectUses> = {
+    usesCommands: [],
+    usesQueries: [],
+    usesLiveQueries: [],
+    rawForgeFetches: [],
+  };
+  for (const [name, composableUses] of composableUseIndex) {
+    if (new RegExp(`\\b${name}\\s*\\(`).test(text)) {
+      uses = mergeUses(uses, composableUses);
+    }
+  }
+  return uses;
+}
+
 function devCommandFor(webRoot: string, framework: FrontendGraph["framework"]): string {
   const pkg = readJson<{ scripts?: Record<string, string> }>(join(webRoot, "package.json"));
   if (pkg?.scripts?.dev) {
@@ -347,6 +399,7 @@ export function buildFrontendGraph(input: {
   const bridgeFiles: string[] = [];
   const diagnostics: FrontendGraph["diagnostics"] = [];
   const textByRel = new Map<string, string>();
+  const composableUseIndex = buildComposableUseIndex(webRoot, sourceFiles, input.clientManifest);
 
   for (const file of sourceFiles) {
     const rel = toPosix(relative(input.workspaceRoot, file));
@@ -359,7 +412,10 @@ export function buildFrontendGraph(input: {
       rel === "web/composables/forge.ts" ||
       rel === "web/plugins/forge.ts";
     textByRel.set(rel, text);
-    const uses = detectUses(text, input.clientManifest);
+    const uses = mergeUses(
+      detectUses(text, input.clientManifest),
+      detectLocalComposableUses(text, composableUseIndex),
+    );
     if (isComponentFile(webRoot, file, text)) {
       components.push({ name: componentNameForText(file, text), file: rel, ...uses });
     }
@@ -469,7 +525,7 @@ export function buildFrontendGraph(input: {
         ? "Nuxt app does not expose a Forge plugin; generated composables may not be wired"
         : "web app does not expose a ForgeProvider; generated hooks may not be wired",
       fixHint: framework === "nuxt"
-        ? "Create web/plugins/forge.ts and call provideForge with runtimeConfig.public.forgeUrl and devAuth for local development."
+        ? "Create web/plugins/forge.client.ts and web/plugins/forge.server.ts and install ForgeVuePlugin with runtimeConfig.public.forgeUrl and devAuth for local development."
         : "Mount ForgeProvider once in the web app root/provider layer and pass devAuth for local development.",
       suggestedCommands: ["forge inspect frontend --json", `forge make ui --framework ${framework === "nuxt" ? "nuxt" : "vite"} --dry-run --json`],
       docs: ["src/forge/_generated/frontendGraph.json", "AGENTS.md"],

package/src/forge/delta/explain.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { DeltaStore } from "./store.ts";
 
 export interface DeltaExplainResult {
@@ -13,10 +15,11 @@ export async function runDeltaExplain(input: {
 }): Promise<DeltaExplainResult> {
   const store = await DeltaStore.open(input.workspaceRoot, { access: "read" });
   try {
+    const explanation = await store.explain(input.thing);
     return {
       ok: true,
       thing: input.thing,
-      explanation: await store.explain(input.thing),
+      explanation: enrichWithCurrentAgentContract(input.workspaceRoot, input.thing, explanation),
       exitCode: 0,
     };
   } finally {
@@ -68,6 +71,9 @@ export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
     lines.push("Runtime:");
     lines.push(`  kind: ${String(runtime.entry_kind ?? "unknown")}`);
     lines.push(`  result: ${String(runtime.result ?? "unknown")}`);
+    if (runtime.source) {
+      lines.push(`  source: ${String(runtime.source)}`);
+    }
     if (runtime.diagnostic_code) {
       lines.push(`  diagnostic: ${String(runtime.diagnostic_code)}`);
     }
@@ -94,6 +100,22 @@ export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
       }
     }
   }
+  const currentContract = explanation.currentContract as Record<string, unknown> | null | undefined;
+  if (currentContract) {
+    lines.push("");
+    lines.push("Current contract:");
+    lines.push(`  kind: ${String(currentContract.kind ?? "unknown")}`);
+    lines.push(`  name: ${String(currentContract.name ?? result.thing)}`);
+    if (currentContract.auth) {
+      lines.push(`  auth: ${String(currentContract.auth)}`);
+    }
+    if (currentContract.policy) {
+      lines.push(`  policy: ${String(currentContract.policy)}`);
+    }
+    if (currentContract.sourceFile) {
+      lines.push(`  file: ${String(currentContract.sourceFile)}`);
+    }
+  }
   lines.push("");
   lines.push("Introduced in:");
   if (workSessions.length === 0) {
@@ -124,3 +146,93 @@ export function formatDeltaExplainHuman(result: DeltaExplainResult): string {
 export function formatDeltaExplainJson(result: DeltaExplainResult): string {
   return `${JSON.stringify(result, null, 2)}\n`;
 }
+
+function enrichWithCurrentAgentContract(
+  workspaceRoot: string,
+  thing: string,
+  explanation: Record<string, unknown>,
+): Record<string, unknown> {
+  const currentContract = currentContractForThing(workspaceRoot, thing);
+  if (!currentContract) {
+    return explanation;
+  }
+  const runtime = explanation.runtime && typeof explanation.runtime === "object"
+    ? explanation.runtime as Record<string, unknown>
+    : null;
+  return {
+    ...explanation,
+    type: explanation.type === "unknown" ? "runtime-entry" : explanation.type,
+    runtime: runtime ?? {
+      entry_name: currentContract.name,
+      entry_kind: currentContract.kind,
+      result: "defined",
+      source: "agentContract",
+      ...(currentContract.policy ? { policy: currentContract.policy } : {}),
+      ...(typeof currentContract.tenantScoped === "boolean" ? { tenant_scoped: currentContract.tenantScoped } : {}),
+      ...(typeof currentContract.needsApproval === "boolean" ? { needs_approval: currentContract.needsApproval } : {}),
+    },
+    currentContract,
+  };
+}
+
+function currentContractForThing(workspaceRoot: string, thing: string): Record<string, unknown> | undefined {
+  const contractPath = join(workspaceRoot, "src", "forge", "_generated", "agentContract.json");
+  if (!existsSync(contractPath)) {
+    return undefined;
+  }
+  try {
+    const contract = JSON.parse(readFileSync(contractPath, "utf8")) as Record<string, unknown>;
+    const collections: Array<[keyof typeof runtimeKinds, string]> = [
+      ["commands", "command"],
+      ["queries", "query"],
+      ["liveQueries", "liveQuery"],
+      ["actions", "action"],
+      ["workflows", "workflow"],
+    ];
+    for (const [collection, kind] of collections) {
+      const entries = Array.isArray(contract[collection]) ? contract[collection] as Record<string, unknown>[] : [];
+      for (const entry of entries) {
+        const name = runtimeEntryName(entry);
+        if (!name) {
+          continue;
+        }
+        if (name === thing || `${kind}:${name}` === thing || entry.id === thing || entry.exportName === thing) {
+          return {
+            source: "src/forge/_generated/agentContract.json",
+            kind,
+            name,
+            ...(stringValue(entry.auth) ? { auth: stringValue(entry.auth) } : {}),
+            ...(stringValue(entry.policy) ? { policy: stringValue(entry.policy) } : {}),
+            ...(typeof entry.tenantScoped === "boolean" ? { tenantScoped: entry.tenantScoped } : {}),
+            ...(typeof entry.needsApproval === "boolean" ? { needsApproval: entry.needsApproval } : {}),
+            ...(stringValue(entry.risk) ? { risk: stringValue(entry.risk) } : {}),
+            ...(stringValue(entry.file) ? { sourceFile: stringValue(entry.file) } : {}),
+            ...(stringValue(entry.path) ? { sourceFile: stringValue(entry.path) } : {}),
+          };
+        }
+      }
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+const runtimeKinds = {
+  commands: "command",
+  queries: "query",
+  liveQueries: "liveQuery",
+  actions: "action",
+  workflows: "workflow",
+} as const;
+
+function runtimeEntryName(entry: Record<string, unknown>): string | undefined {
+  return stringValue(entry.name)
+    ?? stringValue(entry.exportName)
+    ?? stringValue(entry.id)
+    ?? stringValue(entry.entryName);
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/src/forge/delta/index.ts

@@ -1,10 +1,22 @@
 export {
   runDeltaStatus,
   runDeltaRepair,
+  runDeltaCompact,
+  runDeltaPrune,
+  runDeltaExport,
+  runDeltaDoctor,
   formatDeltaStatusHuman,
   formatDeltaStatusJson,
   formatDeltaRepairHuman,
   formatDeltaRepairJson,
+  formatDeltaDoctorHuman,
+  formatDeltaDoctorJson,
+  formatDeltaCompactHuman,
+  formatDeltaCompactJson,
+  formatDeltaPruneHuman,
+  formatDeltaPruneJson,
+  formatDeltaExportHuman,
+  formatDeltaExportJson,
 } from "./status.ts";
 export { runDeltaTimeline, formatDeltaTimelineHuman, formatDeltaTimelineJson } from "./timeline.ts";
 export { runDeltaExplain, formatDeltaExplainHuman, formatDeltaExplainJson } from "./explain.ts";

package/src/forge/delta/recorder.ts

@@ -260,6 +260,27 @@ async function recordSpecializedCommand(
     return;
   }
 
+  if (command.kind === "cair") {
+    const cairKind = cairOperationKind(command);
+    await store.appendOperation({
+      sessionId,
+      actorId,
+      kind: cairKind,
+      summary: cairSummary(command, cairKind, exitCode),
+      data: {
+        subcommand: command.options.subcommand,
+        exitCode,
+        ...(command.options.query ? { queryVerb: compactCairVerb(command.options.query) } : {}),
+        ...(command.options.action ? { actionVerb: compactCairVerb(command.options.action) } : {}),
+        ...(command.options.inputPath ? { inputPath: command.options.inputPath } : {}),
+        dryRun: Boolean(command.options.dryRun),
+        plan: Boolean(command.options.plan),
+        allowGenerated: Boolean(command.options.allowGenerated),
+      },
+    });
+    return;
+  }
+
   if (command.kind === "check" || command.kind === "verify") {
     await store.appendOperation({
       sessionId,
@@ -276,6 +297,45 @@ async function recordSpecializedCommand(
   }
 }
 
+function cairOperationKind(command: Extract<ForgeCommand, { kind: "cair" }>): string {
+  if (command.options.subcommand === "snapshot") {
+    return "cair.snapshot.created";
+  }
+  if (command.options.subcommand === "query") {
+    return "cair.query.run";
+  }
+  const actionVerb = compactCairVerb(command.options.action ?? "");
+  if (command.options.plan) {
+    return "cair.plan.created";
+  }
+  if (actionVerb === "A APPLY") {
+    return "cair.plan.applied";
+  }
+  if (command.options.dryRun) {
+    return "cair.action.previewed";
+  }
+  return "cair.action.run";
+}
+
+function cairSummary(command: Extract<ForgeCommand, { kind: "cair" }>, kind: string, exitCode: number): string {
+  const suffix = exitCode === 0 ? "completed" : "failed";
+  if (command.options.subcommand === "query") {
+    return `CAIR query ${compactCairVerb(command.options.query ?? "")} ${suffix}`;
+  }
+  if (command.options.subcommand === "action") {
+    return `CAIR ${kind.replace(/^cair\./, "").replace(/\./g, " ")} ${compactCairVerb(command.options.action ?? "")} ${suffix}`;
+  }
+  return `CAIR snapshot ${suffix}`;
+}
+
+function compactCairVerb(input: string): string {
+  const parts = input.trim().split(/\s+/u).filter(Boolean);
+  if (parts.length === 0) {
+    return "unknown";
+  }
+  return parts.slice(0, 2).join(" ");
+}
+
 const noopRecorder: AmbientDeltaRecorder = {
   async recordRuntimeCall() {},
   async recordAgentTool() {},