forgeos 0.1.0-alpha.4 → 0.1.0-alpha.41

package/src/forge/cli/progress.ts

@@ -0,0 +1,51 @@
+export interface CommandHeartbeat {
+  setPhase: (phase: string) => void;
+  stop: () => void;
+}
+
+export function startCommandHeartbeat(input: {
+  label: string;
+  enabled?: boolean;
+  initialPhase?: string;
+  intervalMs?: number;
+  stallMs?: number;
+}): CommandHeartbeat {
+  if (input.enabled === false || process.env.FORGE_PROGRESS === "0") {
+    return {
+      setPhase: () => {},
+      stop: () => {},
+    };
+  }
+
+  const startedAt = Date.now();
+  const intervalMs = input.intervalMs ?? 10_000;
+  const stallMs = input.stallMs ?? 30_000;
+  let phase = input.initialPhase ?? "running";
+  let ticks = 0;
+
+  const timer = setInterval(() => {
+    ticks += 1;
+    const elapsedMs = Date.now() - startedAt;
+    const elapsedSeconds = Math.round(elapsedMs / 1000);
+    const stalled = elapsedMs >= stallMs;
+    const prefix = stalled ? "still waiting" : "working";
+    process.stderr.write(
+      `[forge] ${input.label}: ${prefix}; phase=${phase}; elapsed=${elapsedSeconds}s\n`,
+    );
+    if (stalled && ticks === Math.ceil(stallMs / intervalMs)) {
+      process.stderr.write(
+        `[forge] ${input.label}: run with --json for structured status; for dev startup failures, use forge last --json.\n`,
+      );
+    }
+  }, intervalMs);
+  timer.unref?.();
+
+  return {
+    setPhase: (nextPhase: string) => {
+      phase = nextPhase;
+    },
+    stop: () => {
+      clearInterval(timer);
+    },
+  };
+}

package/src/forge/cli/query.ts

@@ -1,6 +1,10 @@
 import { listQueries, runQuery, type ListQueriesResult, type RunQueryResult } from "../runtime/query/run-query.ts";
 import { resolveAuthFromCli } from "../runtime/auth/resolve.ts";
 import { createDiagnostic } from "../compiler/diagnostics/create.ts";
+import {
+  resolveExternalQualifiedName,
+  runExternalEntry,
+} from "../runtime/external/bridge.ts";
 
 export type QuerySubcommand = "list" | "run";
 
@@ -52,6 +56,34 @@ export async function runQueryCommand(
     role: options.role,
   });
 
