forgeos 0.1.0-alpha.4 → 0.1.0-alpha.40

package/src/forge/agent-adapters/index.ts

@@ -4,6 +4,7 @@ import { createDiagnostic } from "../compiler/diagnostics/create.ts";
 import { GENERATED_DIR, GENERATOR_VERSION } from "../compiler/emitter/constants.ts";
 import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
 import { hashStable } from "../compiler/primitives/hash.ts";
+import { normalizePath } from "../compiler/primitives/paths.ts";
 import { serializeCanonical } from "../compiler/primitives/serialize.ts";
 import { secretLeakScan } from "../compiler/sandbox/secret-scan.ts";
 import type { Diagnostic } from "../compiler/types/diagnostic.ts";
@@ -27,19 +28,41 @@ import type {
   AgentDoctorResult,
   AgentExportFile,
   AgentExportResult,
+  AgentHooksSmokeResult,
+  AgentHooksStatusResult,
+  AgentOnboardResult,
   AgentPrintContextResult,
+  AgentPrepareResult,
+  AgentTimelineItem,
+  AgentTimelineResult,
   AgentTargetsResult,
   CustomAdapterConfig,
   AgentCheckResult,
 } from "./types.ts";
+import type { AgentMemoryEventRecord } from "../agent-memory/types.ts";
+import {
+  formatAgentMemoryHuman,
+  formatAgentMemoryJson,
+  inspectAgentMemoryQueueFile,
+  runAgentMemoryCommand,
+  type AgentMemoryCommandResult,
+} from "../agent-memory/bridge.ts";
+import {
+  compareHookForgeVersions,
+  inspectCodexHookCommands,
+  probeCodexHookRunner,
+  readCodexHookMeta,
+  resolveForgeOnPath,
+} from "../agent-memory/hook-runner.ts";
+import { releaseManifest } from "../_generated/releaseManifest.ts";
+import { runDevConsoleCycle } from "../dev-console/cycle.ts";
+import { normalizeForgeCliCommandsInValue } from "../workspace/forge-cli.ts";
 
 export const AGENT_ADAPTER_VERSION = "agent-adapter-0.1.0";
 export const AGENT_FORMAT_VERSION = "2026-06";
 
 const USER_START = "<!-- user-notes:start -->";
 const USER_END = "<!-- user-notes:end -->";
