@agent-native/core 0.95.1 → 0.97.0

package/corpus/core/src/audit/actions/export-audit-events.ts

@@ -0,0 +1,162 @@
+import { z } from "zod";
+
+import { defineAction } from "../../action.js";
+import { MAX_LIMIT, queryAuditEvents } from "../store.js";
+import type { AuditEvent } from "../types.js";
+
+const DEFAULT_MAX_ROWS = 5000;
+const HARD_CAP_ROWS = 10000;
+
+// Deterministic column order for CSV — mirrors the store's list projection
+// (`LIST_COLUMNS`), which deliberately excludes `input` so a bulk export
+// never streams every event's (redacted) request body at once. Future
+// columns added to the audit store must be reflected here too.
+const CSV_COLUMNS: Array<[key: keyof AuditEvent, header: string]> = [
+  ["id", "id"],
+  ["createdAt", "created_at"],
+  ["action", "action"],
+  ["caller", "caller"],
+  ["actorKind", "actor_kind"],
+  ["actorEmail", "actor_email"],
+  ["orgId", "org_id"],
+  ["threadId", "thread_id"],
+  ["turnId", "turn_id"],
+  ["targetType", "target_type"],
+  ["targetId", "target_id"],
+  ["status", "status"],
+  ["summary", "summary"],
+  ["errorCode", "error_code"],
+  ["ownerEmail", "owner_email"],
+  ["visibility", "visibility"],
+];
+
+/** Hand-rolled CSV field escaper — quotes a field when it contains a comma,
+ *  quote, or newline, doubling any embedded quotes. No dependency needed for
+ *  ~10 lines of RFC 4180 escaping. */
+function csvField(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  const raw = String(value);
+  if (/[",\n\r]/.test(raw)) {
+    return `"${raw.replace(/"/g, '""')}"`;
+  }
+  return raw;
+}
+
+function toCsv(events: AuditEvent[]): string {
+  const header = CSV_COLUMNS.map(([, label]) => label).join(",");
+  const rows = events.map((event) =>
+    CSV_COLUMNS.map(([key]) => csvField(event[key])).join(","),
+  );
+  return [header, ...rows].join("\n");
+}
+
+function toNdjson(events: AuditEvent[]): string {
+  return events.map((event) => JSON.stringify(event)).join("\n");
+}
+
+/**
+ * Bulk-export audit-log events as CSV or NDJSON — the "bulk export" sensitive
+ * read the audit doc itself names. Pages past the per-call row clamp
+ * (`queryAuditEvents`'s `MAX_LIMIT`) up to `maxRows`, scoped in SQL to the
+ * caller's identity exactly like `list-audit-events`. Read-only; never
+ * exposes other tenants' rows.
+ */
+export default defineAction({
+  description:
+    "Export audit-log events as a CSV or NDJSON document for offline/compliance pulls (up to maxRows, default 5000, hard cap 10000). Use this instead of hand-paging list-audit-events when you need a bulk download of the trail; use list-audit-events instead for browsing recent activity or answering 'what changed'.",
+  schema: z.object({
+    targetType: z
+      .string()
+      .optional()
+      .describe("Filter to one resource type, e.g. 'recording'."),
+    targetId: z
+      .string()
+      .optional()
+      .describe("Filter to one resource id (pair with targetType)."),
+    actorKind: z
+      .enum(["agent", "human", "system"])
+      .optional()
+      .describe("Filter to changes made by the agent, a human, or the system."),
+    actorEmail: z.string().optional().describe("Filter to one actor's email."),
+    status: z
+      .enum(["success", "error", "denied"])
+      .optional()
+      .describe("Filter by outcome."),
+    threadId: z.string().optional().describe("Filter to one agent thread."),
+    turnId: z
+      .string()
+      .optional()
+      .describe("Filter to one agent turn (a single agent response)."),
+    action: z.string().optional().describe("Filter to one action name."),
+    sinceMs: z
+      .number()
+      .optional()
+      .describe("Only events at or after this Unix epoch (ms)."),
+    format: z
+      .enum(["csv", "ndjson"])
+      .default("csv")
+      .describe(
+        "Export format — CSV with a header row, or one JSON event per line.",
+      ),
+    maxRows: z
+      .number()
+      .optional()
+      .describe("Max rows to export (default 5000, hard cap 10000)."),
+  }),
+  http: { method: "GET" },
+  audit: {
+    // Read-only actions are skipped by default — this is exactly the
+    // "bulk export" sensitive read the framework's own audit doc calls out.
+    onRead: true,
+    summary: (args) =>
+      `Bulk export of audit events (${(args as { format?: string }).format ?? "csv"})`,
+  },
+  run: async (args, ctx) => {
+    const scope = { userEmail: ctx?.userEmail, orgId: ctx?.orgId ?? null };
+    const cap = Math.min(
+      Math.max(1, Math.floor(args.maxRows ?? DEFAULT_MAX_ROWS)),
+      HARD_CAP_ROWS,
+    );
+
+    const filters = {
+      ...(args.targetType ? { targetType: args.targetType } : {}),
+      ...(args.targetId ? { targetId: args.targetId } : {}),
+      ...(args.actorKind ? { actorKind: args.actorKind } : {}),
+      ...(args.actorEmail ? { actorEmail: args.actorEmail } : {}),
+      ...(args.status ? { status: args.status } : {}),
+      ...(args.threadId ? { threadId: args.threadId } : {}),
+      ...(args.turnId ? { turnId: args.turnId } : {}),
+      ...(args.action ? { action: args.action } : {}),
+      ...(typeof args.sinceMs === "number" ? { sinceMs: args.sinceMs } : {}),
+    };
+
+    const events: AuditEvent[] = [];
+    let offset = 0;
+    while (events.length < cap) {
+      const pageLimit = Math.min(MAX_LIMIT, cap - events.length);
+      const page = await queryAuditEvents(scope, {
+        ...filters,
+        limit: pageLimit,
+        offset,
+      });
+      events.push(...page);
+      offset += page.length;
+      if (page.length < pageLimit) break; // exhausted — no more matching rows
+    }
+
+    // We stopped because we hit the cap, not because we ran out of rows —
+    // probe one more row to know whether the export was actually truncated.
+    let truncated = false;
+    if (events.length >= cap) {
+      const probe = await queryAuditEvents(scope, {
+        ...filters,
+        limit: 1,
+        offset,
+      });
+      truncated = probe.length > 0;
+    }
+
+    const content = args.format === "ndjson" ? toNdjson(events) : toCsv(events);
+    return { content, rowCount: events.length, truncated, format: args.format };
+  },
+});

package/corpus/core/src/audit/store.ts

@@ -250,7 +250,9 @@ function scopeClause(scope: AuditReadScope): { sql: string; args: any[] } {
   return { sql: `(${clauses.join(" OR ")})`, args };
 }
 
-const MAX_LIMIT = 500;
+// Exported so callers that must page past a single call (e.g.
+// `export-audit-events`) can mirror the clamp instead of guessing it.
+export const MAX_LIMIT = 500;
 const DEFAULT_LIMIT = 100;
 
 // Columns returned by the list surface — deliberately EXCLUDES `input` so a
@@ -297,13 +299,16 @@ export async function queryAuditEvents(
     Math.max(1, Math.floor(filters.limit ?? DEFAULT_LIMIT)),
     MAX_LIMIT,
   );
+  // 0-based, default-compatible: existing callers that never pass `offset`
+  // keep selecting from the top of the ordered result set.
+  const offset = Math.max(0, Math.floor(filters.offset ?? 0));
 
   const result = await client.execute({
     sql: `SELECT ${LIST_COLUMNS} FROM agent_audit_log
           WHERE ${where.join(" AND ")}
           ORDER BY created_at DESC
-          LIMIT ?`,
-    args: [...args, limit],
+          LIMIT ? OFFSET ?`,
+    args: [...args, limit, offset],
   });
   return (result.rows ?? []).map(mapRow);
 }

package/corpus/core/src/audit/types.ts

@@ -135,4 +135,7 @@ export interface AuditQueryFilters {
   sourcePlatform?: string;
   sinceMs?: number;
   limit?: number;
+  /** Skip this many matching rows before applying `limit` (0-based). Used by
+   *  `export-audit-events` to page past the per-call `MAX_LIMIT` clamp. */
+  offset?: number;
 }

package/corpus/core/src/chat-threads/store.ts

@@ -639,6 +639,14 @@ export interface ListThreadsOptions {
   /** When true, returns only threads with no scope (general chats). */
   unscopedOnly?: boolean;
   orgId?: string | null;
+  /**
+   * Include archived threads in the results. Defaults to false: archived
+   * threads (`archived_at` set via `setThreadArchived`) are hidden from the
+   * ordinary chat list/search so archiving actually removes a thread from
+   * view. Pass true for surfaces that explicitly need to see archived chats
+   * (e.g. an "Archived" filter or restoring one via `setThreadArchived`).
+   */
+  includeArchived?: boolean;
 }
 
 function chatThreadAccessSql(
@@ -686,6 +694,9 @@ export async function listThreads(
   );
   const filters: string[] = [access.sql, `message_count > 0`];
   const args: (string | number)[] = [...access.args];
+  if (!opts.includeArchived) {
+    filters.push(`archived_at IS NULL`);
+  }
   if (opts.scope) {
     filters.push(`scope_type = ? AND scope_id = ?`);
     args.push(opts.scope.type, opts.scope.id);
@@ -710,7 +721,12 @@ export async function searchThreads(
   ownerEmail: string,
   query: string,
   limit = 50,
-  options: { scope?: { type: string; id: string }; orgId?: string | null } = {},
+  options: {
+    scope?: { type: string; id: string };
+    orgId?: string | null;
+    /** See `ListThreadsOptions.includeArchived` — defaults to false. */
+    includeArchived?: boolean;
+  } = {},
 ): Promise<ChatThreadSummary[]> {
   await ensureTable();
   const client = getDbExec();
@@ -728,6 +744,9 @@ export async function searchThreads(
     `(title LIKE ? ESCAPE '!' OR preview LIKE ? ESCAPE '!' OR thread_data LIKE ? ESCAPE '!')`,
   ];
   const args: (string | number)[] = [...access.args, pattern, pattern, pattern];
+  if (!options.includeArchived) {
+    filters.push(`archived_at IS NULL`);
+  }
   if (options.scope) {
     filters.push(`scope_type = ? AND scope_id = ?`);
     args.push(options.scope.type, options.scope.id);

package/corpus/core/src/cli/code-agent-executor.ts

@@ -215,6 +215,7 @@ export async function executeCodeAgentRun(
       runId: existing.id,
       kind: "status",
       message,
+      signal: "credential-gap",
       metadata: { status: "paused", phase: "missing-credentials" },
     });
     return updateCodeAgentRunRecord(existing.id, {

package/corpus/core/src/cli/code-agent-runs.ts

@@ -77,6 +77,17 @@ export type CodeAgentTranscriptEventKind =
   | "artifact"
   | "status";
 
+/**
+ * Structured, machine-checkable marker for transcript events that need
+ * special handling in the UI beyond free-text matching. `"credential-gap"`
+ * marks the status event the executor appends when no LLM provider key (or
+ * Codex CLI login) is available; consumers should prefer this field over
+ * regex-matching `message` (see `isCredentialGapCodeAgentEvent` in
+ * `../code-agents/transcript-normalizer.js`). Optional so older, already
+ * persisted JSONL transcripts without the field keep parsing unchanged.
+ */
+export type CodeAgentTranscriptEventSignal = "credential-gap";
+
 export interface CodeAgentTranscriptEvent {
   schemaVersion: 1;
   id: string;
@@ -85,6 +96,7 @@ export interface CodeAgentTranscriptEvent {
   message: string;
   createdAt: string;
   metadata?: Record<string, unknown>;
+  signal?: CodeAgentTranscriptEventSignal;
 }
 
 export interface CreateCodeAgentRunInput {
@@ -109,6 +121,7 @@ export interface AppendCodeAgentTranscriptEventInput {
   message: string;
   createdAt?: string;
   metadata?: Record<string, unknown>;
+  signal?: CodeAgentTranscriptEventSignal;
 }
 
 export interface QueueCodeAgentFollowUpInput {
@@ -294,6 +307,7 @@ export function appendCodeAgentTranscriptEvent(
     message: input.message,
     createdAt,
     metadata: input.metadata,
+    ...(input.signal ? { signal: input.signal } : {}),
   };
 
   fs.mkdirSync(codeAgentTranscriptsDir(), { recursive: true });

package/corpus/core/src/cli/doctor.ts

@@ -0,0 +1,396 @@
+/**
+ * `agent-native doctor` — scan an app's source tree for the security-
+ * critical code-safety invariants this monorepo already enforces on
+ * itself via `scripts/guard-*.mjs` (see
+ * `advisor-plans/reports/005-doctor-design.md` for the full design and
+ * `advisor-plans/015-doctor-v1-implementation.md` for the implementation
+ * plan). v1 ships 7 of those guards, ported to work against a single
+ * generated app root instead of this monorepo's multi-template layout —
+ * see `../guards/index.ts`.
+ *
+ * This is a NEW top-level command, deliberately kept separate from the two
+ * existing "doctor" precedents in this CLI:
+ *   - `agent-native upgrade check` (`upgrade.ts`) — dependency-pin health.
+ *   - `agent-native recap doctor` (`recap.ts`) — PR Visual Recap config health.
+ * Each diagnoses a different domain; none are folded into a shared
+ * mega-doctor (see report 005, "Relationship to upgrade doctor and recap
+ * doctor").
+ *
+ * `--fix` is reserved, not implemented in v1 — it prints a message and
+ * exits 2 rather than silently no-op, so a future implementation doesn't
+ * collide with a script already passing the flag.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  scanDbToolScoping,
+  scanDrizzlePush,
+  scanEnvCredentials,
+  scanEnvMutation,
+  scanLocalhostFallback,
+  scanUnscopedCredentials,
+  scanUnscopedQueries,
+} from "../guards/index.js";
+import type { GuardResult } from "../guards/index.js";
+
+export type GuardName =
+  | "no-drizzle-push"
+  | "no-unscoped-credentials"
+  | "no-unscoped-queries"
+  | "no-env-credentials"
+  | "db-tool-scoping"
+  | "no-env-mutation"
+  | "no-localhost-fallback";
+
+export const ALL_GUARD_NAMES: GuardName[] = [
+  "no-drizzle-push",
+  "no-unscoped-credentials",
+  "no-unscoped-queries",
+  "no-env-credentials",
+  "db-tool-scoping",
+  "no-env-mutation",
+  "no-localhost-fallback",
+];
+
+export interface DoctorConfig {
+  disabledGuards: string[];
+  dbToolScopingDenylist: Record<string, string>;
+  failOnBuild: boolean;
+}
+
+const DEFAULT_DOCTOR_CONFIG: DoctorConfig = {
+  disabledGuards: [],
+  dbToolScopingDenylist: {},
+  failOnBuild: false,
+};
+
+export interface DoctorFinding {
+  guard: string;
+  file: string;
+  line: number;
+  message: string;
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  findings: DoctorFinding[];
+  guardsRun: string[];
+}
+
+/**
+ * Reads the optional `"doctor"` key from `<root>/agent-native.json`. All
+ * fields are optional with sane empty defaults — an app needs zero config
+ * to run `agent-native doctor` with every v1 guard enabled.
+ */
+export function readDoctorConfig(root: string): DoctorConfig {
+  const manifestPath = path.join(root, "agent-native.json");
+  if (!fs.existsSync(manifestPath)) {
+    return { ...DEFAULT_DOCTOR_CONFIG, dbToolScopingDenylist: {} };
+  }
+  try {
+    const raw = fs.readFileSync(manifestPath, "utf-8");
+    const parsed = JSON.parse(raw) as { doctor?: Record<string, unknown> };
+    const doctor = parsed.doctor ?? {};
+    const disabledGuards = Array.isArray(doctor.disabledGuards)
+      ? doctor.disabledGuards.filter((v): v is string => typeof v === "string")
+      : [];
+    const dbToolScopingDenylist =
+      doctor.dbToolScopingDenylist &&
+      typeof doctor.dbToolScopingDenylist === "object"
+        ? (Object.fromEntries(
+            Object.entries(
+              doctor.dbToolScopingDenylist as Record<string, unknown>,
+            ).filter(
+              (entry): entry is [string, string] =>
+                typeof entry[1] === "string",
+            ),
+          ) as Record<string, string>)
+        : {};
+    const failOnBuild = doctor.failOnBuild === true;
+    return { disabledGuards, dbToolScopingDenylist, failOnBuild };
+  } catch {
+    return { ...DEFAULT_DOCTOR_CONFIG, dbToolScopingDenylist: {} };
+  }
+}
+
+function runGuard(
+  name: GuardName,
+  root: string,
+  config: DoctorConfig,
+): GuardResult {
+  switch (name) {
+    case "no-drizzle-push":
+      return scanDrizzlePush({ root });
+    case "no-unscoped-credentials":
+      return scanUnscopedCredentials({ root });
+    case "no-unscoped-queries":
+      return scanUnscopedQueries({ root, extraExemptPaths: [] });
+    case "no-env-credentials":
+      return scanEnvCredentials({ root });
+    case "db-tool-scoping":
+      return scanDbToolScoping({
+        root,
+        denylist: config.dbToolScopingDenylist,
+      });
+    case "no-env-mutation":
+      return scanEnvMutation({ root });
+    case "no-localhost-fallback":
+      return scanLocalhostFallback({ root, extraExemptPaths: [] });
+  }
+}
+
+export interface RunDoctorScanOptions {
+  root: string;
+  /** Restrict to these guard names. When omitted, runs every guard not
+   * listed in `agent-native.json`'s `doctor.disabledGuards`. Unknown names
+   * are silently ignored here — the CLI layer (`runDoctor`) validates
+   * `--only` and reports a usage error before calling this. */
+  only?: string[];
+}
+
+/** Pure scan orchestrator: runs the selected guards against `root` and
+ * returns a flat report. No I/O beyond reading `agent-native.json` and the
+ * app source tree — no printing, no process.exit. */
+export function runDoctorScan(options: RunDoctorScanOptions): DoctorReport {
+  const root = options.root;
+  const config = readDoctorConfig(root);
+
+  let names: GuardName[];
+  if (options.only && options.only.length > 0) {
+    const knownOnly = options.only.filter((n): n is GuardName =>
+      (ALL_GUARD_NAMES as string[]).includes(n),
+    );
+    names = knownOnly;
+  } else {
+    names = ALL_GUARD_NAMES.filter((n) => !config.disabledGuards.includes(n));
+  }
+
+  const findings: DoctorFinding[] = [];
+  for (const name of names) {
+    const result = runGuard(name, root, config);
+    for (const f of result.findings) {
+      findings.push({
+        guard: name,
+        file: f.file,
+        line: f.line,
+        message: f.message,
+      });
+    }
+  }
+
+  return { ok: findings.length === 0, findings, guardsRun: names };
+}
+
+/** Pure escalation rule shared by the CLI (`--strict`) and the `build`
+ * pre-step (`--strict` / `agent-native.json` `doctor.failOnBuild`). Doctor
+ * findings never fail anything on their own — only `strict` or
+ * `failOnBuild` turn findings into a hard failure. */
+export function shouldFailBuild(
+  hasFindings: boolean,
+  opts: { strict?: boolean; failOnBuild?: boolean },
+): boolean {
+  return hasFindings && Boolean(opts.strict || opts.failOnBuild);
+}
+
+export interface DoctorIo {
+  log: (message: string) => void;
+  err: (message: string) => void;
+}
+
+const defaultIo: DoctorIo = {
+  log: (message) => console.log(message),
+  err: (message) => console.error(message),
+};
+
+function formatDoctorHuman(report: DoctorReport, root: string): string {
+  const lines: string[] = [];
+  lines.push(`agent-native doctor: ${root}`);
+  lines.push(`Guards run: ${report.guardsRun.join(", ") || "(none)"}`);
+  if (report.findings.length === 0) {
+    lines.push("Clean — no findings.");
+  } else {
+    lines.push(`${report.findings.length} finding(s):`);
+    for (const f of report.findings) {
+      lines.push(`  [${f.guard}] ${f.file}:${f.line} — ${f.message}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export interface DoctorCliOptions {
+  json?: boolean;
+  cwd?: string;
+  only?: string[];
+  strict?: boolean;
+  help?: boolean;
+  fix?: boolean;
+}
+
+export function parseDoctorArgs(argv: string[]): DoctorCliOptions {
+  const opts: DoctorCliOptions = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") {
+      opts.help = true;
+    } else if (arg === "--json") {
+      opts.json = true;
+    } else if (arg === "--strict") {
+      opts.strict = true;
+    } else if (arg === "--fix") {
+      opts.fix = true;
+    } else if (arg === "--cwd" && argv[i + 1] !== undefined) {
+      opts.cwd = argv[++i];
+    } else if (arg.startsWith("--cwd=")) {
+      opts.cwd = arg.slice("--cwd=".length);
+    } else if (arg === "--only" && argv[i + 1] !== undefined) {
+      opts.only = splitGuardList(argv[++i]);
+    } else if (arg.startsWith("--only=")) {
+      opts.only = splitGuardList(arg.slice("--only=".length));
+    }
+  }
+  return opts;
+}
+
+function splitGuardList(value: string): string[] {
+  return value
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+export function printDoctorHelp(io: Pick<DoctorIo, "log"> = defaultIo): void {
+  io.log(
+    [
+      "Usage:",
+      "  agent-native doctor                        Scan app source for security-critical guard violations",
+      "  agent-native doctor --json                 Machine-readable report: { ok, findings, guardsRun }",
+      "  agent-native doctor --only <guard,guard>   Run only the named guard(s)",
+      "  agent-native doctor --strict                Escalate findings to a hard failure when used by `agent-native build --strict`",
+      "  agent-native doctor --cwd <dir>             Run against a project root other than the current directory",
+      "  agent-native doctor --fix                   Not implemented in this version",
+      "  agent-native doctor --help                  Show this help",
+      "",
+      `Guards: ${ALL_GUARD_NAMES.join(", ")}`,
+      "",
+      "Exit codes: 0 clean, 1 findings present, 2 usage/execution error.",
+      "",
+      "`agent-native build` runs doctor as a warn-only pre-step by default — it",
+      "never fails the build unless `agent-native build --strict` is passed or",
+      'agent-native.json sets { "doctor": { "failOnBuild": true } }.',
+      "",
+      "For dependency-pin health (framework overrides/patches, stale",
+      "@agent-native/* pins), run `agent-native upgrade check` instead.",
+    ].join("\n"),
+  );
+}
+
+/** `agent-native doctor` CLI entrypoint. Returns the process exit code —
+ * callers are responsible for calling `process.exit(code)`. */
+export async function runDoctor(
+  argv: string[],
+  io: DoctorIo = defaultIo,
+): Promise<number> {
+  const opts = parseDoctorArgs(argv);
+
+  if (opts.help) {
+    printDoctorHelp(io);
+    return 0;
+  }
+
+  if (opts.fix) {
+    io.err(
+      "agent-native doctor --fix is not implemented in this version. Fix findings manually and re-run `agent-native doctor`.",
+    );
+    return 2;
+  }
+
+  const root = path.resolve(opts.cwd ?? process.cwd());
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    const message = `--cwd path does not exist or is not a directory: ${root}`;
+    if (opts.json) io.err(JSON.stringify({ ok: false, message }, null, 2));
+    else io.err(message);
+    return 2;
+  }
+
+  if (opts.only) {
+    const unknown = opts.only.filter(
+      (n) => !(ALL_GUARD_NAMES as string[]).includes(n),
+    );
+    if (unknown.length > 0) {
+      const message = `Unknown guard name(s) in --only: ${unknown.join(", ")}. Known guards: ${ALL_GUARD_NAMES.join(", ")}`;
+      if (opts.json) io.err(JSON.stringify({ ok: false, message }, null, 2));
+      else io.err(message);
+      return 2;
+    }
+  }
+
+  const report = runDoctorScan({ root, only: opts.only });
+
+  if (opts.json) {
+    const sink = report.ok ? io.log : io.err;
+    sink(JSON.stringify({ ...report, strict: Boolean(opts.strict) }, null, 2));
+  } else {
+    io.log(formatDoctorHuman(report, root));
+    if (!report.ok) {
+      io.err("");
+      io.err(
+        "agent-native doctor found issues above. Fix them, or add a `// guard:allow-<check> — reason` opt-out with reviewer approval.",
+      );
+    }
+  }
+
+  return report.ok ? 0 : 1;
+}
+
+export interface DoctorBuildHookOptions {
+  cwd: string;
+  /** Set when the caller passed `agent-native build --strict`. */
+  strict?: boolean;
+}
+
+export interface DoctorBuildHookResult {
+  /** False only when findings are present AND (`strict` was requested OR
+   * `agent-native.json`'s `doctor.failOnBuild` is true). */
+  ok: boolean;
+  report: DoctorReport;
+}
+
+/**
+ * `agent-native build`'s doctor pre-step. Always runs every enabled guard
+ * and always prints findings (as warnings) to `io.err` — never silent.
+ * Never causes the build to fail unless `strict` was passed or
+ * `agent-native.json` sets `doctor.failOnBuild: true` (see report 005,
+ * "Where it runs" — the v1 doctor has zero field mileage against arbitrary
+ * app layouts, so shipping fail-by-default would risk breaking a first
+ * deploy on a false positive).
+ */
+export async function runDoctorBuildHook(
+  options: DoctorBuildHookOptions,
+  io: DoctorIo = defaultIo,
+): Promise<DoctorBuildHookResult> {
+  const root = path.resolve(options.cwd);
+  const config = readDoctorConfig(root);
+  const report = runDoctorScan({ root });
+
+  if (report.findings.length > 0) {
+    io.err(
+      `\n[doctor] ${report.findings.length} finding(s) from \`agent-native doctor\` — run it directly for details. This does not fail the build unless --strict was passed or agent-native.json's doctor.failOnBuild is true.`,
+    );
+    for (const f of report.findings) {
+      io.err(`  [${f.guard}] ${f.file}:${f.line} — ${f.message}`);
+    }
+  }
+
+  const fail = shouldFailBuild(report.findings.length > 0, {
+    strict: options.strict,
+    failOnBuild: config.failOnBuild,
+  });
+  if (fail) {
+    io.err(
+      `\n[doctor] Failing build: ${options.strict ? "--strict was passed" : "agent-native.json's doctor.failOnBuild is true"}.`,
+    );
+  }
+
+  return { ok: !fail, report };
+}