+  const external = resolveExternalQualifiedName(options.workspaceRoot, options.name, "query");
+  if (external) {
+    const run = await runExternalEntry(options.workspaceRoot, {
+      kind: "query",
+      serviceName: external.serviceName,
+      entryName: external.entryName,
+      args: options.args,
+      auth,
+    });
+    return {
+      run: {
+        ok: run.ok,
+        result: run.result,
+        query: {
+          name: `${external.serviceName}.${external.entryName}`,
+          qualifiedName: `${external.serviceName}.${external.entryName}`,
+          file: `external:${external.serviceName}`,
+          symbolId: `external:${external.serviceName}:query:${external.entryName}`,
+          moduleId: `external:${external.serviceName}`,
+        },
+        diagnostics: run.diagnostics,
+        exitCode: run.exitCode,
+        traceId: run.traceId,
+      },
+      exitCode: run.exitCode,
+    };
+  }
+
   const run = await runQuery(options.workspaceRoot, options.name, {
     args: options.args,
     auth,

package/src/forge/cli/release.ts

@@ -18,12 +18,14 @@ import {
   providerConfigDiagnostics,
 } from "../runtime/release/runtime.ts";
 import { symbolicateStacktrace } from "../runtime/release/symbolicate.ts";
+import { releasePrepareNextActions, releaseReadyNextActions } from "./next-actions.ts";
 
 export type ReleaseArea = "release" | "artifacts" | "sourcemaps";
 export type ReleaseAction =
   | "prepare"
   | "inspect"
   | "check"
+  | "doctor"
   | "finalize"
   | "collect"
   | "list"
@@ -44,12 +46,15 @@ export interface ReleaseCommandOptions {
   target?: ReleaseExportProvider;
   allowDirty: boolean;
   allowPublicSourcemaps: boolean;
+  allowMissingLocalRelease?: boolean;
 }
 
 export interface ReleaseCommandResult {
   ok: boolean;
   data?: unknown;
   diagnostics: Diagnostic[];
+  nextActions?: string[];
+  failureKind?: string;
   exitCode: 0 | 1;
 }
 
@@ -125,19 +130,34 @@ export async function runReleaseCommand(
     const dir = latestReleaseDir(options.workspaceRoot);
     const diagnostics: Diagnostic[] = [];
     if (!dir || !nodeFileSystem.exists(join(dir, "release.json"))) {
-      diagnostics.push(
-        createDiagnostic({
-          severity: "error",
+      if (options.allowMissingLocalRelease) {
+        diagnostics.push(createDiagnostic({
+          severity: "warning",
           code: FORGE_RELEASE_ID_MISSING,
-          message: "no prepared local release found",
-        }),
-      );
+          message: "no prepared local release found; treating this as not-prepared because --allow-missing-local-release was provided",
+          fixHint: "Run forge release prepare when you want to validate a concrete release bundle.",
+          suggestedCommands: releasePrepareNextActions(),
+        }));
+      } else {
+        diagnostics.push(
+          createDiagnostic({
+            severity: "error",
+            code: FORGE_RELEASE_ID_MISSING,
+            message: "no prepared local release found; run forge release prepare before release check/finalize",
+            fixHint: "Prepare a local release first, then re-run the release gate.",
+            suggestedCommands: releasePrepareNextActions(),
+          }),
+        );
+      }
     }
+    const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
     return {
-      ok: diagnostics.length === 0,
-      data: { releaseDir: dir },
+      ok: errors.length === 0,
+      data: { releaseDir: dir, state: diagnostics.length === 0 ? "prepared" : "missing-prepared-release" },
       diagnostics,
-      exitCode: diagnostics.length === 0 ? 0 : 1,
+      nextActions: diagnostics.length === 0 ? releaseReadyNextActions() : releasePrepareNextActions(),
+      failureKind: errors.length === 0 ? undefined : "missing-prepared-release",
+      exitCode: errors.length === 0 ? 0 : 1,
     };
   }
 
@@ -256,7 +276,7 @@ export async function runReleaseCommand(
     };
   }
 
-  return { ok: false, diagnostics: [], exitCode: 1 };
+  return { ok: false, diagnostics: [], failureKind: "unsupported-release-command", exitCode: 1 };
 }
 
 function missingRelease(): ReleaseCommandResult {
@@ -266,9 +286,13 @@ function missingRelease(): ReleaseCommandResult {
       createDiagnostic({
         severity: "error",
         code: FORGE_RELEASE_ID_MISSING,
-        message: "release not found",
+        message: "release not found; pass --release <id> or run forge release prepare first",
+        fixHint: "Inspect the prepared releases directory or create a new local release.",
+        suggestedCommands: ["forge release prepare --env production", "forge release inspect --json"],
       }),
     ],
+    nextActions: ["forge release prepare --env production", "forge release inspect --json"],
+    failureKind: "missing-prepared-release",
     exitCode: 1,
   };
 }

package/src/forge/cli/rls.ts

@@ -19,7 +19,7 @@ import type { DbAdapter, DbAdapterKind, DbTransaction } from "../runtime/db/adap
 import { createDbAdapter } from "../runtime/db/factory.ts";
 import { databaseUrlUsesPostgresSuperuser } from "../runtime/db/session-context.ts";
 import type { RlsTableSecurity } from "../compiler/data-graph/rls/types.ts";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 export type RlsSubcommand = "generate" | "check" | "apply" | "test" | "mutate-test";
 