-const GENERATED_START = "<!-- forge-generated:start -->";
-const GENERATED_END = "<!-- forge-generated:end -->";
 const CUSTOM_ADAPTERS_DIR = ".forge/agent-adapters";
 
 function sorted(values: string[]): string[] {
@@ -55,6 +78,25 @@ function diagnostic(
   return createDiagnostic({ severity, code, message, ...(file ? { file } : {}) });
 }
 
+function normalizeAgentCliCommandHints<T>(workspaceRoot: string, result: T): T {
+  if (!result || typeof result !== "object") {
+    return result;
+  }
+  const value = result as Record<string, unknown>;
+  const normalized: Record<string, unknown> = { ...value };
+  for (const key of ["nextActions", "diagnostics", "commands", "checks", "steps"]) {
+    if (key in normalized) {
+      normalized[key] = normalizeForgeCliCommandsInValue(workspaceRoot, normalized[key], key);
+    }
+  }
+  for (const key of ["installResult", "ingestResult"]) {
+    if (key in normalized) {
+      normalized[key] = normalizeAgentCliCommandHints(workspaceRoot, normalized[key]);
+    }
+  }
+  return normalized as T;
+}
+
 function readText(workspaceRoot: string, relative: string): string | null {
   const path = join(workspaceRoot, relative);
   if (!nodeFileSystem.exists(path)) {
@@ -172,7 +214,7 @@ export function buildAgentContext(contract: AgentContract): AgentContext {
     },
     knownPitfalls: [
       "Do not edit src/forge/_generated/** directly.",
-      "Do not use process.env directly in app code.",
+      "Do not read secrets or server runtime config through process.env in Forge runtime code; public frontend bridge env is allowed.",
       "Do not import network packages in command/query/liveQuery.",
       "Preserve tenant isolation and policy declarations.",
       "Use forge make, forge feature, forge refactor, forge impact, and forge repair before hand-editing architecture.",
@@ -222,99 +264,6 @@ export function buildAgentDoneCriteria(): AgentDoneCriteria {
   };
 }
 
-function replaceGeneratedBlock(existing: string | null, generated: string, fallbackUserNotes: string): string {
-  const userBlock = extractUserBlock(existing) ?? `${USER_START}\n\n${fallbackUserNotes}\n\n${USER_END}`;
-  return `${GENERATED_START}\n${generated.trim()}\n${GENERATED_END}\n\n${userBlock.trim()}\n`;
-}
-
-function extractUserBlock(existing: string | null): string | null {
-  if (!existing) {
-    return null;
-  }
-  const start = existing.indexOf(USER_START);
-  const end = existing.indexOf(USER_END);
-  if (start === -1 || end === -1 || end < start) {
-    return null;
-  }
-  return existing.slice(start, end + USER_END.length);
-}
-
-function agentsMarkdown(contract: AgentContract, existing: string | null): string {
-  const context = buildAgentContext(contract);
-  const generated = `# AGENTS.md
-
-## Project Type
-
-This is a ForgeOS application.
-
-## Required Workflow
-
-Before editing:
-
-\`\`\`bash
-forge inspect all --json
-forge doctor --json
-\`\`\`
-
-During editing:
-
-\`\`\`bash
-forge impact --changed --json
-forge test plan --changed --json
-\`\`\`
-
-After editing:
-
-\`\`\`bash
-forge generate
-forge check
-forge verify --strict
-\`\`\`
-
-## Do Not
-
-- Do not edit \`src/forge/_generated/**\`.
-- Do not import network packages in \`command\`, \`query\`, or \`liveQuery\`.
-- Do not use \`process.env\` directly in app code.
-- Use \`ctx.secrets\`.
-- Do not bypass tenant isolation.
-- Do not call \`ctx.ai\` in \`command\`, \`query\`, or \`liveQuery\`.
-- Do not manually modify \`forge.lock\` unless instructed.
-
-## Runtime Model
-
-- \`command\`: ${context.runtimeModel.command}.
-- \`query\`: ${context.runtimeModel.query}.
-- \`liveQuery\`: ${context.runtimeModel.liveQuery}.
-- \`action\`: ${context.runtimeModel.action}.
-- \`workflow\`: ${context.runtimeModel.workflow}.
-
-## Common Commands
-
-\`\`\`bash
-forge make resource <name>
-forge feature plan <blueprint>
-forge refactor rename field <from> <to>
-forge impact --changed --json
-forge repair diagnose --from-last-test-run --json
-forge agent print-context --json
-\`\`\`
-
-## Agent Adapter Exports
-
-- Generic agents read \`.forge/agent/context.json\` and \`.forge/agent/playbooks/*.md\`.
-- Codex skills are generated under \`.codex/skills/**\`.
-- Cursor rules are generated under \`.cursor/rules/**\`.
-- Claude instructions are generated in \`CLAUDE.md\` and \`.claude/**\`.
-
-These files are derived from ForgeOS generated contracts. Regenerate them with:
-
-\`\`\`bash
-forge agent export --target all
-\`\`\``;
-  return `# AGENTS.md\n\n${replaceGeneratedBlock(existing, generated, "Project-specific human notes go here.")}`;
-}
-
 function playbook(title: string, steps: string[]): string {
   return `# Playbook: ${title}\n\n${steps.map((step, index) => `${index + 1}. ${step}`).join("\n")}\n`;
 }
@@ -322,7 +271,7 @@ function playbook(title: string, steps: string[]): string {
 function playbookFiles(): AgentExportFile[] {
   const books: Array<[string, string, string[]]> = [
     ["add-command.md", "Add Command", [
-      "Run `forge inspect all --json`.",
+      "Run `forge status --json`, `forge handoff --json`, and `forge agent print-context --json`.",
       "Prefer `forge make command <resource.action> --table <table> --policy <policy>`.",
       "Commands may write through `ctx.db` and emit with `ctx.emit`.",
       "Commands must not import network packages, use `ctx.secrets`, or call `ctx.ai`.",
@@ -378,7 +327,7 @@ function playbookFiles(): AgentExportFile[] {
       "Prefer targeted repairs and impacted tests before full verify.",
     ]],
     ["frontend-change.md", "Frontend Change", [
-      "Use generated client APIs and React hooks.",
+      "Use generated client APIs and framework bindings: React hooks or Vue composables.",
       "Do not import server adapters or server-only packages into client code.",
       "Preserve `ForgeError.traceId` in visible error states.",
       "Run affected frontend tests and `forge verify --changed`.",
@@ -395,9 +344,8 @@ function playbookFiles(): AgentExportFile[] {
   }));
 }
 
-function buildGenericFiles(contract: AgentContract, existingAgentsMd?: string | null): AgentExportFile[] {
+function buildGenericFiles(contract: AgentContract): AgentExportFile[] {
   return [
-    { path: "AGENTS.md", content: existingAgentsMd ?? agentsMarkdown(contract, null) },
     { path: ".forge/agent/context.json", content: renderJson(buildAgentContext(contract)) },
     { path: ".forge/agent/commands.json", content: renderJson(buildAgentCommandsMap()) },
     { path: ".forge/agent/done-criteria.json", content: renderJson(buildAgentDoneCriteria()) },
@@ -405,10 +353,25 @@ function buildGenericFiles(contract: AgentContract, existingAgentsMd?: string |
   ];
 }
 
+function buildGenericSupportFiles(contract: AgentContract): AgentExportFile[] {
+  return buildGenericFiles(contract);
+}
+
 function skill(name: string, description: string, body: string): string {
   return `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${description}\n\n${body.trim()}\n`;
 }
 
+function codexAgentRole(name: string, description: string, developerInstructions: string): string {
+  return [
+    `name = "forge-${name}"`,
+    `description = "${description}"`,
+    "developer_instructions = '''",
+    developerInstructions.trim(),
+    "'''",
+    "",
+  ].join("\n");
+}
+
 function buildCodexFiles(_contract: AgentContract, options: { skills: boolean }): AgentExportFile[] {
   if (!options.skills) {
     return [];
@@ -423,7 +386,7 @@ Rules:
 - Commands must not use \`ctx.secrets\` or \`ctx.ai\`.
 
 Steps:
-1. Run \`forge inspect all --json\`.
+1. Run \`forge status --json\`, \`forge handoff --json\`, and \`forge agent print-context --json\`.
 2. Prefer \`forge make command <resource.action> --table <table> --policy <policy>\`.
 3. Run \`forge generate\`, \`forge check\`, and \`forge verify --changed\`.
 4. Finish with \`forge verify --strict\`.
@@ -457,11 +420,45 @@ Prefer targeted checks before full verification.
     path: `.codex/skills/${name}/SKILL.md`,
     content: skill(name, description, body),
   }));
-  const agents = ["explorer", "worker", "reviewer", "security"].map((name) => ({
+  const agents: Array<[string, string, string]> = [
+    ["explorer", "Explore a ForgeOS app contract, routes, runtime entries, policies, and generated context before editing.", `
+You are the ForgeOS explorer role.
+
+Use ForgeOS inspection commands before reading broad file trees:
+- forge status --json
+- forge changed --json
+- forge agent print-context --json
+- forge inspect all --brief --json
+
+Explain the app shape, key runtime entries, frontend bindings, policies, generated files, and likely files to inspect next. Prefer concise findings with exact file paths. Do not modify files.
+`],
+    ["worker", "Implement ForgeOS app changes using generated contracts, playbooks, and verification commands.", `
+You are the ForgeOS worker role.
+
+Before editing, read the generated agent context and changed-file summary. Prefer ForgeOS primitives such as forge do, forge make, forge add, forge refactor, and forge repair when they fit. Keep authored changes separate from generated artifacts, never edit src/forge/_generated directly, and run forge generate plus focused checks after source changes.
+
+Return the implemented change, files touched, verification commands, and any remaining risks.
+`],
+    ["reviewer", "Review ForgeOS changes with focus on behavior, generated drift, policies, tests, and handoff readiness.", `
+You are the ForgeOS reviewer role.
+
+Start from forge changed --json and forge review run --changed --json. Review authored source, tests, docs, and config before generated artifacts. Look for runtime boundary violations, stale generated files, missing tests, tenant/auth mistakes, frontend binding drift, and unclear handoff state.
+
+Lead with findings ordered by severity and include file paths and commands that prove the issue.
+`],
+    ["security", "Audit ForgeOS security boundaries, secrets, tenant scope, policies, hooks, and agent memory surfaces.", `
+You are the ForgeOS security role.
+
+Focus on command/query/liveQuery/action/workflow boundaries, process.env usage, ctx.secrets placement, tenant isolation, policy coverage, generated RLS artifacts, hook trust, Agent Memory privacy, and AI tool approval risks. Use forge inspect policies --json, forge auth check --json, forge ai redteam --json, and forge changed --json when relevant.
+
+Report concrete risks, impacted files, exploit path if applicable, and the smallest safe fix.
+`],
+  ];
+  const agentFiles = agents.map(([name, description, instructions]) => ({
     path: `.codex/agents/forge-${name}.toml`,
-    content: `name = "forge-${name}"\ndescription = "ForgeOS ${name} helper generated from agentAdapterManifest."\n`,
+    content: codexAgentRole(name, description, instructions),
   }));
-  return [...files, ...agents];
+  return [...files, ...agentFiles];
 }
 
 function mdc(description: string, globs: string[], body: string): string {
@@ -511,7 +508,7 @@ function buildCursorFiles(_contract: AgentContract, options: { rules: boolean })
         `# ForgeOS Security Rules
 
 - Never include secret values in generated files, logs, or adapter exports.
-- Use \`ctx.secrets\`; do not read \`process.env\` directly in app code.
+- Use \`ctx.secrets\` or generated config context for runtime secrets/config; public frontend bridge env is allowed.
 - Preserve tenant-scoped reads and writes.
 - Run \`forge policy check --strict-policies\` after access changes.`,
       ),
@@ -541,8 +538,11 @@ This is a ForgeOS app.
 Start with:
 
 \`\`\`bash
-forge inspect all --json
-forge doctor --json
+forge status --json
+forge handoff --json
+forge dev --once --json
+forge agent print-context --json
+forge check --json
 \`\`\`
 
 After changes:
@@ -558,7 +558,7 @@ Critical rules:
 - Commands cannot use network packages, secrets, or AI.
 - Queries/liveQueries are read-only.
 - Use \`ctx.emit\` for side effects.
-- Use \`ctx.secrets\`, never \`process.env\`.
+- Use \`ctx.secrets\` or generated config context for runtime secrets/config; public frontend bridge env is allowed.
 `;
   return [
     { path: "CLAUDE.md", content: claude },
@@ -668,23 +668,22 @@ function builtFilesForTarget(
   target: AgentAdapterTarget,
   options: Pick<AgentCommandOptions, "skills" | "rules">,
 ): { files: AgentExportFile[]; diagnostics: Diagnostic[] } {
-  const existingAgentsMd = readText(workspaceRoot, "AGENTS.md");
   if (target === "generic") {
-    return { files: buildGenericFiles(contract, existingAgentsMd), diagnostics: [] };
+    return { files: buildGenericFiles(contract), diagnostics: [] };
   }
   if (target === "codex") {
-    return { files: [...buildGenericFiles(contract, existingAgentsMd), ...buildCodexFiles(contract, { skills: options.skills })], diagnostics: [] };
+    return { files: [...buildGenericSupportFiles(contract), ...buildCodexFiles(contract, { skills: options.skills })], diagnostics: [] };
   }
   if (target === "cursor") {
-    return { files: [...buildGenericFiles(contract, existingAgentsMd), ...buildCursorFiles(contract, { rules: options.rules })], diagnostics: [] };
+    return { files: [...buildGenericSupportFiles(contract), ...buildCursorFiles(contract, { rules: options.rules })], diagnostics: [] };
   }
   if (target === "claude") {
-    return { files: [...buildGenericFiles(contract, existingAgentsMd), ...buildClaudeFiles(contract)], diagnostics: [] };
+    return { files: [...buildGenericSupportFiles(contract), ...buildClaudeFiles(contract)], diagnostics: [] };
   }
   if (target === "all") {
     const byPath = new Map<string, AgentExportFile>();
     for (const file of [
-      ...buildGenericFiles(contract, existingAgentsMd),
+      ...buildGenericFiles(contract),
       ...buildCodexFiles(contract, { skills: options.skills }),
       ...buildCursorFiles(contract, { rules: options.rules }),
       ...buildClaudeFiles(contract),
@@ -831,10 +830,26 @@ export function runAgentCheck(options: AgentCommandOptions): AgentCheckResult {
   }
   const diag = [...built.diagnostics, ...validation];
   for (const file of stale) {
-    diag.push(diagnostic("error", FORGE_AGENT_STALE_EXPORT, `stale agent adapter export: ${file}`, file));
+    diag.push(createDiagnostic({
+      severity: "error",
+      code: FORGE_AGENT_STALE_EXPORT,
+      message: `stale agent adapter export: ${file}`,
+      file,
+      fixHint: `Regenerate the ${options.target} adapter export.`,
+      suggestedCommands: [`forge agent export --target ${options.target}`, "forge verify --strict"],
+      docs: ["src/forge/_generated/agentAdapterManifest.json", "AGENTS.md"],
+    }));
   }
   for (const file of missing) {
-    diag.push(diagnostic("error", FORGE_AGENT_STALE_EXPORT, `missing agent adapter export: ${file}`, file));
+    diag.push(createDiagnostic({
+      severity: "error",
+      code: FORGE_AGENT_STALE_EXPORT,
+      message: `missing agent adapter export: ${file}`,
+      file,
+      fixHint: `Generate the ${options.target} adapter export.`,
+      suggestedCommands: [`forge agent export --target ${options.target}`, "forge verify --strict"],
+      docs: ["src/forge/_generated/agentAdapterManifest.json", "AGENTS.md"],
+    }));
   }
   const ok = stale.length === 0 && missing.length === 0 && diag.every((item) => item.severity !== "error");
   return {
@@ -930,23 +945,1308 @@ export function runAgentClean(options: AgentCommandOptions): AgentExportResult {
   };
 }
 
-export function runAgentDoctor(options: AgentCommandOptions): AgentDoctorResult {
+function eventBindings(event: AgentMemoryEventRecord): Record<string, unknown> {
+  const data = event.data;
+  const bindings = data && typeof data === "object" && "bindings" in data
+    ? (data as { bindings?: unknown }).bindings
+    : undefined;
+  return bindings && typeof bindings === "object" && !Array.isArray(bindings)
+    ? bindings as Record<string, unknown>
+    : {};
+}
+
+function eventPayload(event: AgentMemoryEventRecord): Record<string, unknown> {
+  const data = event.data;
+  const envelope = data && typeof data === "object" && "envelope" in data
+    ? (data as { envelope?: unknown }).envelope
+    : undefined;
+  const payload = envelope && typeof envelope === "object" && "payload" in envelope
+    ? (envelope as { payload?: unknown }).payload
+    : undefined;
+  return payload && typeof payload === "object" && !Array.isArray(payload)
+    ? payload as Record<string, unknown>
+    : {};
+}
+
+function eventIsForgeHookCanary(event: AgentMemoryEventRecord): boolean {
+  return eventPayload(event).forgeHookCanary === "FORGE_HOOK_SMOKE_CANARY";
+}
+
+function eventIsForgeHookProbe(event: AgentMemoryEventRecord): boolean {
+  const payload = eventPayload(event);
+  return payload.forgeHookProbe === true ||
+    payload._parseError === true ||
+    payload._invalidPayload === true;
+}
+
+function eventHasUsefulSignal(event: AgentMemoryEventRecord): boolean {
+  const bindings = eventBindings(event);
+  const files = bindings.files;
+  const entries = bindings.entries;
+  const proofs = bindings.proofs;
+  return (
+    typeof bindings.toolName === "string" ||
+    typeof bindings.command === "string" ||
+    typeof bindings.status === "string" ||
+    (Array.isArray(files) && files.length > 0) ||
+    (Array.isArray(entries) && entries.length > 0) ||
+    (Array.isArray(proofs) && proofs.length > 0)
+  );
+}
+
+function eventIsNativeHookEvent(event: AgentMemoryEventRecord): boolean {
+  return (
+    !eventIsForgeHookCanary(event) &&
+    !eventIsForgeHookProbe(event) &&
+    event.integrationKind === "native-hook" &&
+    event.trustLevel === "direct-hook"
+  );
+}
+
+function hookApprovalStatusFor(
+  target: AgentAdapterTarget,
+  installed: boolean,
+  nativeSignals: number,
+  observableSignals = 0,
+  memoryReadable = true,
+): "not-required" | "waiting-for-user-trust" | "accepted" | "trusted" | "memory-unavailable" {
+  if (target !== "codex" || !installed) {
+    return "not-required";
+  }
+  if (!memoryReadable) {
+    return "memory-unavailable";
+  }
+  if (nativeSignals > 0) {
+    return "trusted";
+  }
+  return observableSignals > 0 ? "accepted" : "waiting-for-user-trust";
+}
+
+function hookNativeTrustStatusFor(
+  target: AgentAdapterTarget,
+  installed: boolean,
+  nativeSignals: number,
+  memoryReadable = true,
+): "not-required" | "waiting-for-native-signal" | "trusted" | "memory-unavailable" {
+  if (target !== "codex" || !installed) {
+    return "not-required";
+  }
+  if (!memoryReadable) {
+    return "memory-unavailable";
+  }
+  return nativeSignals > 0 ? "trusted" : "waiting-for-native-signal";
+}
+
+function codexHookApprovalMessage(
+  approvalStatus: ReturnType<typeof hookApprovalStatusFor>,
+  nativeTrustStatus: ReturnType<typeof hookNativeTrustStatusFor>,
+  canarySignals = 0,
+): string {
+  if (approvalStatus === "waiting-for-user-trust") {
+    if (canarySignals > 0) {
+      return "ForgeOS can see the Codex smoke canary; hook approval is accepted, but trusted native Codex signal proof is still pending";
+    }
+    return "ForgeOS has not seen a trusted native Codex hook signal yet; approve the Codex Desktop hook prompt if shown, then continue a Codex session in this workspace";
+  }
+  if (approvalStatus === "accepted" && nativeTrustStatus === "waiting-for-native-signal") {
+    return "Codex hook approval is accepted for local editing; ForgeOS is still waiting for a trusted native Codex signal for stronger provenance";
+  }
+  if (approvalStatus === "trusted") {
+    return "Codex Desktop hook trust is confirmed by a native hook signal";
+  }
+  if (approvalStatus === "memory-unavailable") {
+    return "Codex Desktop hook trust cannot be verified until Agent Memory is readable";
+  }
+  return "Codex Desktop hook trust is not required";
+}
+
+function hookApprovalNextActions(target: AgentAdapterTarget, canarySignals = 0): string[] {
+  if (target !== "codex") {
+    return [];
+  }
+  return canarySignals > 0
+    ? [
+        "Continue or send one Codex message in this workspace so a normal native hook event is emitted",
+        "If Codex Desktop shows a hook approval prompt, approve it",
+        `forge agent hooks status --target ${target} --json`,
+      ]
+    : [
+        "Approve the installed hooks in Codex Desktop (Confiar em tudo or Revisar hooks)",
+        "Start or continue a Codex session in this workspace so a native hook event is emitted",
+        `forge agent hooks status --target ${target} --json`,
+      ];
+}
+
+function inspectQueuedHookSignals(workspaceRoot: string, installTarget: string | null) {
+  if (installTarget !== "codex") {
+    return undefined;
+  }
+  return inspectAgentMemoryQueueFile({
+    workspaceRoot,
+    watchFile: join(workspaceRoot, ".forge", "agent", "events.ndjson"),
+    source: "codex",
+  });
+}
+
+function stringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string" && item.length > 0)
+    : [];
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function agentTimelineItem(event: AgentMemoryEventRecord): AgentTimelineItem {
+  const bindings = eventBindings(event);
+  return {
+    id: event.id,
+    source: event.sourceName,
+    integration: event.integrationKind,
+    trustLevel: event.trustLevel,
+    kind: event.normalizedKind,
+    capturedAt: event.capturedAt,
+    ...(event.externalSessionId ? { sessionId: event.externalSessionId } : {}),
+    ...(event.externalTurnId ? { turnId: event.externalTurnId } : {}),
+    ...(event.summary ? { summary: event.summary } : {}),
+    ...(stringValue(bindings.toolName) ? { toolName: stringValue(bindings.toolName) } : {}),
+    ...(stringValue(bindings.command) ? { command: stringValue(bindings.command) } : {}),
+    ...(stringValue(bindings.status) ? { status: stringValue(bindings.status) } : {}),
+    files: stringArray(bindings.files),
+    entries: stringArray(bindings.entries),
+    proofs: stringArray(bindings.proofs),
+    confidence: event.confidence,
+  };
+}
+
+function agentTimelineSourceFilter(target: AgentAdapterTarget): string | undefined {
+  if (!target || target === "all" || target === "generic") {
+    return undefined;
+  }
+  return agentMemorySourceForTarget(target);
+}
+
+export async function runAgentTimeline(options: AgentCommandOptions): Promise<AgentTimelineResult> {
+  const target = options.target || "all";
+  const sourceFilter = agentTimelineSourceFilter(target);
+  const requestedLimit = options.limit ?? 50;
+  const memoryResult = await runAgentMemoryCommand({
+    subcommand: "memory",
+    workspaceRoot: options.workspaceRoot,
+    json: true,
+    target: "generic",
+    source: "generic",
+    limit: sourceFilter ? 200 : requestedLimit,
+  });
+  if (!("events" in memoryResult) || memoryResult.ok === false) {
+    const diagnostics = "diagnostics" in memoryResult ? memoryResult.diagnostics ?? [] : [];
+    const nextActions = "nextActions" in memoryResult
+      ? memoryResult.nextActions ?? ["forge delta status --json"]
+      : ["forge delta status --json"];
+    return {
+      schemaVersion: "0.1.0",
+      ok: false,
+      timeline: "agent",
+      target,
+      ...(sourceFilter ? { sourceFilter } : {}),
+      summary: { events: 0, sessions: 0, files: 0, entries: 0, proofs: 0, tools: 0 },
+      events: [],
+      files: [],
+      entries: [],
+      proofs: [],
+      sessions: [],
+      nextActions,
+      diagnostics,
+      exitCode: 1,
+    };
+  }
+
+  const filtered = sourceFilter
+    ? memoryResult.events.filter((event) => event.sourceName === sourceFilter)
+    : memoryResult.events;
+  const events = filtered.slice(-requestedLimit).map(agentTimelineItem);
+  const files = sorted(events.flatMap((event) => event.files));
+  const entries = sorted(events.flatMap((event) => event.entries));
+  const proofs = sorted(events.flatMap((event) => event.proofs));
+  const sessions = sorted(events.flatMap((event) => event.sessionId ? [event.sessionId] : []));
+  const tools = sorted(events.flatMap((event) => event.toolName ? [event.toolName] : []));
+  return {
+    schemaVersion: "0.1.0",
+    ok: true,
+    timeline: "agent",
+    target,
+    ...(sourceFilter ? { sourceFilter } : {}),
+    summary: {
+      events: events.length,
+      sessions: sessions.length,
+      files: files.length,
+      entries: entries.length,
+      proofs: proofs.length,
+      tools: tools.length,
+      ...(events.at(-1)?.capturedAt ? { latestEventAt: events.at(-1)?.capturedAt } : {}),
+    },
+    events,
+    files,
+    entries,
+    proofs,
+    sessions,
+    nextActions: [
+      "forge agent context --current --json",
+      "forge changed --json",
+      "forge timeline --json --for-agent",
+    ],
+    diagnostics: [],
+    exitCode: 0,
+  };
+}
+
+function agentMemorySourceForTarget(target: AgentAdapterTarget): string {
+  if (target === "claude") return "claude-code";
+  if (target === "codex" || target === "cursor" || target === "claude-code") return target;
+  return String(target || "generic");
+}
+
+function hookInstallFilesPresent(workspaceRoot: string, installResult: unknown): {
+  planned: string[];
+  missing: string[];
+} {
+  const planned =
+    installResult &&
+    typeof installResult === "object" &&
+    "filesPlanned" in installResult &&
+    Array.isArray((installResult as { filesPlanned?: unknown }).filesPlanned)
+      ? ((installResult as { filesPlanned: unknown[] }).filesPlanned.filter((file): file is string => typeof file === "string"))
+      : [];
+  return {
+    planned,
+    missing: planned.filter((file) => !nodeFileSystem.exists(join(workspaceRoot, file))),
+  };
+}
+
+function lastAgentSignal(events: AgentMemoryEventRecord[]): AgentHooksStatusResult["lastSignal"] {
+  const event = events.at(-1);
+  return event
+    ? {
+        kind: event.normalizedKind,
+        ...(event.summary ? { summary: event.summary } : {}),
+        capturedAt: event.capturedAt,
+        ...(eventWorkspaceRoot(event) ? { workspaceRoot: eventWorkspaceRoot(event) } : {}),
+      }
+    : undefined;
+}
+
+function normalizeAgentWorkspaceRoot(value: unknown): string {
+  return normalizePath(String(value ?? "")).replace(/\/+$/, "").toLowerCase();
+}
+
+function eventWorkspaceRoot(event: AgentMemoryEventRecord): string | undefined {
+  const envelope = event.data?.envelope;
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+    return undefined;
+  }
+  const workspace = (envelope as { workspace?: unknown }).workspace;
+  if (!workspace || typeof workspace !== "object" || Array.isArray(workspace)) {
+    return undefined;
+  }
+  const root = (workspace as { root?: unknown }).root;
+  return typeof root === "string" && root.trim() ? root : undefined;
+}
+
+function eventBelongsToWorkspace(event: AgentMemoryEventRecord, workspaceRoot: string): boolean {
+  const root = eventWorkspaceRoot(event);
+  if (!root) {
+    return true;
+  }
+  return normalizeAgentWorkspaceRoot(root) === normalizeAgentWorkspaceRoot(workspaceRoot);
+}
+
+async function readHookMemoryStatus(
+  workspaceRoot: string,
+  source: string,
+  limit: number,
+): Promise<{
+  events: AgentMemoryEventRecord[];
+  diagnostics: Diagnostic[];
+  ignoredOutOfWorkspaceEvents: number;
+  workspaceRoot: string;
+}> {
+  const diagnostics: Diagnostic[] = [];
+  const memoryResult = await runAgentMemoryCommand({
+    subcommand: "memory",
+    workspaceRoot,
+    json: true,
+    target: source,
+    source,
+    entry: source,
+    limit,
+  }).catch((error: unknown) => {
+    diagnostics.push(diagnostic(
+      "error",
+      "FORGE_AGENT_MEMORY_UNAVAILABLE",
+      error instanceof Error ? error.message : "agent memory store is unavailable",
+    ));
+    return { ok: false as const, events: [], exitCode: 1 as const };
+  });
+  if (
+    memoryResult &&
+    typeof memoryResult === "object" &&
+    "diagnostics" in memoryResult &&
+    Array.isArray((memoryResult as { diagnostics?: unknown }).diagnostics)
+  ) {
+    diagnostics.push(...(memoryResult as { diagnostics: Diagnostic[] }).diagnostics);
+  }
+  const allEvents = "events" in memoryResult ? memoryResult.events ?? [] : [];
+  const events = allEvents.filter((event) => eventBelongsToWorkspace(event, workspaceRoot));
+  return {
+    events,
+    diagnostics,
+    ignoredOutOfWorkspaceEvents: allEvents.length - events.length,
+    workspaceRoot: normalizeAgentWorkspaceRoot(workspaceRoot),
+  };
+}
+
+async function readAgentHookStatus(options: AgentCommandOptions): Promise<AgentHooksStatusResult> {
+  const target = options.target || "codex";
+  const source = agentMemorySourceForTarget(target);
+  const installTarget = hookInstallTarget(target);
+  if (!installTarget) {
+    const diag = diagnostic(
+      "error",
+      "FORGE_AGENT_HOOK_TARGET_UNSUPPORTED",
+      `agent hooks supports codex, claude, and cursor targets; got ${target}`,
+    );
+    return {
+      ok: false,
+      target,
+      installed: false,
+      bridgeWritable: false,
+      deltaWritable: false,
+      visibleInMemory: false,
+      recentEvents: 0,
+      usefulSignals: 0,
+      nativeSignals: 0,
+      canarySignals: 0,
+      approvalRequired: false,
+      approvalStatus: "not-required",
+      nativeTrustStatus: "not-required",
+      checks: [{ name: "target", ok: false, message: diag.message }],
+      nextActions: ["forge agent list-targets --json"],
+      diagnostics: [diag],
+      exitCode: 1,
+    };
+  }
+
+  const installResult = await runAgentMemoryCommand({
+    subcommand: "install",
+    workspaceRoot: options.workspaceRoot,
+    json: options.json,
+    target: installTarget,
+    source: installTarget,
+    dryRun: true,
+    force: false,
+  });
+  const installOk =
+    typeof installResult === "object" && installResult !== null && "exitCode" in installResult
+      ? (installResult as { exitCode?: number }).exitCode === 0
+      : true;
+  const hookFiles = hookInstallFilesPresent(options.workspaceRoot, installResult);
+  const memory = await readHookMemoryStatus(options.workspaceRoot, source, options.limit ?? 25);
+  const queuedHooks = inspectQueuedHookSignals(options.workspaceRoot, installTarget);
+  const usefulEvents = memory.events.filter(eventHasUsefulSignal);
+  const nativeEvents = memory.events.filter(eventIsNativeHookEvent);
+  const canaryEvents = memory.events.filter(eventIsForgeHookCanary);
+  const installed = hookFiles.missing.length === 0;
+  const bridgeWritable = installOk;
+  const deltaWritable = memory.diagnostics.length === 0;
+  const visibleInMemory = memory.events.length > 0;
+  const queuedEvents = queuedHooks?.events ?? 0;
+  const usefulSignals = usefulEvents.length + (queuedHooks?.usefulSignals ?? 0);
+  const nativeSignals = nativeEvents.length + (queuedHooks?.nativeSignals ?? 0);
+  const canarySignals = canaryEvents.length + (queuedHooks?.canarySignals ?? 0);
+  const visibleHookSignals = visibleInMemory || queuedEvents > 0;
+  const observableSignals = Math.max(usefulSignals, canarySignals);
+  const approvalStatus = hookApprovalStatusFor(target, installed, nativeSignals, observableSignals, deltaWritable);
+  const nativeTrustStatus = hookNativeTrustStatusFor(target, installed, nativeSignals, deltaWritable);
+  const approvalRequired = approvalStatus === "waiting-for-user-trust";
+  const codexHookInspection = installTarget === "codex"
+    ? inspectCodexHookCommands(options.workspaceRoot)
+    : undefined;
+  const codexHookMeta = installTarget === "codex"
+    ? readCodexHookMeta(options.workspaceRoot)
+    : undefined;
+  const codexVersionMatch = installTarget === "codex"
+    ? compareHookForgeVersions(codexHookMeta ?? null)
+    : undefined;
+  const forgeOnPath = installTarget === "codex"
+    ? resolveForgeOnPath(options.workspaceRoot)
+    : undefined;
+  const usesLegacyForgeCli = codexHookInspection?.usesLegacyForgeCli === true;
+  const usesLightweightRunner = codexHookInspection?.usesLightweightRunner === true;
+  const hookCommandHealthy = installTarget !== "codex" || (usesLightweightRunner && !usesLegacyForgeCli);
+  const hookVersionHealthy = installTarget !== "codex" || !usesLightweightRunner || codexVersionMatch?.matches === true;
+  const ok = installed && bridgeWritable && deltaWritable && visibleHookSignals && usefulSignals > 0 && !approvalRequired && hookCommandHealthy && hookVersionHealthy;
+  const nextActions = ok
+    ? uniqueCommands([
+        ...(queuedEvents > 0 ? [`forge agent ingest ${source} --file .forge/agent/events.ndjson --json`] : []),
+        `forge agent memory --entry ${source} --json`,
+        `forge agent context --current --json`,
+      ])
+    : uniqueCommands([
+        ...(!installed ? [`forge agent install ${installTarget} --json`] : []),
+        ...(usesLegacyForgeCli ? [`forge agent install ${installTarget} --force --json`] : []),
+        ...(codexVersionMatch && !codexVersionMatch.matches ? [`forge agent install ${installTarget} --force --json`] : []),
+        ...(approvalRequired ? hookApprovalNextActions(target, canarySignals) : []),
+        ...(installed && deltaWritable && !visibleHookSignals ? [`forge agent hooks smoke --target ${target} --json`] : []),
+        ...(visibleHookSignals && usefulSignals === 0 ? [`forge agent ingest ${source} --event PostToolUse --json`] : []),
+        ...(!deltaWritable ? ["forge delta status --json", "forge delta repair --dry-run --json"] : []),
+        ...(queuedEvents > 0 ? [`forge agent ingest ${source} --file .forge/agent/events.ndjson --json`] : []),
+        ...(usesLightweightRunner ? [`forge agent ingest ${source} --watch --file .forge/agent/events.ndjson --json`] : []),
+      ]);
+
+  return {
+    ok,
+    target,
+    installTarget,
+    installed,
+    bridgeWritable,
+    deltaWritable,
+    visibleInMemory,
+    recentEvents: memory.events.length,
+    queuedEvents,
+    usefulSignals,
+    nativeSignals,
+    canarySignals,
+    approvalRequired,
+    approvalStatus,
+    nativeTrustStatus,
+    workspaceRoot: memory.workspaceRoot,
+    ignoredOutOfWorkspaceEvents: memory.ignoredOutOfWorkspaceEvents,
+    ...(lastAgentSignal(memory.events) ? { lastSignal: lastAgentSignal(memory.events) } : {}),
+    checks: [
+      {
+        name: "hook-bridge-installed",
+        ok: installed,
+        message: installed
+          ? `${installTarget} hook bridge files are present`
+          : `missing hook bridge files: ${hookFiles.missing.join(", ")}`,
+        evidence: { planned: hookFiles.planned, missing: hookFiles.missing },
+      },
+      {
+        name: "hook-bridge-installable",
+        ok: bridgeWritable,
+        message: bridgeWritable ? "hook bridge install plan is valid" : "hook bridge install failed",
+      },
+      {
+        name: "agent-memory-readable",
+        ok: deltaWritable,
+        message: deltaWritable ? "agent memory store is readable" : "agent memory store is unavailable",
+      },
+      {
+        name: "visible-in-memory",
+        ok: visibleHookSignals,
+        message: visibleInMemory
+          ? `${memory.events.length} recent ${source} events visible for this workspace`
+          : queuedEvents > 0
+            ? `${queuedEvents} queued ${source} hook event(s) visible for this workspace and waiting for ingest`
+          : memory.ignoredOutOfWorkspaceEvents > 0
+            ? `ignored ${memory.ignoredOutOfWorkspaceEvents} ${source} event(s) from other workspaces`
+            : "no hook events visible in memory yet",
+        evidence: {
+          workspaceRoot: memory.workspaceRoot,
+          ignoredOutOfWorkspaceEvents: memory.ignoredOutOfWorkspaceEvents,
+          queuedEvents,
+          queuedNativeSignals: queuedHooks?.nativeSignals ?? 0,
+          queuedCanarySignals: queuedHooks?.canarySignals ?? 0,
+          queuedLatestEventAt: queuedHooks?.latestEventAt,
+        },
+      },
+      {
+        name: "workspace-scope",
+        ok: true,
+        message: memory.ignoredOutOfWorkspaceEvents > 0
+          ? `ignored ${memory.ignoredOutOfWorkspaceEvents} out-of-workspace agent event(s)`
+          : "agent memory events are scoped to this workspace",
+        evidence: {
+          workspaceRoot: memory.workspaceRoot,
+          ignoredOutOfWorkspaceEvents: memory.ignoredOutOfWorkspaceEvents,
+        },
+      },
+      {
+        name: "useful-signals",
+        ok: usefulSignals > 0,
+        message: usefulSignals > 0
+          ? `${usefulSignals} events include useful tool, file, command, status, entry, or proof signals`
+          : "no useful tool, file, command, status, entry, or proof signals found",
+      },
+      {
+        name: "native-hook-signal",
+        ok: target !== "codex" || !deltaWritable || nativeSignals > 0 || approvalStatus === "accepted",
+        message: target !== "codex"
+          ? "native Codex hook approval is not required for this target"
+          : !deltaWritable
+            ? "trusted Codex native hook signals cannot be verified until Agent Memory is readable"
+          : nativeSignals > 0
+            ? `${nativeSignals} trusted Codex native hook signal(s) visible or queued`
+            : "hook approval is accepted, but Codex has not emitted a trusted native hook signal yet",
+        evidence: {
+          nativeSignals,
+          canarySignals,
+          queuedNativeSignals: queuedHooks?.nativeSignals ?? 0,
+          queuedCanarySignals: queuedHooks?.canarySignals ?? 0,
+          memoryReadable: deltaWritable,
+          nativeTrustStatus,
+          trustBoundary: target === "codex" ? "codex-desktop-hook-approval" : "not-required",
+        },
+      },
+      {
+        name: "codex-hook-approval",
+        ok: !approvalRequired && approvalStatus !== "memory-unavailable",
+        message: codexHookApprovalMessage(approvalStatus, nativeTrustStatus, canarySignals),
+        evidence: { approvalStatus, approvalRequired, nativeTrustStatus },
+      },
+      ...(installTarget === "codex"
+        ? [
+            {
+              name: "hook-runner-mode",
+              ok: hookCommandHealthy,
+              message: usesLegacyForgeCli
+                ? "Codex hooks still call full forge agent ingest; reinstall with forge agent install codex --force"
+                : usesLightweightRunner
+                  ? "Codex hooks use the lightweight workspace runner (.forge/agent/codex-hook.mjs)"
+                  : "Codex hook command mode is unknown; reinstall hooks",
+              evidence: codexHookInspection,
+            },
+            {
+              name: "hook-forge-version",
+              ok: hookVersionHealthy,
+              message: codexVersionMatch?.matches
+                ? `hook manifest matches runtime Forge ${releaseManifest.packageVersion}`
+                : codexVersionMatch?.installedVersion
+                  ? `hook manifest is ${codexVersionMatch.installedVersion}, runtime is ${codexVersionMatch.runtimeVersion}`
+                  : "hook manifest is missing; reinstall hooks to pin workspace runner version",
+              evidence: {
+                manifest: codexHookMeta,
+                runtimeVersion: releaseManifest.packageVersion,
+                forgeOnPath,
+              },
+            },
+            {
+              name: "hook-global-forge",
+              ok: !usesLegacyForgeCli,
+              message: usesLegacyForgeCli
+                ? `hooks call global/legacy forge CLI${forgeOnPath?.path ? ` (${forgeOnPath.path}${forgeOnPath.version ? ` ${forgeOnPath.version}` : ""})` : ""}`
+                : forgeOnPath
+                  ? `PATH forge resolves to ${forgeOnPath.path}${forgeOnPath.version ? ` (${forgeOnPath.version})` : ""}; hooks use workspace runner instead`
+                  : "hooks use workspace runner; no global forge resolution needed",
+              evidence: { forgeOnPath, usesLegacyForgeCli },
+            },
+          ]
+        : []),
+    ],
+    nextActions,
+    installResult,
+    diagnostics: [
+      ...memory.diagnostics,
+      ...(usesLegacyForgeCli
+        ? [createDiagnostic({
+            severity: "warning",
+            code: "FORGE_AGENT_HOOK_LEGACY_CLI",
+            message: "Codex hooks still spawn the full Forge CLI per event. Reinstall with forge agent install codex --force to use the lightweight queue runner.",
+            suggestedCommands: [`forge agent install ${installTarget} --force --json`, `forge agent hooks smoke --target ${target} --json`],
+          })]
+        : []),
+      ...(codexVersionMatch && !codexVersionMatch.matches
+        ? [createDiagnostic({
+            severity: "warning",
+            code: "FORGE_AGENT_HOOK_VERSION_MISMATCH",
+            message: `Installed Codex hook manifest is ${codexVersionMatch.installedVersion}, but this Forge runtime is ${codexVersionMatch.runtimeVersion}.`,
+            suggestedCommands: [`forge agent install ${installTarget} --force --json`],
+          })]
+        : []),
+    ],
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+export async function runAgentDoctor(options: AgentCommandOptions): Promise<AgentDoctorResult> {
+  const target = options.target || "generic";
   const check = runAgentCheck(options);
+  const source = agentMemorySourceForTarget(target);
+  const installTarget = hookInstallTarget(target);
+  const installResult = installTarget
+    ? await runAgentMemoryCommand({
+        subcommand: "install",
+        workspaceRoot: options.workspaceRoot,
+        json: options.json,
+        target: installTarget,
+        source: installTarget,
+        dryRun: true,
+        force: false,
+      })
+    : undefined;
+  const hookFiles = installTarget
+    ? hookInstallFilesPresent(options.workspaceRoot, installResult)
+    : { planned: [], missing: [] };
+  const memory = await readHookMemoryStatus(options.workspaceRoot, source, options.limit ?? 25);
+  const queuedHooks = inspectQueuedHookSignals(options.workspaceRoot, installTarget);
+  const memoryDiagnostics = memory.diagnostics;
+  const recentEvents = memory.events;
+  const usefulEvents = recentEvents.filter(eventHasUsefulSignal);
+  const nativeEvents = recentEvents.filter(eventIsNativeHookEvent);
+  const canaryEvents = recentEvents.filter(eventIsForgeHookCanary);
+  const queuedEvents = queuedHooks?.events ?? 0;
+  const visibleHookSignals = recentEvents.length > 0 || queuedEvents > 0;
+  const usefulSignals = usefulEvents.length + (queuedHooks?.usefulSignals ?? 0);
+  const nativeSignals = nativeEvents.length + (queuedHooks?.nativeSignals ?? 0);
+  const canarySignals = canaryEvents.length + (queuedHooks?.canarySignals ?? 0);
+  const adapterState = check.missing.length > 0 ? "missing" : check.stale.length > 0 ? "stale" : "ready";
+  const installed = !installTarget || hookFiles.missing.length === 0;
+  const memoryReadable = memoryDiagnostics.length === 0;
+  const observableSignals = Math.max(usefulSignals, canarySignals);
+  const approvalStatus = hookApprovalStatusFor(
+    target,
+    Boolean(installTarget && installed),
+    nativeSignals,
+    observableSignals,
+    memoryReadable,
+  );
+  const nativeTrustStatus = hookNativeTrustStatusFor(target, Boolean(installTarget && installed), nativeSignals, memoryReadable);
+  const approvalRequired = approvalStatus === "waiting-for-user-trust";
+  const hookBridgeState = !installTarget
+    ? "not-supported"
+    : !memoryReadable
+      ? "memory-unavailable"
+    : approvalRequired
+      ? "waiting-for-user-trust"
+      : hookFiles.missing.length === 0
+      ? "ready"
+      : "missing";
   const checks = [
-    { name: "AGENTS.md", ok: !check.missing.includes("AGENTS.md") },
+    {
+      name: "adapter-export",
+      ok: check.missing.length === 0 && check.stale.length === 0,
+      message: adapterState === "ready" ? "agent adapter exports are current" : `adapter exports are ${adapterState}`,
+      evidence: { missing: check.missing, stale: check.stale },
+    },
+    { name: "AGENTS.md", ok: readText(options.workspaceRoot, "AGENTS.md") !== null },
     { name: "agent-context", ok: !check.missing.includes(".forge/agent/context.json") },
     { name: "commands", ok: !check.missing.includes(".forge/agent/commands.json") },
     { name: "done-criteria", ok: !check.missing.includes(".forge/agent/done-criteria.json") },
-    { name: "stale-exports", ok: check.stale.length === 0, message: check.stale.join(", ") || undefined },
+    {
+      name: "hook-bridge",
+      ok: !installTarget || hookFiles.missing.length === 0,
+      message: !installTarget
+        ? "this target has no native hook bridge"
+        : hookFiles.missing.length === 0
+          ? `${installTarget} hook bridge files are present`
+          : `missing hook bridge files: ${hookFiles.missing.join(", ")}`,
+      evidence: { target: installTarget, planned: hookFiles.planned, missing: hookFiles.missing },
+    },
+    {
+      name: "recent-memory",
+      ok: (!installTarget || visibleHookSignals) && memoryDiagnostics.length === 0,
+      message: memoryDiagnostics.length > 0
+        ? "agent memory store is unavailable"
+        : recentEvents.length > 0
+        ? `${recentEvents.length} recent ${source} memory events for this workspace`
+        : queuedEvents > 0
+          ? `${queuedEvents} queued ${source} hook event(s) for this workspace are waiting for ingest`
+        : memory.ignoredOutOfWorkspaceEvents > 0
+          ? `ignored ${memory.ignoredOutOfWorkspaceEvents} ${source} event(s) from other workspaces`
+          : "no recent agent memory events found",
+      evidence: {
+        workspaceRoot: memory.workspaceRoot,
+        ignoredOutOfWorkspaceEvents: memory.ignoredOutOfWorkspaceEvents,
+        recent: recentEvents.slice(-5).map((event) => ({
+          kind: event.normalizedKind,
+          summary: event.summary,
+          capturedAt: event.capturedAt,
+          workspaceRoot: eventWorkspaceRoot(event),
+        })),
+        queuedEvents,
+        queuedNativeSignals: queuedHooks?.nativeSignals ?? 0,
+        queuedCanarySignals: queuedHooks?.canarySignals ?? 0,
+        queuedLatestEventAt: queuedHooks?.latestEventAt,
+      },
+    },
+    {
+      name: "workspace-scope",
+      ok: true,
+      message: memory.ignoredOutOfWorkspaceEvents > 0
+        ? `ignored ${memory.ignoredOutOfWorkspaceEvents} out-of-workspace agent event(s)`
+        : "agent memory events are scoped to this workspace",
+      evidence: {
+        workspaceRoot: memory.workspaceRoot,
+        ignoredOutOfWorkspaceEvents: memory.ignoredOutOfWorkspaceEvents,
+      },
+    },
+    {
+      name: "useful-signals",
+      ok: !installTarget || usefulSignals > 0,
+      message: usefulSignals > 0
+        ? `${usefulSignals} events include files, entries, commands, tools, status, or proofs`
+        : "events do not yet include useful files, entries, commands, tools, status, or proofs",
+    },
+    {
+      name: "native-hook-signal",
+      ok: !installTarget || target !== "codex" || !memoryReadable || nativeSignals > 0 || approvalStatus === "accepted",
+      message: !installTarget || target !== "codex"
+        ? "native Codex hook approval is not required for this target"
+        : !memoryReadable
+          ? "trusted Codex native hook signals cannot be verified until Agent Memory is readable"
+        : nativeSignals > 0
+          ? `${nativeSignals} trusted Codex native hook signal(s) visible or queued`
+          : "hook approval is accepted, but Codex has not emitted a trusted native hook signal yet",
+      evidence: {
+        nativeSignals,
+        canarySignals,
+        queuedNativeSignals: queuedHooks?.nativeSignals ?? 0,
+        queuedCanarySignals: queuedHooks?.canarySignals ?? 0,
+        memoryReadable,
+        nativeTrustStatus,
+        trustBoundary: target === "codex" ? "codex-desktop-hook-approval" : "not-required",
+      },
+    },
+    {
+      name: "codex-hook-approval",
+      ok: !approvalRequired && approvalStatus !== "memory-unavailable",
+      message: codexHookApprovalMessage(approvalStatus, nativeTrustStatus, canarySignals),
+      evidence: { approvalStatus, approvalRequired, nativeTrustStatus },
+    },
     { name: "secret-scan", ok: !check.diagnostics.some((diag) => diag.code === FORGE_AGENT_SECRET_LEAK) },
   ];
   const ok = checks.every((item) => item.ok) && check.exitCode === 0;
-  return { ok, checks, diagnostics: check.diagnostics, exitCode: ok ? 0 : 1 };
+  const nextActions = ok
+    ? [
+        `forge agent context --current --json`,
+        `forge agent memory --entry ${source} --json`,
+      ]
+    : [
+        ...(check.missing.length > 0 || check.stale.length > 0 ? [`forge agent export --target ${target}`] : []),
+        ...(installTarget && hookFiles.missing.length > 0 ? [`forge agent install ${installTarget} --json`] : []),
+        ...(approvalRequired ? hookApprovalNextActions(target, canarySignals) : []),
+        ...(memoryDiagnostics.length > 0 ? ["forge delta status --json", "forge delta repair --dry-run --json"] : []),
+        ...(installTarget && !visibleHookSignals && memoryDiagnostics.length === 0 ? [`forge agent hooks smoke --target ${target} --json`] : []),
+        ...(installTarget && visibleHookSignals && usefulSignals === 0 ? [`forge agent ingest ${source} --event PostToolUse --json`] : []),
+        ...(queuedEvents > 0 ? [`forge agent ingest ${source} --file .forge/agent/events.ndjson --json`] : []),
+      ];
+  return {
+    ok,
+    target,
+    summary: {
+      adapter: adapterState,
+      hookBridge: hookBridgeState,
+      approvalRequired,
+      approvalStatus,
+      nativeTrustStatus,
+      recentEvents: recentEvents.length,
+      queuedEvents,
+      usefulSignals,
+      nativeSignals,
+      canarySignals,
+      ...(recentEvents.at(-1)?.capturedAt || queuedHooks?.latestEventAt
+        ? { lastEventAt: queuedHooks?.latestEventAt ?? recentEvents.at(-1)?.capturedAt }
+        : {}),
+    },
+    checks,
+    nextActions,
+    diagnostics: [...check.diagnostics, ...memoryDiagnostics],
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+function hookInstallTarget(target: AgentAdapterTarget): string | null {
+  if (target === "codex") return "codex";
+  if (target === "claude") return "claude-code";
+  if (target === "cursor") return "cursor";
+  return null;
+}
+
+function openCommandForTarget(target: AgentAdapterTarget): string | undefined {
+  if (target === "codex") return "codex";
+  if (target === "claude") return "claude";
+  if (target === "cursor") return "cursor .";
+  return undefined;
+}
+
+function agentCommandHints(target: AgentAdapterTarget): AgentPrepareResult["commands"] {
+  const installTarget = hookInstallTarget(target);
+  return {
+    context: "forge agent context --current --json",
+    export: `forge agent export --target ${target}`,
+    check: `forge agent check --target ${target} --json`,
+    ...(installTarget ? { install: `forge agent install ${installTarget} --json` } : {}),
+    ...(installTarget ? { hooksStatus: `forge agent hooks status --target ${target} --json` } : {}),
+    ...(installTarget ? { hooksSmoke: `forge agent hooks smoke --target ${target} --json` } : {}),
+    ...(openCommandForTarget(target) ? { open: openCommandForTarget(target) } : {}),
+  };
+}
+
+export async function runAgentPrepare(options: AgentCommandOptions): Promise<AgentPrepareResult> {
+  const target = options.target || "generic";
+  const exportResult = runAgentExport({ ...options, target });
+  const installTarget = hookInstallTarget(target);
+  const installResult = installTarget
+    ? await runAgentMemoryCommand({
+        subcommand: "install",
+        workspaceRoot: options.workspaceRoot,
+        json: options.json,
+        target: installTarget,
+        source: installTarget,
+        dryRun: options.dryRun,
+        force: options.force,
+      })
+    : undefined;
+  const checkResult = runAgentCheck({ ...options, target });
+  const diagnostics = [
+    ...exportResult.diagnostics,
+    ...checkResult.diagnostics,
+  ];
+  const installOk =
+    !installResult ||
+    (typeof installResult === "object" && installResult !== null && "exitCode" in installResult
+      ? (installResult as { exitCode?: number }).exitCode === 0
+      : true);
+  const ok = exportResult.ok && checkResult.ok && installOk;
+  return {
+    ok,
+    target,
+    exportResult,
+    checkResult,
+    ...(installResult ? { installResult } : {}),
+    commands: agentCommandHints(target),
+    diagnostics,
+    exitCode: ok ? 0 : 1,
+  };
+}
+
+function uniqueCommands(commands: Array<string | undefined>): string[] {
+  return [...new Set(commands.filter((command): command is string => Boolean(command)))];
+}
+
+export async function runAgentOnboard(options: AgentCommandOptions): Promise<AgentOnboardResult> {
+  const target = options.target || "codex";
+  const installTarget = hookInstallTarget(target);
+  const initialContext = runAgentPrintContext(options.workspaceRoot);
+  const preflightDev = initialContext.context === null
+    ? await runDevConsoleCycle({
+        workspaceRoot: options.workspaceRoot,
+        mode: "once",
+        strictSecrets: false,
+        includeImpact: false,
+      })
+    : undefined;
+  const prepare = await runAgentPrepare({ ...options, target });
+  const hookSmoke = installTarget && !options.dryRun
+    ? await runAgentHooksSmoke({ ...options, target, subcommand: "hooks", hookAction: "smoke" })
+    : undefined;
+  const doctor = await runAgentDoctor({ ...options, target, subcommand: "doctor" });
+  const context = runAgentPrintContext(options.workspaceRoot);
+  const dev = await runDevConsoleCycle({
+    workspaceRoot: options.workspaceRoot,
+    mode: "once",
+    strictSecrets: true,
+    includeImpact: true,
+  });
+  const agentContext = dev.summary.agentContext;
+  const diagnostics = [
+    ...(preflightDev?.ok ? [] : initialContext.diagnostics),
+    ...(preflightDev?.diagnostics ?? []),
+    ...prepare.diagnostics,
+    ...(hookSmoke?.diagnostics ?? []),
+    ...doctor.diagnostics,
+    ...context.diagnostics,
+    ...dev.diagnostics,
+  ];
+  const readyToEdit =
+    prepare.ok &&
+    context.context !== null &&
+    dev.ok &&
+    agentContext.safeToEdit &&
+    (!hookSmoke || hookSmoke.ok) &&
+    doctor.summary.adapter === "ready" &&
+    !doctor.summary.approvalRequired;
+  const steps = [
+    ...(preflightDev
+      ? [{
+          name: "generated-preflight",
+          ok: preflightDev.ok,
+          message: preflightDev.ok
+            ? "generated context was created before adapter preparation"
+            : "generated context preflight failed",
+        }]
+      : []),
+    {
+      name: "adapter-prepare",
+      ok: prepare.ok,
+      message: prepare.ok
+        ? `${target} adapter files are present and current`
+        : `${target} adapter files need attention`,
+    },
+    ...(hookSmoke
+      ? [{
+          name: "hook-smoke",
+          ok: hookSmoke.ok,
+          message: hookSmoke.approvalRequired
+            ? `${target} hook files are installed, but no accepted hook signal is visible yet`
+            : hookSmoke.ok
+              ? `${target} hooks recorded a useful canary signal`
+              : `${target} hooks did not prove memory visibility`,
+        }]
+      : [{
+          name: "hook-smoke",
+          ok: !installTarget,
+          message: installTarget
+            ? "hook smoke skipped because this was a dry run"
+            : "this target has no native hook bridge",
+        }]),
+    ...(installTarget
+      ? [{
+          name: "hook-approval",
+          ok: !doctor.summary.approvalRequired,
+          message: doctor.summary.approvalRequired
+            ? "approve the installed hooks in Codex Desktop if prompted, then continue or start a Codex session in this workspace"
+            : doctor.summary.approvalStatus === "memory-unavailable"
+              ? "Codex hook trust cannot be verified until Agent Memory is readable"
+            : doctor.summary.approvalStatus === "trusted"
+              ? "Codex hook trust is confirmed by a native hook signal"
+            : doctor.summary.approvalStatus === "accepted"
+              ? "Codex hook approval is accepted; trusted native signal proof is still pending"
+              : "hook approval is not required for this target",
+        }]
+      : []),
+    {
+      name: "agent-doctor",
+      ok: doctor.ok,
+      message: doctor.ok ? "adapter, hooks, and memory are ready" : "agent doctor found follow-up actions",
+    },
+    {
+      name: "dev-snapshot",
+      ok: dev.ok && agentContext.safeToEdit,
+      message: dev.ok
+        ? `safeToEdit=${agentContext.safeToEdit}; generatedFresh=${agentContext.generatedFresh}; generatedChangedFiles=${agentContext.generatedChangedFiles}; changedFiles=${agentContext.changedFiles}`
+        : "dev snapshot found blocking diagnostics",
+    },
+    {
+      name: "context",
+      ok: context.context !== null,
+      message: context.context ? "generated agent context is readable" : "generated agent context is missing",
+    },
+  ];
+  const commandHints = agentCommandHints(target);
+  const nextActions = readyToEdit
+    ? uniqueCommands([
+        commandHints.open,
+        "forge changed --json",
+        "forge agent context --current --json",
+        "forge do verify --json",
+      ])
+    : uniqueCommands([
+        ...doctor.nextActions,
+        ...dev.nextActions.map((action) => action.command),
+        ...(context.context ? [] : ["forge generate"]),
+        "forge dev --once --json",
+      ]);
+  return {
+    schemaVersion: "0.1.0",
+    ok: readyToEdit,
+    target,
+    readyToEdit,
+    summary: {
+      adapter: doctor.summary.adapter,
+      hookBridge: doctor.summary.hookBridge,
+      approvalRequired: doctor.summary.approvalRequired,
+      approvalStatus: doctor.summary.approvalStatus,
+      nativeTrustStatus: doctor.summary.nativeTrustStatus,
+      memorySignals: doctor.summary.usefulSignals,
+      nativeSignals: doctor.summary.nativeSignals,
+      canarySignals: doctor.summary.canarySignals,
+      generatedFresh: agentContext.generatedFresh,
+      generatedChanged: agentContext.generatedChanged,
+      generatedChangedFiles: agentContext.generatedChangedFiles,
+      safeToEdit: agentContext.safeToEdit,
+      changedFiles: agentContext.changedFiles,
+      ...(dev.summary.primaryAction?.command ? { primaryAction: dev.summary.primaryAction.command } : {}),
+    },
+    steps,
+    recommendedReadFiles: agentContext.recommendedReadFiles,
+    commands: {
+      changed: "forge changed --json",
+      dev: "forge dev --once --json",
+      context: "forge agent context --current --json",
+      verify: "forge do verify --json",
+      ...(commandHints.hooksStatus ? { hooksStatus: commandHints.hooksStatus } : {}),
+      ...(commandHints.hooksSmoke ? { hooksSmoke: commandHints.hooksSmoke } : {}),
+      ...(commandHints.open ? { open: commandHints.open } : {}),
+    },
+    nextActions,
+    diagnostics,
+    exitCode: readyToEdit ? 0 : 1,
+  };
+}
+
+export async function runAgentHooksStatus(options: AgentCommandOptions): Promise<AgentHooksStatusResult> {
+  return readAgentHookStatus(options);
 }
 
-export async function runAgentCommand(options: AgentCommandOptions): Promise<
-  AgentExportResult | AgentCheckResult | AgentTargetsResult | AgentPrintContextResult | AgentDoctorResult
-> {
+export async function runAgentHooksSmoke(options: AgentCommandOptions): Promise<AgentHooksSmokeResult> {
+  const target = options.target || "codex";
+  const installTarget = hookInstallTarget(target);
+  const source = agentMemorySourceForTarget(target);
+  const canaryMarker = "FORGE_HOOK_SMOKE_CANARY";
+  if (!installTarget) {
+    const diag = diagnostic(
+      "error",
+      "FORGE_AGENT_HOOK_TARGET_UNSUPPORTED",
+      `agent hook smoke supports codex, claude, and cursor targets; got ${target}`,
+    );
+    return {
+      ok: false,
+      target,
+      smokeReady: false,
+      trustedNativeReady: false,
+      readinessLevel: "none",
+      installed: false,
+      bridgeWritable: false,
+      deltaWritable: false,
+      visibleInMemory: false,
+      usefulSignals: 0,
+      nativeSignals: 0,
+      canarySignals: 0,
+      approvalRequired: false,
+      approvalStatus: "not-required",
+      nativeTrustStatus: "not-required",
+      checks: [{ name: "target", ok: false, message: diag.message }],
+      nextActions: ["forge agent list-targets --json"],
+      diagnostics: [diag],
+      exitCode: 1,
+    };
+  }
+
+  const installResult = await runAgentMemoryCommand({
+    subcommand: "install",
+    workspaceRoot: options.workspaceRoot,
+    json: options.json,
+    target: installTarget,
+    source: installTarget,
+    dryRun: options.dryRun,
+    force: options.force,
+  });
+  const installOk =
+    typeof installResult === "object" && installResult !== null && "exitCode" in installResult
+      ? (installResult as { exitCode?: number }).exitCode === 0
+      : true;
+
+  const ingestResult = options.dryRun
+    ? undefined
+    : await runAgentMemoryCommand({
+        subcommand: "ingest",
+        workspaceRoot: options.workspaceRoot,
+        json: options.json,
+        target: installTarget,
+        source: installTarget,
+        eventName: installTarget === "cursor" ? "FileChange" : "SessionStart",
+        input: {
+          forgeHookCanary: canaryMarker,
+          cwd: options.workspaceRoot,
+          provider: installTarget,
+          status: "completed",
+          summary: "Forge hook smoke event recorded",
+          filesChanged: ["AGENTS.md"],
+          command: "forge agent hooks smoke",
+        },
+      });
+  const ingestOk =
+    options.dryRun ||
+    (typeof ingestResult === "object" && ingestResult !== null && "exitCode" in ingestResult
+      ? (ingestResult as { exitCode?: number }).exitCode === 0
+      : false);
+  const ingestDiagnostics =
+    ingestResult &&
+    typeof ingestResult === "object" &&
+    "diagnostics" in ingestResult &&
+    Array.isArray((ingestResult as { diagnostics?: unknown }).diagnostics)
+      ? (ingestResult as { diagnostics: Diagnostic[] }).diagnostics
+      : [];
+  const ingestNextActions =
+    ingestResult &&
+    typeof ingestResult === "object" &&
+    "nextActions" in ingestResult &&
+    Array.isArray((ingestResult as { nextActions?: unknown }).nextActions)
+      ? (ingestResult as { nextActions: unknown[] }).nextActions.filter((action): action is string => typeof action === "string")
+      : [];
+  const ingestStoreBusy = ingestDiagnostics.some((diag) => diag.code === "FORGE_DELTA_BUSY");
+  const hookRunnerProbe = installTarget === "codex" && !options.dryRun
+    ? await probeCodexHookRunner(options.workspaceRoot, { maxDurationMs: 5000, stdinHangBudgetMs: 3000 })
+    : undefined;
+  const ingestedEventId =
+    ingestResult &&
+    typeof ingestResult === "object" &&
+    "event" in ingestResult &&
+    (ingestResult as { event?: { id?: string } }).event?.id;
+  const memoryAfterSmoke = options.dryRun
+    ? { events: [], diagnostics: [] as Diagnostic[] }
+    : await readHookMemoryStatus(options.workspaceRoot, source, Math.max(options.limit ?? 25, 50));
+  const status = await readAgentHookStatus({ ...options, target });
+  const canaryEvent = ingestedEventId
+    ? memoryAfterSmoke.events.find((event) => event.id === ingestedEventId)
+    : undefined;
+  const visibleInMemory = options.dryRun
+    ? false
+    : Boolean(canaryEvent);
+  const checks = [
+    { name: "hook-install", ok: installOk, message: installOk ? "hook bridge files are available" : "hook bridge install failed" },
+    { name: "canary-ingest", ok: ingestOk, message: options.dryRun ? "dry-run skipped ingest" : ingestOk ? "canary event was normalized and stored" : "canary ingest failed" },
+    {
+      name: "canary-memory-readable",
+      ok: options.dryRun || memoryAfterSmoke.diagnostics.length === 0,
+      message: options.dryRun
+        ? "dry-run skipped memory read"
+        : memoryAfterSmoke.diagnostics.length === 0
+          ? `${memoryAfterSmoke.events.length} memory event(s) inspected after canary ingest`
+          : "agent memory was not readable after canary ingest",
+    },
+    {
+      name: "canary-visible",
+      ok: options.dryRun || !ingestOk || visibleInMemory,
+      message: options.dryRun
+        ? "dry-run skipped memory visibility check"
+        : !ingestOk
+          ? "not checked because canary ingest failed"
+        : visibleInMemory
+          ? "canary event is visible in agent memory"
+          : "canary event was not visible in agent memory",
+    },
+    {
+      name: "codex-hook-approval",
+      ok: status.approvalStatus !== "memory-unavailable",
+      message: codexHookApprovalMessage(status.approvalStatus, status.nativeTrustStatus, status.canarySignals),
+    },
+    ...(installTarget === "codex"
+      ? [
+          {
+            name: "hook-runner-latency",
+            ok: options.dryRun || hookRunnerProbe?.ok === true,
+            message: options.dryRun
+              ? "dry-run skipped hook runner latency probe"
+              : hookRunnerProbe?.ok
+                ? `lightweight hook runner exited in ${hookRunnerProbe.durationMs}ms and queued NDJSON`
+                : hookRunnerProbe?.error ?? "hook runner latency probe failed",
+          },
+          {
+            name: "hook-stdin-hang-safe",
+            ok: options.dryRun || hookRunnerProbe?.stdinHangSafe === true,
+            message: options.dryRun
+              ? "dry-run skipped stdin hang probe"
+              : hookRunnerProbe?.stdinHangSafe
+                ? `hook runner exited without waiting for stdin EOF (${hookRunnerProbe.stdinHangDurationMs ?? 0}ms)`
+                : "hook runner may hang when stdin never closes",
+          },
+        ]
+      : []),
+  ];
+  const diagnostics = [
+    ...ingestDiagnostics,
+    ...memoryAfterSmoke.diagnostics,
+    ...(!installOk
+      ? [diagnostic("error", "FORGE_AGENT_HOOK_INSTALL_FAILED", `hook bridge install failed for ${installTarget}`)]
+      : []),
+    ...(!ingestOk && !ingestStoreBusy
+      ? [diagnostic(
+          "error",
+          "FORGE_AGENT_HOOK_CANARY_MISSING",
+          `Forge hook smoke did not record a canary event for ${installTarget}; install hooks and restart the external agent, then run forge agent hooks smoke --target ${target} --json`,
+        )]
+      : []),
+    ...(!options.dryRun && ingestOk && !visibleInMemory
+      ? [createDiagnostic({
+          severity: "error",
+          code: "FORGE_AGENT_HOOK_CANARY_NOT_VISIBLE",
+          message: `Forge hook smoke ingested canary ${ingestedEventId ?? canaryMarker} for ${installTarget}, but that event was not visible in agent memory; inspect hook status and DeltaDB before trusting hooks.`,
+          suggestedCommands: [`forge agent hooks status --target ${target} --json`, `forge agent memory --entry ${source} --json`, "forge delta status --json"],
+        })]
+      : []),
+    ...(status.approvalRequired
+      ? [createDiagnostic({
+          severity: "warning",
+          code: "FORGE_AGENT_HOOK_APPROVAL_REQUIRED",
+          message: "Codex Desktop hook approval is still pending because ForgeOS has not seen a canary, useful hook event, or trusted native hook signal yet. Approve the hook prompt if Codex shows one, then continue a Codex session in this workspace.",
+          suggestedCommands: hookApprovalNextActions(target, status.canarySignals),
+        })]
+      : []),
+    ...(hookRunnerProbe && !hookRunnerProbe.ok
+      ? [createDiagnostic({
+          severity: "error",
+          code: "FORGE_AGENT_HOOK_RUNNER_SLOW",
+          message: hookRunnerProbe.error ?? `Codex hook runner probe failed after ${hookRunnerProbe.durationMs}ms`,
+          suggestedCommands: [`forge agent install ${installTarget} --force --json`, `forge agent hooks status --target ${target} --json`],
+        })]
+      : []),
+  ];
+  const smokeReady = checks.every((check) => check.ok);
+  const trustedNativeReady =
+    status.approvalStatus === "trusted" || status.approvalStatus === "not-required";
+  const readinessLevel = trustedNativeReady
+    ? "trusted-native"
+    : smokeReady
+      ? "canary"
+      : "none";
+  return {
+    ok: smokeReady,
+    target,
+    installTarget,
+    smokeReady,
+    trustedNativeReady,
+    readinessLevel,
+    installed: status.installed,
+    bridgeWritable: installOk,
+    deltaWritable: status.deltaWritable && ingestOk && memoryAfterSmoke.diagnostics.length === 0,
+    visibleInMemory,
+    usefulSignals: status.usefulSignals,
+    nativeSignals: status.nativeSignals,
+    canarySignals: status.canarySignals,
+    approvalRequired: status.approvalRequired,
+    approvalStatus: status.approvalStatus,
+    nativeTrustStatus: status.nativeTrustStatus,
+    ...(canaryEvent ? { lastSignal: lastAgentSignal([canaryEvent]) } : status.lastSignal ? { lastSignal: status.lastSignal } : {}),
+    ...(hookRunnerProbe ? { hookRunnerProbe } : {}),
+    canary: {
+      marker: canaryMarker,
+      source,
+      eventName: installTarget === "cursor" ? "FileChange" : "SessionStart",
+      ...(ingestedEventId ? { ingestedEventId } : {}),
+      memoryEventsChecked: memoryAfterSmoke.events.length,
+      visible: visibleInMemory,
+    },
+    checks,
+    nextActions: smokeReady
+      ? uniqueCommands([
+          ...(status.approvalRequired ? hookApprovalNextActions(target, status.canarySignals) : []),
+          `forge agent hooks status --target ${target} --json`,
+          `forge agent memory --entry ${source} --json`,
+        ])
+      : uniqueCommands([
+          ...ingestNextActions,
+          ...(status.approvalRequired ? hookApprovalNextActions(target, status.canarySignals) : []),
+          ...status.nextActions,
+          `forge agent hooks status --target ${target} --json`,
+          `forge agent memory --entry ${source} --json`,
+          `forge agent timeline --target ${target} --json`,
+          "forge delta status --json",
+        ]),
+    installResult,
+    ...(ingestResult ? { ingestResult } : {}),
+    diagnostics,
+    exitCode: smokeReady ? 0 : 1,
+  };
+}
+
+type AgentCommandResult =
+  AgentExportResult | AgentCheckResult | AgentTargetsResult | AgentPrintContextResult | AgentDoctorResult | AgentPrepareResult | AgentOnboardResult | AgentHooksSmokeResult | AgentHooksStatusResult | AgentTimelineResult | AgentMemoryCommandResult
+;
+
+async function runAgentCommandRaw(options: AgentCommandOptions): Promise<AgentCommandResult> {
   if (options.subcommand === "list-targets") {
     return runAgentListTargets(options.workspaceRoot);
   }
@@ -959,12 +2259,51 @@ export async function runAgentCommand(options: AgentCommandOptions): Promise<
   if (options.subcommand === "doctor") {
     return runAgentDoctor({ ...options, target: options.target || "generic" });
   }
+  if (options.subcommand === "onboard") {
+    return runAgentOnboard({ ...options, target: options.target || "codex" });
+  }
   if (options.subcommand === "print-context") {
     return runAgentPrintContext(options.workspaceRoot);
   }
   if (options.subcommand === "clean") {
     return runAgentClean(options);
   }
+  if (options.subcommand === "prepare") {
+    return runAgentPrepare(options);
+  }
+  if (options.subcommand === "hooks") {
+    if (options.hookAction === "status") {
+      return runAgentHooksStatus(options);
+    }
+    return runAgentHooksSmoke(options);
+  }
+  if (options.subcommand === "timeline") {
+    return runAgentTimeline(options);
+  }
+  if (
+    options.subcommand === "install" ||
+    options.subcommand === "ingest" ||
+    options.subcommand === "context" ||
+    options.subcommand === "memory"
+  ) {
+    return runAgentMemoryCommand({
+      subcommand: options.subcommand,
+      workspaceRoot: options.workspaceRoot,
+      json: options.json,
+      target: options.target,
+      source: options.target,
+      eventName: options.eventName,
+      input: options.input,
+      entry: options.entry,
+      current: options.current,
+      dryRun: options.dryRun,
+      force: options.force,
+      limit: options.limit,
+      watch: options.watch,
+      file: options.file,
+      pollIntervalMs: options.pollIntervalMs,
+    });
+  }
   return {
     ok: false,
     target: options.target,
@@ -978,19 +2317,138 @@ export async function runAgentCommand(options: AgentCommandOptions): Promise<
   };
 }
 
+export async function runAgentCommand(options: AgentCommandOptions): Promise<AgentCommandResult> {
+  return normalizeAgentCliCommandHints(options.workspaceRoot, await runAgentCommandRaw(options));
+}
+
 export function formatAgentJson(result: Awaited<ReturnType<typeof runAgentCommand>>): string {
+  if ("timeline" in result && result.timeline === "agent") {
+    return `${JSON.stringify(result, null, 2)}\n`;
+  }
+  if ("privacy" in result || "event" in result || "agentMemory" in result || "events" in result || "watch" in result) {
+    return formatAgentMemoryJson(result as AgentMemoryCommandResult);
+  }
   return `${JSON.stringify(result, null, 2)}\n`;
 }
 
 export function formatAgentHuman(result: Awaited<ReturnType<typeof runAgentCommand>>): string {
+  if ("timeline" in result && result.timeline === "agent") {
+    return [
+      `agent timeline for ${result.target}: ${result.summary.events} event(s)`,
+      ...(result.summary.latestEventAt ? [`latest: ${result.summary.latestEventAt}`] : []),
+      ...(result.files.length > 0 ? [`files: ${result.files.slice(0, 8).join(", ")}`] : []),
+      ...(result.entries.length > 0 ? [`entries: ${result.entries.slice(0, 8).join(", ")}`] : []),
+      "",
+      ...result.events.slice(-12).map((event) => {
+        const parts = [
+          event.capturedAt,
+          event.source,
+          event.kind,
+          event.toolName,
+          event.status,
+          event.summary,
+        ].filter(Boolean);
+        return `- ${parts.join(" | ")}`;
+      }),
+      ...(result.nextActions.length > 0 ? ["", "Next:", ...result.nextActions.map((command) => `  ${command}`)] : []),
+    ].join("\n") + "\n";
+  }
+  if ("privacy" in result || "event" in result || "agentMemory" in result || "events" in result || "watch" in result) {
+    return formatAgentMemoryHuman(result as AgentMemoryCommandResult);
+  }
   if ("targets" in result) {
     return `${result.targets.map((target) => `${target.name}${target.default ? " (default)" : ""}${target.optional ? " (optional)" : ""}${target.custom ? " (custom)" : ""}`).join("\n")}\n`;
   }
   if ("context" in result) {
     return `${JSON.stringify(result.context, null, 2)}\n`;
   }
+  if ("exportResult" in result) {
+    return [
+      `agent prepare ${result.ok ? "ok" : "failed"} for ${result.target}`,
+      "commands:",
+      ...Object.entries(result.commands).map(([name, command]) => `- ${name}: ${command}`),
+      "files written:",
+      ...(result.exportResult.filesWritten.length > 0 ? result.exportResult.filesWritten.map((file) => `- ${file}`) : ["- none"]),
+    ].join("\n") + "\n";
+  }
+  if ("readyToEdit" in result) {
+    return [
+      `agent onboard ${result.ok ? "ready" : "needs attention"} for ${result.target}`,
+      `ready to edit: ${result.readyToEdit ? "yes" : "no"}`,
+      `hook bridge: ${result.summary.hookBridge}`,
+      `hook approval: ${result.summary.approvalStatus}`,
+      `native trust: ${result.summary.nativeTrustStatus}`,
+      `generated fresh: ${result.summary.generatedFresh ? "yes" : "no"}`,
+      `generated changed: ${result.summary.generatedChangedFiles}`,
+      `changed files: ${result.summary.changedFiles}`,
+      "",
+      "steps:",
+      ...result.steps.map((step) => `${step.ok ? "OK" : "WARN"} ${step.name}: ${step.message}`),
+      ...(result.nextActions.length > 0 ? ["", "Next:", ...result.nextActions.map((command) => `  ${command}`)] : []),
+    ].join("\n") + "\n";
+  }
+  if ("ingestResult" in result || ("checks" in result && "installResult" in result)) {
+    const smoke = result as AgentHooksSmokeResult;
+    return [
+      `agent hooks smoke ${smoke.ok ? "ok" : "failed"} for ${smoke.target}`,
+      `smoke ready: ${smoke.smokeReady ? "yes" : "no"}`,
+      `trusted native ready: ${smoke.trustedNativeReady ? "yes" : "no"}`,
+      `readiness level: ${smoke.readinessLevel}`,
+      `approval: ${smoke.approvalStatus}`,
+      `native trust: ${smoke.nativeTrustStatus}`,
+      `native signals: ${smoke.nativeSignals}`,
+      `canary signals: ${smoke.canarySignals}`,
+      ...smoke.checks.map((check) => `${check.ok ? "OK" : "FAIL"} ${check.name}${check.message ? `: ${check.message}` : ""}`),
+      ...(smoke.canary
+        ? [
+            "",
+            "Canary:",
+            `  marker: ${smoke.canary.marker}`,
+            `  source: ${smoke.canary.source}`,
+            `  event: ${smoke.canary.eventName}`,
+            ...(smoke.canary.ingestedEventId ? [`  ingested id: ${smoke.canary.ingestedEventId}`] : []),
+            `  memory events checked: ${smoke.canary.memoryEventsChecked}`,
+            `  visible: ${smoke.canary.visible ? "yes" : "no"}`,
+          ]
+        : []),
+      ...(smoke.lastSignal
+        ? [
+            "",
+            `last signal: ${smoke.lastSignal.kind}${smoke.lastSignal.summary ? ` - ${smoke.lastSignal.summary}` : ""}`,
+            `captured at: ${smoke.lastSignal.capturedAt}`,
+          ]
+        : []),
+      ...(smoke.nextActions.length > 0 ? ["", "Next:", ...smoke.nextActions.map((command) => `  ${command}`)] : []),
+    ].join("\n") + "\n";
+  }
+  if ("installed" in result && "visibleInMemory" in result) {
+    return [
+      `agent hooks status ${result.ok ? "ready" : "needs attention"} for ${result.target}`,
+      `installed: ${result.installed ? "yes" : "no"}`,
+      `bridge writable: ${result.bridgeWritable ? "yes" : "no"}`,
+      `delta writable: ${result.deltaWritable ? "yes" : "no"}`,
+      `visible in memory: ${result.visibleInMemory ? "yes" : "no"}`,
+      `useful signals: ${result.usefulSignals}`,
+      `native signals: ${result.nativeSignals}`,
+      `canary signals: ${result.canarySignals}`,
+      `approval: ${result.approvalStatus}`,
+      `native trust: ${result.nativeTrustStatus}`,
+      ...("recentEvents" in result ? [`recent events: ${result.recentEvents}`] : []),
+      ...("queuedEvents" in result ? [`queued events: ${result.queuedEvents ?? 0}`] : []),
+      ...(result.lastSignal ? [`last signal: ${result.lastSignal.kind}${result.lastSignal.summary ? ` - ${result.lastSignal.summary}` : ""}`] : []),
+      ...(result.nextActions.length > 0 ? ["", "Next:", ...result.nextActions.map((command) => `  ${command}`)] : []),
+    ].join("\n") + "\n";
+  }
   if ("checks" in result) {
-    return `Forge Agent Doctor\n\n${result.checks.map((check) => `${check.ok ? "OK" : "WARN"} ${check.name}${check.message ? `: ${check.message}` : ""}`).join("\n")}\n`;
+    const nextActions = "nextActions" in result && Array.isArray(result.nextActions)
+      ? result.nextActions as string[]
+      : [];
+    return [
+      `Forge Agent Doctor ${result.ok ? "ready" : "needs attention"}`,
+      "",
+      ...result.checks.map((check) => `${check.ok ? "OK" : "WARN"} ${check.name}${check.message ? `: ${check.message}` : ""}`),
+      ...(nextActions.length > 0 ? ["", "Next:", ...nextActions.map((command) => `  ${command}`)] : []),
+    ].join("\n") + "\n";
   }
   if ("stale" in result) {
     if (result.ok) {
@@ -998,5 +2456,6 @@ export function formatAgentHuman(result: Awaited<ReturnType<typeof runAgentComma
     }
     return `agent adapter exports are stale\nmissing: ${result.missing.join(", ") || "none"}\nstale: ${result.stale.join(", ") || "none"}\n`;
   }
-  return `agent export ${result.ok ? "ok" : "failed"} for ${result.target}\nfiles written:\n${result.filesWritten.map((file) => `- ${file}`).join("\n") || "- none"}\n`;
+  const exportResult = result as AgentExportResult;
+  return `agent export ${exportResult.ok ? "ok" : "failed"} for ${exportResult.target}\nfiles written:\n${exportResult.filesWritten.map((file: string) => `- ${file}`).join("\n") || "- none"}\n`;
 }