@app-vitals/agent-admin 0.15.0 → 0.16.1

package/src/agent-cron-jobs.unit.test.ts

@@ -12,8 +12,8 @@ import { describe, expect, test } from "bun:test";
 import type { AgentCronJob, PrismaClient } from "../prisma/client/client.ts";
 import { AgentCronJobService, isValidCron } from "./agent-cron-jobs.ts";
 import {
-  type SpecialtyManifestResolver,
   resolveDefaultSpecialtyName,
+  type SpecialtyManifestResolver,
 } from "./specialty-manifest-loader.ts";
 import type { SpecialtyManifest } from "./specialty-registry.ts";
 
@@ -374,51 +374,159 @@ describe("reconcileSystemCrons (unit, injected registry)", () => {
     expect(String(errors[0]?.[0])).toContain("agent-1");
   });
 
-  test("the default manifest that cannot load still throws", async () => {
+  test("the default type with no loadable manifest logs an error and changes nothing", async () => {
     const registry = fakeRegistry({});
-    const { prisma } = makeFakePrisma({
-      specialty: resolveDefaultSpecialtyName(),
+    const { prisma, rows } = makeFakePrisma({
+      specialty: "specialist",
+      existing: [{ id: "sys-1", name: "old-system", system: true }],
     });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
       undefined,
       registry,
     );
+    const original = console.error;
+    console.error = () => {};
+    try {
+      expect(await service.reconcileSystemCrons("agent-1")).toEqual({
+        created: 0,
+        updated: 0,
+        deleted: 0,
+      });
+    } finally {
+      console.error = original;
+    }
+    expect(Array.from(rows.keys())).toEqual(["sys-1"]);
+  });
 
-    await expect(service.reconcileSystemCrons("agent-1")).rejects.toThrow(
-      resolveDefaultSpecialtyName(),
+  test("a valid non-coding manifest reconciles normally", async () => {
+    const registry = fakeRegistry({ specialist: [loopCron] });
+    const { prisma, rows } = makeFakePrisma({ specialty: "specialist" });
+    const service = new AgentCronJobService(
+      prisma as unknown as PrismaClient,
+      undefined,
+      registry,
     );
+
+    const result = await service.reconcileSystemCrons("agent-1");
+
+    expect(result.created).toBe(1);
+    expect(registry.lookups).toEqual(["specialist"]);
+    expect(Array.from(rows.values())[0]?.name).toBe("shipwright-loop");
   });
+});
 
-  test("the default-manifest failure names the env vars that configure it", async () => {
-    const registry = fakeRegistry({});
-    const { prisma } = makeFakePrisma({
-      specialty: resolveDefaultSpecialtyName(),
-    });
+describe("reconcileSystemCrons (specialtyDefaults hook)", () => {
+  const extCron = {
+    name: "ext-cron",
+    schedule: "*/5 * * * *",
+    prompt: "/ext",
+    enabled: false,
+  };
+
+  test("hook crons win over the manifest and the manifest is not consulted", async () => {
+    const registry = fakeRegistry({ coding: [loopCron] });
+    const { prisma, rows } = makeFakePrisma({ specialty: "coding" });
+    const service = new AgentCronJobService(
+      prisma as unknown as PrismaClient,
+      undefined,
+      registry,
+      (specialty) =>
+        specialty === "coding" ? { crons: [extCron] } : undefined,
+    );
+
+    const result = await service.reconcileSystemCrons("agent-1");
+
+    expect(result.created).toBe(1);
+    expect(registry.lookups).toEqual([]);
+    const [row] = Array.from(rows.values());
+    expect(row?.name).toBe("ext-cron");
+    expect(row?.enabled).toBe(false);
+  });
+
+  test("hook returning nothing falls back to the manifest", async () => {
+    const registry = fakeRegistry({ coding: [loopCron] });
+    const { prisma, rows } = makeFakePrisma({ specialty: "coding" });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
       undefined,
       registry,
+      () => undefined,
     );
 
-    await expect(service.reconcileSystemCrons("agent-1")).rejects.toThrow(
-      /SHIPWRIGHT_SPECIALTIES_DIR.*SHIPWRIGHT_DEFAULT_AGENT_TYPE/s,
+    await service.reconcileSystemCrons("agent-1");
+
+    expect(Array.from(rows.values()).map((r) => r.name)).toEqual([
+      "shipwright-loop",
+    ]);
+  });
+
+  test("defaults without crons fall back to the manifest crons", async () => {
+    const registry = fakeRegistry({ coding: [loopCron] });
+    const { prisma, rows } = makeFakePrisma({ specialty: "coding" });
+    const service = new AgentCronJobService(
+      prisma as unknown as PrismaClient,
+      undefined,
+      registry,
+      () => ({ tools: ["Read"] }),
     );
+
+    await service.reconcileSystemCrons("agent-1");
+
+    expect(Array.from(rows.values()).map((r) => r.name)).toEqual([
+      "shipwright-loop",
+    ]);
   });
 
-  test("a valid non-coding manifest reconciles normally", async () => {
-    const registry = fakeRegistry({ specialist: [loopCron] });
-    const { prisma, rows } = makeFakePrisma({ specialty: "specialist" });
+  test("reconciles hook crons without any manifest for the specialty", async () => {
+    const registry = fakeRegistry({});
+    const { prisma, rows } = makeFakePrisma({ specialty: "ext-only" });
     const service = new AgentCronJobService(
       prisma as unknown as PrismaClient,
       undefined,
       registry,
+      () => ({ crons: [extCron] }),
     );
 
     const result = await service.reconcileSystemCrons("agent-1");
 
     expect(result.created).toBe(1);
-    expect(registry.lookups).toEqual(["specialist"]);
-    expect(Array.from(rows.values())[0]?.name).toBe("shipwright-loop");
+    expect(Array.from(rows.values())[0]?.name).toBe("ext-cron");
+  });
+
+  test("preserves row id and enabled state, links parents, and deletes orphans", async () => {
+    const registry = fakeRegistry({});
+    const { prisma, rows } = makeFakePrisma({
+      specialty: "coding",
+      existing: [
+        { id: "stable-id", name: "ext-cron", enabled: true },
+        { id: "orphan", name: "removed-cron" },
+      ],
+    });
+    const service = new AgentCronJobService(
+      prisma as unknown as PrismaClient,
+      undefined,
+      registry,
+      () => ({
+        crons: [
+          extCron,
+          {
+            name: "ext-child",
+            schedule: "* * * * *",
+            prompt: "/c",
+            parentCron: "ext-cron",
+          },
+        ],
+      }),
+    );
+
+    const result = await service.reconcileSystemCrons("agent-1");
+
+    expect(result).toEqual({ created: 1, updated: 1, deleted: 1 });
+    expect(rows.get("stable-id")?.enabled).toBe(true);
+    expect(rows.has("orphan")).toBe(false);
+    const child = Array.from(rows.values()).find((r) => r.name === "ext-child");
+    expect(child?.parentCronId).toBe("stable-id");
+    expect(child?.enabled).toBe(true);
   });
 });

package/src/agents-api.ts

@@ -156,6 +156,7 @@ import {
   UpsertChatTokenDailyBodySchema,
 } from "./openapi-schemas.ts";
 import type { SelfServeConfig } from "./self-serve-config.ts";
+import type { SpecialtyDefaultsResolver } from "./specialty-defaults.ts";
 import type { SpecialtyManifestResolver } from "./specialty-manifest-loader.ts";
 import { managedReconcileTargets } from "./startup-policy-reconcile.ts";
 
@@ -225,6 +226,8 @@ export interface AdminDeps {
    * Required (not optional) because the route needs it unconditionally.
    */
   specialtyRegistry: SpecialtyManifestResolver;
+  /** Extension-supplied specialty defaults, consulted before the manifest. */
+  specialtyDefaults?: SpecialtyDefaultsResolver;
   agentChatTokenService: Pick<
     AgentChatTokenService,
     "upsertDailyByModel" | "queryStats"
@@ -1522,6 +1525,7 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
     agentPluginService,
     agentMemberService,
     specialtyRegistry,
+    specialtyDefaults,
     agentChatTokenService,
     agentGitHubInstallationsService,
     prisma,
@@ -1930,7 +1934,7 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
     // SSP-4.2: platform admins keep today's behavior (and may create
     // unassigned agents). A session user with an account (flag on) may create
     // agents in THEIR account only: accountId comes from the resolved scope —
-    // never the body — and the type is forced to "coding".
+    // never the body — and the type is forced to the self-serve specialty.
     let accountId: string | undefined;
     if (c.get("isAdmin") !== true) {
       const email = c.get("callerEmail");
@@ -1965,6 +1969,7 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
         agentCronJobService,
         provisioner,
         specialtyRegistry,
+        specialtyDefaults,
         anthropicFederationEnabled: deps.anthropicFederationEnabled,
       },
       {

package/src/agents.ts

@@ -23,6 +23,7 @@ import {
   type SpecialtyManifestResolver,
   SpecialtyRegistry,
 } from "./specialty-manifest-loader.ts";
+import type { SpecialtyDefaultsResolver } from "./specialty-defaults.ts";
 import { ANTHROPIC_CREDENTIALS_BLOCKED_CODE } from "./anthropic-credential-guard.ts";
 import type { PrismaTransactionClient } from "./prisma-tx.ts";
 
@@ -784,6 +785,8 @@ export interface CreateAgentDeps {
   agentCronJobService: Pick<AgentCronJobService, "reconcileSystemCrons">;
   provisioner: Pick<AgentProvisioner, "canProvision" | "provision">;
   specialtyRegistry: Pick<SpecialtyManifestResolver, "tryGetManifest">;
+  /** Extension-supplied tools/plugins, consulted before the manifest's. */
+  specialtyDefaults?: SpecialtyDefaultsResolver;
   /** WIF-2.1: Anthropic federation is enabled; defaults to false. */
   anthropicFederationEnabled?: boolean;
 }
@@ -878,7 +881,10 @@ export async function createAgent(
   const manifest = specialty
     ? deps.specialtyRegistry.tryGetManifest(specialty)
     : undefined;
-  if (!specialty || !manifest) {
+  const extensionDefaults = specialty
+    ? deps.specialtyDefaults?.(specialty)
+    : undefined;
+  if (!specialty || (!manifest && !extensionDefaults)) {
     return { ok: false, errorCode: "invalid_type" };
   }
 
@@ -940,10 +946,14 @@ export async function createAgent(
       // handling below, and the manifest's members/repos arrays are empty
       // for every specialty that exists today.
       try {
-        for (const pattern of manifest.tools) {
+        for (const pattern of extensionDefaults?.tools ??
+          manifest?.tools ??
+          []) {
           await deps.agentToolService.add(agent.id, pattern, tx);
         }
-        for (const pluginName of manifest.plugins) {
+        for (const pluginName of extensionDefaults?.plugins ??
+          manifest?.plugins ??
+          []) {
           await deps.agentPluginService.add(
             agent.id,
             pluginName,

package/src/agents.unit.test.ts

@@ -1319,6 +1319,76 @@ function baseCreateAgentInput(
   };
 }
 
+describe("createAgent() specialtyDefaults hook", () => {
+  it("seeds tools and plugins from the hook instead of the manifest", async () => {
+    const { deps, calls } = makeCreateAgentHarness();
+    deps.specialtyDefaults = () => ({
+      tools: ["Grep"],
+      plugins: ["ext-plugin"],
+    });
+
+    const result = await createAgent(deps, baseCreateAgentInput());
+
+    expect(result.ok).toBe(true);
+    expect(calls.toolsAdded.map((t) => t.pattern)).toEqual(["Grep"]);
+    expect(calls.pluginsAdded.map((p) => p.name)).toEqual(["ext-plugin"]);
+  });
+
+  it("falls back to the manifest when the hook returns nothing", async () => {
+    const { deps, calls } = makeCreateAgentHarness();
+    deps.specialtyDefaults = () => undefined;
+
+    await createAgent(deps, baseCreateAgentInput());
+
+    expect(calls.toolsAdded.map((t) => t.pattern)).toEqual(
+      CODING_MANIFEST.tools,
+    );
+    expect(calls.pluginsAdded.map((p) => p.name)).toEqual(
+      CODING_MANIFEST.plugins,
+    );
+  });
+
+  it("falls back per field when the hook omits tools or plugins", async () => {
+    const { deps, calls } = makeCreateAgentHarness();
+    deps.specialtyDefaults = () => ({ plugins: ["ext-plugin"] });
+
+    await createAgent(deps, baseCreateAgentInput());
+
+    expect(calls.toolsAdded.map((t) => t.pattern)).toEqual(
+      CODING_MANIFEST.tools,
+    );
+    expect(calls.pluginsAdded.map((p) => p.name)).toEqual(["ext-plugin"]);
+  });
+
+  it("accepts a specialty known only to the hook", async () => {
+    const { deps, calls } = makeCreateAgentHarness();
+    deps.specialtyDefaults = (s) =>
+      s === "ext-only" ? { tools: ["Read"] } : undefined;
+
+    const result = await createAgent(
+      deps,
+      baseCreateAgentInput({ specialty: "ext-only" }),
+    );
+
+    expect(result.ok).toBe(true);
+    expect(calls.toolsAdded.map((t) => t.pattern)).toEqual(["Read"]);
+    expect(calls.pluginsAdded).toEqual([]);
+  });
+
+  it("still rejects a specialty unknown to both hook and manifest", async () => {
+    const { deps, calls } = makeCreateAgentHarness();
+    deps.specialtyDefaults = () => undefined;
+
+    const result = await createAgent(
+      deps,
+      baseCreateAgentInput({ specialty: "nope" }),
+    );
+
+    expect(result).toEqual({ ok: false, errorCode: "invalid_type" });
+    expect(calls.created).toHaveLength(0);
+  });
+});
+
 describe("createAgent()", () => {
   it("passes accountId through to agentService.create and tolerates an undefined tx (SSP-4.1)", async () => {
     const { deps, calls } = makeCreateAgentHarness();

package/src/specialty-defaults.ts

@@ -0,0 +1,35 @@
+/**
+ * admin/src/specialty-defaults.ts
+ *
+ * The shape of a specialty's default crons, tools and plugins as supplied by
+ * an AdminExtension's specialtyDefaults() hook (admin-extension.ts). The cron
+ * reconcile (agent-cron-jobs.ts) and create-time seeding (agents.ts) consult
+ * the hook first and fall back to the specialty manifest when it returns
+ * nothing. Kept in its own module so those services can name the types without
+ * importing admin-extension.ts.
+ */
+
+/** A default cron template; same fields as a manifest cron, defaults optional. */
+export interface SpecialtyDefaultCron {
+  name: string;
+  schedule: string;
+  prompt: string;
+  preCheck?: string;
+  silent?: boolean;
+  /** Initial enabled state for a newly created row; defaults to true. */
+  enabled?: boolean;
+  /** Name of another cron in this same list. */
+  parentCron?: string;
+}
+
+/** Any field left undefined falls back to the manifest for that field. */
+export interface SpecialtyDefaults {
+  crons?: readonly SpecialtyDefaultCron[];
+  tools?: readonly string[];
+  plugins?: readonly string[];
+}
+
+/** Resolves a specialty name to extension-supplied defaults, if any. */
+export type SpecialtyDefaultsResolver = (
+  specialty: string,
+) => SpecialtyDefaults | undefined;

package/src/specialty-manifest-loader.fixture.integration.test.ts

@@ -50,13 +50,17 @@ describe("SpecialtyRegistry with the fixture specialty", () => {
     expect(fixtureRegistry().tryGetManifest("renamed-type")).toBeUndefined();
   });
 
-  it("fails with an actionable error when the default specialty is not on disk", () => {
+  it("warns and returns an empty-crons manifest when the default specialty is not on disk", () => {
+    const warnings: string[] = [];
     const registry = new SpecialtyRegistry({
       typesDir: FIXTURE_SPECIALTIES_DIR,
       defaultTypeName: "not-there",
-      warn: () => {},
+      warn: (m) => warnings.push(m),
     });
-    expect(() => registry.getManifest("fixture-or-anything")).toThrow(
+    const manifest = registry.getManifest("fixture-or-anything");
+    expect(manifest.crons).toEqual([]);
+    expect(manifest.plugins).toEqual([]);
+    expect(warnings.join("\n")).toMatch(
       /SHIPWRIGHT_SPECIALTIES_DIR.*SHIPWRIGHT_DEFAULT_AGENT_TYPE/s,
     );
   });

package/src/specialty-manifest-loader.ts

@@ -2,24 +2,25 @@
  * admin/src/specialty-manifest-loader.ts
  *
  * SpecialtyRegistry — resolves an agent's stored `specialty` to its parsed
- * Specialty manifest by loading `specialties/{specialty}/manifest.yaml` from
- * disk (relative to the repo root) and validating it via
+ * Specialty manifest by loading `{typesDir}/{specialty}/manifest.yaml` from
+ * disk (typesDir defaults to the shipped agent-types/) and validating it via
  * parseSpecialtyManifest().
  *
  * This is the runtime source of truth for an agent's default system crons
  * (and, in time, its default plugins/tools/env contract). It replaces the
  * former hardcoded SYSTEM_CRONS array in admin/src/system-crons.ts.
  *
- * Fallback contract: an unknown `specialty` (a value with no matching
- * directory under specialties/) resolves to the "coding" manifest with a
- * logged warning — never throws. This keeps the boot-path
- * POST /agents/:id/crons/reconcile route from beginning to 5xx for an agent
- * whose type was renamed or removed.
+ * Defaults: the default type is `specialist` and the type directory is the
+ * shipped `agent-types/` (both resolved by @app-vitals/agent-lib/default-specialty,
+ * the single shared helper; SHIPWRIGHT_DEFAULT_AGENT_TYPE /
+ * SHIPWRIGHT_SPECIALTIES_DIR override them).
  *
- * Hard-failure contract: if the "coding" manifest itself (the universal
- * fallback) cannot be loaded or fails validation, that is a configuration error
- * (it names SHIPWRIGHT_SPECIALTIES_DIR / SHIPWRIGHT_DEFAULT_AGENT_TYPE) and the error propagates — we never silently degrade the fallback into a
- * no-op that would strip every agent's system crons.
+ * Fallback contract: getManifest() never throws. An unknown `specialty` (no
+ * matching directory under the type dir) resolves to the default type's
+ * manifest with a logged warning. If even the default cannot be loaded (bad
+ * env override, missing/invalid manifest) it warns and returns a built-in
+ * minimal manifest with no crons/plugins, so the boot-path
+ * POST /agents/:id/crons/reconcile route never 5xxs over configuration.
  *
  * The class takes an injectable reader/warner so unit tests can drive it
  * without touching the filesystem (see agent-cron-jobs.unit.test.ts).
@@ -28,12 +29,47 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
-  type SpecialtyManifest,
+  DEFAULT_SPECIALTY_NAME,
+  resolveDefaultSpecialtyName,
+  resolveSpecialtiesDir,
+} from "@app-vitals/agent-lib/default-specialty";
+import {
   parseSpecialtyManifest,
+  type SpecialtyManifest,
 } from "./specialty-registry.ts";
 
-/** The universal fallback type — every agent degrades to this manifest. */
-export const DEFAULT_SPECIALTY_NAME = "coding";
+export {
+  DEFAULT_SPECIALTY_NAME,
+  resolveDefaultSpecialtyName,
+  resolveSpecialtiesDir,
+};
+
+/**
+ * Built-in last-resort manifest: used only when the default type itself cannot
+ * be loaded. Declares nothing (no crons, plugins, tools) so it never seeds
+ * anything unexpected.
+ */
+const BUILT_IN_FALLBACK_MANIFEST_YAML = `apiVersion: shipwright.dev/v1alpha1
+kind: Specialty
+metadata:
+  name: ${DEFAULT_SPECIALTY_NAME}
+  displayName: Specialist Agent
+  description: Built-in fallback used when the default specialty manifest cannot be loaded.
+  version: 0.0.0
+  skills: []
+identity:
+  templatesDir: workspace/
+crons: []
+plugins: []
+tools: []
+env:
+  required: []
+  optional: []
+members: []
+repos: []
+chat: true
+voice: true
+`;
 
 /** Reads a manifest's raw YAML text for a type; throws if it does not exist. */
 type ManifestReader = (specialty: string) => string;
@@ -54,51 +90,6 @@ export interface SpecialtyOption {
   displayName: string;
 }
 
-/**
- * Repo root resolved relative to this module (admin/src/ → ../../). The
- * specialties/ directory lives at the repo root alongside admin/.
- */
-const REPO_ROOT = join(import.meta.dir, "..", "..");
-const BUILT_IN_SPECIALTIES_DIR = join(REPO_ROOT, "specialties");
-
-/**
- * The specialties directory: SHIPWRIGHT_SPECIALTIES_DIR when set, else the
- * repo-root specialties/ (today's location).
- */
-export function resolveSpecialtiesDir(
-  env: Record<string, string | undefined> = process.env,
-): string {
-  return env.SHIPWRIGHT_SPECIALTIES_DIR || BUILT_IN_SPECIALTIES_DIR;
-}
-
-/**
- * The universal fallback type: SHIPWRIGHT_DEFAULT_AGENT_TYPE when set, else
- * "coding".
- */
-/**
- * The actionable error for a default specialty that cannot be loaded. The
- * platform ships no specialty of its own, so this is a configuration problem:
- * the operator must point the two env vars at a real specialties directory.
- */
-export function missingDefaultSpecialtyError(
-  defaultTypeName: string,
-  typesDir: string,
-  cause?: unknown,
-): Error {
-  const detail = cause instanceof Error ? ` (${cause.message})` : "";
-  return new Error(
-    `SpecialtyRegistry: the default specialty "${defaultTypeName}" could not be loaded from "${typesDir}"${detail}. ` +
-      "Set SHIPWRIGHT_SPECIALTIES_DIR to a directory containing <type>/manifest.yaml and " +
-      "SHIPWRIGHT_DEFAULT_AGENT_TYPE to the name of a specialty in it.",
-  );
-}
-
-export function resolveDefaultSpecialtyName(
-  env: Record<string, string | undefined> = process.env,
-): string {
-  return env.SHIPWRIGHT_DEFAULT_AGENT_TYPE || DEFAULT_SPECIALTY_NAME;
-}
-
 /** Default reader: loads {typesDir}/{specialty}/manifest.yaml from disk. */
 export function defaultManifestReader(
   specialty: string,
@@ -122,18 +113,19 @@ export function defaultTypeDirLister(
  */
 export interface SpecialtyManifestResolver {
   /**
-   * Resolve `specialty` to its parsed manifest. Falls back to the "coding"
-   * manifest (with a warning) when the type is unknown. Never throws for an
-   * unknown type — only if the "coding" fallback itself fails to load.
+   * Resolve `specialty` to its parsed manifest. Falls back to the default
+   * type's manifest (with a warning) when the type is unknown, and to a
+   * built-in empty-crons manifest (with a warning) if the default cannot load
+   * either. Never throws.
    */
   getManifest(specialty: string): SpecialtyManifest;
   /**
    * Resolve `specialty` to its parsed manifest WITHOUT falling back to
-   * "coding" — returns undefined for an unknown type instead. No warning is
+   * the default type — returns undefined for an unknown type instead. No warning is
    * logged (an unknown type here is an expected, callers-handle-it outcome,
    * not a degraded-boot condition). Used by POST /admin/agents to reject an
    * unknown requested `type` with 400 rather than silently seeding a
-   * "coding" agent under a different label.
+   * default-type agent under a different label.
    */
   tryGetManifest(specialty: string): SpecialtyManifest | undefined;
   /**
@@ -157,8 +149,8 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
 
   /**
    * `typesDir` and `defaultTypeName` default to SHIPWRIGHT_SPECIALTIES_DIR /
-   * SHIPWRIGHT_DEFAULT_AGENT_TYPE, then to today's repo-root specialties/
-   * and "coding". An injected `read`/`list` takes precedence over `typesDir`.
+   * SHIPWRIGHT_DEFAULT_AGENT_TYPE, then to the shipped agent-types/
+   * and "specialist". An injected `read`/`list` takes precedence over `typesDir`.
    */
   constructor(
     opts: {
@@ -179,33 +171,29 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
   }
 
   getManifest(specialty: string): SpecialtyManifest {
-    const resolved = this.tryLoad(specialty);
+    const resolved = this.tryLoadSafe(specialty);
     if (resolved) return resolved;
 
-    // Unknown type — warn once and fall back to "coding". The fallback load is
-    // deliberately NOT wrapped in tryLoad: if "coding" can't load, that's a
-    // hard startup bug and must surface, not silently become a no-op.
     this.warn(
       `SpecialtyRegistry: unknown agent specialty "${specialty}" — ` +
         `falling back to "${this.defaultTypeName}" manifest`,
     );
-    if (specialty === this.defaultTypeName) {
-      // Guard against infinite intent: the default itself failed to load.
-      throw missingDefaultSpecialtyError(this.defaultTypeName, this.typesDir);
-    }
-    try {
-      return this.loadOrThrow(this.defaultTypeName);
-    } catch (err) {
-      throw missingDefaultSpecialtyError(
-        this.defaultTypeName,
-        this.typesDir,
-        err,
-      );
+    if (specialty !== this.defaultTypeName) {
+      const fallback = this.tryLoadSafe(this.defaultTypeName);
+      if (fallback) return fallback;
     }
+    // Even the default is unloadable (bad SHIPWRIGHT_SPECIALTIES_DIR /
+    // SHIPWRIGHT_DEFAULT_AGENT_TYPE override). Degrade to an empty manifest
+    // rather than failing boot; the warning names the knobs to fix.
+    this.warn(
+      `SpecialtyRegistry: the default specialty "${this.defaultTypeName}" could not be loaded from "${this.typesDir}" — ` +
+        "using a built-in manifest with no crons. Check SHIPWRIGHT_SPECIALTIES_DIR and SHIPWRIGHT_DEFAULT_AGENT_TYPE.",
+    );
+    return parseSpecialtyManifest(BUILT_IN_FALLBACK_MANIFEST_YAML);
   }
 
   /**
-   * Resolve `specialty` without falling back to "coding" — see the interface
+   * Resolve `specialty` without falling back to the default type — see the interface
    * doc comment. Thin public wrapper around the existing tryLoad() used
    * internally by getManifest().
    */
@@ -227,6 +215,15 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
     return options;
   }
 
+  /** tryLoad, but an invalid (unparseable) manifest also yields undefined. */
+  private tryLoadSafe(specialty: string): SpecialtyManifest | undefined {
+    try {
+      return this.tryLoad(specialty);
+    } catch {
+      return undefined;
+    }
+  }
+
   /** Load + cache a manifest, returning undefined only if the file is missing. */
   private tryLoad(specialty: string): SpecialtyManifest | undefined {
     const cached = this.cache.get(specialty);
@@ -240,13 +237,6 @@ export class SpecialtyRegistry implements SpecialtyManifestResolver {
     return this.parseAndCache(specialty, raw);
   }
 
-  /** Load + cache a manifest, propagating any read/parse error. */
-  private loadOrThrow(specialty: string): SpecialtyManifest {
-    const cached = this.cache.get(specialty);
-    if (cached) return cached;
-    return this.parseAndCache(specialty, this.read(specialty));
-  }
-
   private parseAndCache(specialty: string, raw: string): SpecialtyManifest {
     const manifest = parseSpecialtyManifest(raw);
     this.cache.set(specialty, manifest);