@@ -201,34 +201,61 @@ async function setTenant(tx: DbTransaction, tenantId: string): Promise<void> {
 async function setProbeRole(adapter: DbAdapter, tableNames: string[]): Promise<string | null> {
   const roleName = "forge_rls_probe";
   try {
+    const schema = await adapter.query("SELECT current_schema() AS schema");
+    const currentSchema = String(schema.rows[0]?.schema ?? "public");
     await adapter.query(
       `DO $$ BEGIN CREATE ROLE ${quoteIdent(roleName)} NOLOGIN NOBYPASSRLS; EXCEPTION WHEN duplicate_object THEN NULL; END $$`,
     );
     await adapter.query(`GRANT USAGE ON SCHEMA public TO ${quoteIdent(roleName)}`);
     await adapter.query(`GRANT USAGE ON SCHEMA forge TO ${quoteIdent(roleName)}`);
+    if (currentSchema !== "public" && currentSchema !== "forge") {
+      await adapter.query(`GRANT USAGE ON SCHEMA ${quoteIdent(currentSchema)} TO ${quoteIdent(roleName)}`);
+    }
     for (const tableName of tableNames) {
       await adapter.query(
         `GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE ${quoteIdent(tableName)} TO ${quoteIdent(roleName)}`,
       );
     }
     await adapter.query(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO ${quoteIdent(roleName)}`);
+    if (currentSchema !== "public" && currentSchema !== "forge") {
+      await adapter.query(
+        `GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA ${quoteIdent(currentSchema)} TO ${quoteIdent(roleName)}`,
+      );
+    }
     return roleName;
   } catch {
     return null;
   }
 }
 
+async function isolateRlsProbeSchema(adapter: DbAdapter): Promise<string | null> {
+  const schemaName = `forge_rls_probe_${randomUUID().replaceAll("-", "").slice(0, 16)}`;
+  try {
+    await adapter.query(`CREATE SCHEMA ${quoteIdent(schemaName)}`);
+    await adapter.query(`SET search_path TO ${quoteIdent(schemaName)}, forge, public`);
+    return schemaName;
+  } catch {
+    return null;
+  }
+}
+
 async function seedReferencedRows(
   tx: DbTransaction,
   plan: SqlPlan,
   columns: ColumnDef[],
   row: Record<string, unknown>,
   seed: string,
+  seen: Set<string>,
 ): Promise<void> {
   for (const column of columns) {
     if (!column.references) {
       continue;
     }
+    const key = `${column.references.table}.${column.references.column}:${String(row[column.name])}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
     const referenced = tablePlan(plan, column.references.table);
     if (!referenced?.columns) {
       continue;
@@ -297,9 +324,10 @@ async function runTableProbe(
 
   const tx = await adapter.begin();
   try {
-    await seedReferencedRows(tx, plan, columns, rowA, `${table.table}:a`);
-    await seedReferencedRows(tx, plan, columns, rowB, `${table.table}:b`);
-    await seedReferencedRows(tx, plan, columns, mismatchRow, `${table.table}:mismatch`);
+    const seededReferences = new Set<string>();
+    await seedReferencedRows(tx, plan, columns, rowA, `${table.table}:a`, seededReferences);
+    await seedReferencedRows(tx, plan, columns, rowB, `${table.table}:b`, seededReferences);
+    await seedReferencedRows(tx, plan, columns, mismatchRow, `${table.table}:mismatch`, seededReferences);
     if (role) {
       await tx.query(`SET ROLE ${quoteIdent(role)}`);
     }
@@ -419,7 +447,13 @@ async function runRlsIsolationTests(options: RlsCommandOptions): Promise<RlsComm
     };
   }
 
+  let probeSchema: string | null = null;
+
   try {
+    if (options.db === "postgres") {
+      probeSchema = await isolateRlsProbeSchema(adapter);
+    }
+
     const migrationDiagnostics = await applyMigrations(adapter, plan);
     const migrationErrors = migrationDiagnostics.filter((diagnostic) => diagnostic.severity === "error");
     if (migrationErrors.length > 0) {
@@ -490,6 +524,11 @@ async function runRlsIsolationTests(options: RlsCommandOptions): Promise<RlsComm
       exitCode: 1,
     };
   } finally {
+    if (probeSchema) {
+      await adapter.query("RESET ROLE").catch(() => undefined);
+      await adapter.query("RESET search_path").catch(() => undefined);
+      await adapter.query(`DROP SCHEMA IF EXISTS ${quoteIdent(probeSchema)} CASCADE`).catch(() => undefined);
+    }
     await adapter.close();
   }
 }

package/src/forge/cli/run.ts

@@ -1,6 +1,11 @@
 import { listEntries, runEntry } from "../runtime/executor.ts";
 import { createDiagnostic } from "../compiler/diagnostics/create.ts";
 import type { RunEntryResult, ListEntriesResult } from "../runtime/executor.ts";
+import {
+  resolveExternalQualifiedName,
+  runExternalEntry,
+} from "../runtime/external/bridge.ts";
+import { resolveAuthFromCli } from "../runtime/auth/resolve.ts";
 
 export interface RunCommandOptions {
   name?: string;
@@ -10,6 +15,7 @@ export interface RunCommandOptions {
   userId?: string;
   tenantId?: string;
   role?: string;
+  args?: unknown;
   workspaceRoot: string;
 }
 
@@ -29,6 +35,41 @@ export async function runRunCommand(
     return { list, exitCode: list.exitCode };
   }
 
+  const external = resolveExternalQualifiedName(options.workspaceRoot, options.name!, "command");
+  if (external) {
+    const run = await runExternalEntry(options.workspaceRoot, {
+      kind: "command",
+      serviceName: external.serviceName,
+      entryName: external.entryName,
+      args: options.args,
+      auth: resolveAuthFromCli({
+        userId: options.userId,
+        tenantId: options.tenantId,
+        role: options.role,
+      }),
+    });
+    return {
+      run: {
+        ok: run.ok,
+        result: run.result,
+        diagnostics: run.diagnostics,
+        exitCode: run.exitCode,
+        traceId: run.traceId,
+        entry: {
+          id: `external:${external.serviceName}:command:${external.entryName}`,
+          kind: "command",
+          name: `${external.serviceName}.${external.entryName}`,
+          qualifiedName: `${external.serviceName}.${external.entryName}`,
+          file: `external:${external.serviceName}`,
+          moduleId: `external:${external.serviceName}`,
+          runtimeContext: "command",
+          dependencies: [],
+        },
+      },
+      exitCode: run.exitCode,
+    };
+  }
+
   const run = await runEntry(options.workspaceRoot, options.name!, {
     json: options.json,
     mock: options.mock,

package/src/forge/cli/security.ts

@@ -9,6 +9,9 @@ import type { AiCommandResult } from "./ai.ts";
 import { runAiCommand } from "./ai.ts";
 import { runCheckCommand } from "./commands.ts";
 import type { GenerateResult } from "../compiler/types/cli.ts";
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 
 export type SecuritySubcommand = "prove";
 
@@ -27,6 +30,17 @@ export interface SecurityCommandOptions {
   json: boolean;
   db: DbAdapterKind;
   databaseUrl?: string;
+  runTests: boolean;
+}
+
+export interface SecurityTestRunResult {
+  enabled: boolean;
+  ok: boolean;
+  command: string[];
+  tests: string[];
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
 }
 
 export interface SecurityProofResult {
@@ -41,6 +55,7 @@ export interface SecurityProofResult {
     rls: RlsCommandResult;
     rlsMutation: RlsCommandResult;
     agentRedteam: AiCommandResult;
+    securityTests: SecurityTestRunResult;
   };
   evidence: {
     invariants: SecurityInvariantEvidence[];
@@ -155,6 +170,88 @@ function passed(name: string, ok: boolean, summary: SecurityProofResult["summary
   }
 }
 
+function securityTestFiles(options: SecurityCommandOptions): string[] {
+  const tests = new Set<string>();
+  for (const invariant of invariantEvidence()) {
+    for (const test of invariant.tests) {
+      if (!test.startsWith("tests/security/")) {
+        continue;
+      }
+      if (options.db !== "postgres" && test.includes("rls-postgres-adversarial.test.ts")) {
+        continue;
+      }
+      tests.add(test);
+    }
+  }
+  return [...tests].sort();
+}
+
+function runSecurityTests(options: SecurityCommandOptions): SecurityTestRunResult {
+  const tests = securityTestFiles(options);
+  const command = [
+    "./bin/forge-bun.mjs",
+    "test",
+    ...tests,
+    "--timeout",
+    "120000",
+  ];
+
+  if (!options.runTests) {
+    return {
+      enabled: false,
+      ok: true,
+      command: ["node", ...command],
+      tests,
+      exitCode: null,
+      stdout: "",
+      stderr: "",
+    };
+  }
+
+  const missingTests = tests.filter((test) => !existsSync(join(options.workspaceRoot, test)));
+  const runnerPath = join(options.workspaceRoot, "bin", "forge-bun.mjs");
+  if (missingTests.length > 0 || !existsSync(runnerPath)) {
+    return {
+      enabled: false,
+      ok: true,
+      command: ["node", ...command],
+      tests,
+      exitCode: null,
+      stdout: "",
+      stderr:
+        "security invariant test fixtures are not available in this workspace; structural proofs still ran. Run this command from the ForgeOS source checkout to execute the full framework test fixtures.",
+    };
+  }
+
+  const result = spawnSync(process.execPath, command, {
+    cwd: options.workspaceRoot,
+    encoding: "utf8",
+    env: {
+      ...process.env,
+      ...(options.databaseUrl ? { DATABASE_URL: options.databaseUrl } : {}),
+    },
+    windowsHide: true,
+  });
+
+  return {
+    enabled: true,
+    ok: result.status === 0,
+    command: ["node", ...command],
+    tests,
+    exitCode: result.status,
+    stdout: limitOutput(result.stdout ?? ""),
+    stderr: limitOutput(result.stderr ?? ""),
+  };
+}
+
+function limitOutput(output: string): string {
+  const maxLength = 20_000;
+  if (output.length <= maxLength) {
+    return output;
+  }
+  return `${output.slice(0, 4_000)}\n\n[forge output truncated]\n\n${output.slice(-16_000)}`;
+}
+
 export async function runSecurityCommand(
   options: SecurityCommandOptions,
 ): Promise<SecurityProofResult> {
@@ -189,6 +286,7 @@ export async function runSecurityCommand(
     workspaceRoot: options.workspaceRoot,
     json: true,
   });
+  const securityTests = runSecurityTests(options);
 
   const summary: SecurityProofResult["summary"] = {
     passed: [],
@@ -201,6 +299,9 @@ export async function runSecurityCommand(
   passed("rls-proof", rls.exitCode === 0, summary);
   passed("rls-mutation-proof", rlsMutation.exitCode === 0, summary);
   passed("agent-redteam", agentRedteam.exitCode === 0, summary);
+  if (securityTests.enabled) {
+    passed("security-tests", securityTests.ok, summary);
+  }
 
   if (auth.mode === "dev-headers") {
     summary.warnings.push("auth-proof uses local-only dev-headers mode");
@@ -220,6 +321,15 @@ export async function runSecurityCommand(
       summary.warnings.push(`${diagnostic.code}: ${diagnostic.message}`);
     }
   }
+  if (!securityTests.enabled && !options.runTests) {
+    summary.warnings.push("security-tests not executed; pass --full or --run-tests to run invariant security tests");
+  }
+  if (!securityTests.enabled && options.runTests) {
+    summary.warnings.push(securityTests.stderr);
+  }
+  if (options.runTests && options.db !== "postgres") {
+    summary.warnings.push("postgres RLS adversarial test skipped because --db postgres was not selected");
+  }
 
   const ok = summary.failed.length === 0;
   const assurance =
@@ -240,6 +350,7 @@ export async function runSecurityCommand(
       rls,
       rlsMutation,
       agentRedteam,
+      securityTests,
     },
     evidence: {
       invariants: invariantEvidence(),
@@ -261,6 +372,7 @@ export function formatSecurityHuman(result: SecurityProofResult): string {
     `Assurance: ${result.assurance}`,
     `Passed: ${result.summary.passed.join(", ") || "none"}`,
     `Failed: ${result.summary.failed.join(", ") || "none"}`,
+    `Security tests: ${result.proofs.securityTests.enabled ? (result.proofs.securityTests.ok ? "passed" : "failed") : "not run"}`,
   ];
   if (result.summary.warnings.length > 0) {
     lines.push("", "Warnings:", ...result.summary.warnings.map((warning) => `- ${warning}`));

package/src/forge/cli/self-host.ts

@@ -4,6 +4,7 @@ import { GENERATED_DIR } from "../compiler/emitter/constants.ts";
 import { stripDeterministicHeader } from "../compiler/primitives/header.ts";
 import { runGenerateCommand } from "./commands.ts";
 import { runVerifyCommand } from "./verify.ts";
+import { selfHostPrepareNextActions, selfHostReadyNextActions } from "./next-actions.ts";
 
 export type SelfHostSubcommand = "compose" | "env" | "check" | "clean";
 
@@ -15,6 +16,7 @@ export interface SelfHostCommandOptions {
   postgresVersion: string;
   runtimePort: number;
   webPort: number;
+  preparedOnly?: boolean;
 }
 
 export interface SelfHostCheck {
@@ -26,8 +28,10 @@ export interface SelfHostCheck {
 export interface SelfHostCommandResult {
   ok: boolean;
   exitCode: 0 | 1;
+  state?: "ready" | "not-prepared" | "failed";
   files?: string[];
   checks?: SelfHostCheck[];
+  nextActions?: string[];
 }
 
 function deployDir(workspaceRoot: string): string {
@@ -392,6 +396,28 @@ export async function runSelfHostCommand(
   }
 
   const checks: SelfHostCheck[] = [];
+  const requiredDeployFiles = [
+    "docker-compose.yml",
+    "Dockerfile.runtime",
+    "Dockerfile.web",
+    ".dockerignore",
+    ".env.example",
+    "README.md",
+  ];
+  const missingDeployFiles = requiredDeployFiles.filter((file) => !nodeFileSystem.exists(join(dir, file)));
+  if (options.preparedOnly && missingDeployFiles.length > 0) {
+    return {
+      ok: true,
+      state: "not-prepared",
+      exitCode: 0,
+      checks: missingDeployFiles.map((file) => ({
+        name: `deploy/${file}`,
+        ok: true,
+        details: { state: "not-prepared", missing: true, command: "forge self-host compose" },
+      })),
+      nextActions: selfHostPrepareNextActions(),
+    };
+  }
   const generated = await runGenerateCommand({
     workspaceRoot: options.workspaceRoot,
     check: true,
@@ -399,7 +425,11 @@ export async function runSelfHostCommand(
     json: false,
     concurrency: 4,
   });
-  checks.push({ name: "generated", ok: generated.exitCode === 0 });
+  checks.push({
+    name: "generated",
+    ok: generated.exitCode === 0,
+    details: generated.exitCode === 0 ? undefined : { command: "forge generate" },
+  });
 
   const verify = await runVerifyCommand({
     workspaceRoot: options.workspaceRoot,
@@ -409,17 +439,19 @@ export async function runSelfHostCommand(
     skipEslint: true,
     strict: true,
   });
-  checks.push({ name: "verify-strict", ok: verify.exitCode === 0 });
+  checks.push({
+    name: "verify-strict",
+    ok: verify.exitCode === 0,
+    details: verify.exitCode === 0 ? undefined : { command: "forge verify --strict" },
+  });
 
-  for (const file of [
-    "docker-compose.yml",
-    "Dockerfile.runtime",
-    "Dockerfile.web",
-    ".dockerignore",
-    ".env.example",
-    "README.md",
-  ]) {
-    checks.push({ name: `deploy/${file}`, ok: nodeFileSystem.exists(join(dir, file)) });
+  for (const file of requiredDeployFiles) {
+    const exists = nodeFileSystem.exists(join(dir, file));
+    checks.push({
+      name: `deploy/${file}`,
+      ok: exists,
+      details: exists ? undefined : { missing: true, command: "forge self-host compose" },
+    });
   }
 
   const envExample = nodeFileSystem.exists(join(dir, ".env.example"))
@@ -452,7 +484,13 @@ export async function runSelfHostCommand(
   });
 
   const ok = checks.every((check) => check.ok);
-  return { ok, exitCode: ok ? 0 : 1, checks };
+  return {
+    ok,
+    state: ok ? "ready" : "failed",
+    exitCode: ok ? 0 : 1,
+    checks,
+    nextActions: ok ? selfHostReadyNextActions() : selfHostPrepareNextActions(),
+  };
 }
 
 export function formatSelfHostHuman(result: SelfHostCommandResult): string {
@@ -460,9 +498,13 @@ export function formatSelfHostHuman(result: SelfHostCommandResult): string {
     return `wrote self-host files:\n${result.files.map((file) => `  ${file}`).join("\n")}\n`;
   }
   if (result.checks) {
-    return `${result.checks
+    const lines = result.checks
       .map((check) => `${check.ok ? "ok" : "fail"} ${check.name}`)
-      .join("\n")}\n`;
+      .join("\n");
+    const next = result.nextActions && result.nextActions.length > 0
+      ? `\nNext:\n${result.nextActions.map((action) => `  ${action}`).join("\n")}\n`
+      : "\n";
+    return `${lines}${next}`;
   }
   return result.ok ? "self-host clean complete\n" : "self-host command failed\n";
 }