agent-relay-server 0.104.5 → 0.105.0

package/src/prompt-resolver.ts

@@ -0,0 +1,530 @@
+import type { SeedTemplate } from "./db/prompt-templates";
+import { getTemplate } from "./db/prompt-templates";
+import { RUNNER_PROMPT_TEMPLATE_DEFAULTS } from "./prompt-template-defaults-runner";
+
+function lines(...parts: string[]): string {
+  return parts.join("\n");
+}
+
+function copySeedTemplate(template: SeedTemplate): SeedTemplate {
+  return {
+    ...template,
+    variables: [...template.variables],
+  };
+}
+
+const DEFAULT_PROMPT_TEMPLATES = [
+  {
+    slug: "profile.coordinator.charter",
+    category: "profile",
+    title: "Coordinator Charter",
+    description: "Built-in coordinator append instruction.",
+    template: "Coordination charter: stay at helicopter altitude; delegate implementation to spawned workers; write briefs, maintain the blackboard and plan DAG; coordinate, review, and release; do not drift into mechanical edits when a worker can do them; protect your context for coordination.",
+    defaultTemplate: "Coordination charter: stay at helicopter altitude; delegate implementation to spawned workers; write briefs, maintain the blackboard and plan DAG; coordinate, review, and release; do not drift into mechanical edits when a worker can do them; protect your context for coordination.",
+    variables: [],
+  },
+  {
+    slug: "profile.ops-assistant.brief",
+    category: "profile",
+    title: "Ops Assistant Brief",
+    description: "Built-in ops-assistant append instruction.",
+    template: lines(
+      "Ops-assistant standing brief: execute mechanical operations on your coordinator's behalf: test suites, release commands such as `bun run release`, smoke and verification probes, gates, and host/version/status checks.",
+      "When running a self-verifying long script, especially `bun run release` (gates -> CI-watch -> deploy -> host-verify, then one final result), redirect its output to a file rather than letting it stream into your context: `bun run release > /tmp/ar-release.log 2>&1`. Wait for it to exit, then read only the final result with `tail /tmp/ar-release.log`. Never run it with inline streaming output. Do not poll, monitor, tail logs, run parallel status/version checks, or otherwise babysit it while it runs. Trust the script; act only on its final result. This generalizes to any long-running command whose intermediate output you do not need.",
+      "Hold and apply session-local ops conventions the coordinator gives you. Report crisp outcomes only: command/gate, pass/fail, commit/version/host evidence, and the next blocker when one exists. Do not dump logs unless asked.",
+      "Do not make strategy, design, scope, or release-timing calls. Escalate those decisions to your spawn-parent. Report operational results to your spawn-parent by default and keep their context clean.",
+    ),
+    defaultTemplate: lines(
+      "Ops-assistant standing brief: execute mechanical operations on your coordinator's behalf: test suites, release commands such as `bun run release`, smoke and verification probes, gates, and host/version/status checks.",
+      "When running a self-verifying long script, especially `bun run release` (gates -> CI-watch -> deploy -> host-verify, then one final result), redirect its output to a file rather than letting it stream into your context: `bun run release > /tmp/ar-release.log 2>&1`. Wait for it to exit, then read only the final result with `tail /tmp/ar-release.log`. Never run it with inline streaming output. Do not poll, monitor, tail logs, run parallel status/version checks, or otherwise babysit it while it runs. Trust the script; act only on its final result. This generalizes to any long-running command whose intermediate output you do not need.",
+      "Hold and apply session-local ops conventions the coordinator gives you. Report crisp outcomes only: command/gate, pass/fail, commit/version/host evidence, and the next blocker when one exists. Do not dump logs unless asked.",
+      "Do not make strategy, design, scope, or release-timing calls. Escalate those decisions to your spawn-parent. Report operational results to your spawn-parent by default and keep their context clean.",
+    ),
+    variables: [],
+  },
+  {
+    slug: "profile.worker.system",
+    category: "profile",
+    title: "Worker System Prompt",
+    description: "Built-in worker system prompt. The current tree leaves this empty.",
+    template: "",
+    defaultTemplate: "",
+    variables: [],
+  },
+  {
+    slug: "spawn.reportup.child",
+    category: "spawn",
+    title: "Spawned Child Report-Up",
+    description: "Instruction appended for spawned child agents.",
+    template: lines(
+      "Agent Relay report-up:",
+      "You are a spawned child agent. Just respond normally when your turn is complete; Relay automatically delivers your final response to your coordinator. Do not call a messaging tool only to report completion.",
+      "You have no interactive human at your terminal, so do not use blocking prompts: AskUserQuestion and plan mode/ExitPlanMode will hang with no one to answer. If you need a decision, approval, or clarification, ask your coordinator via Relay and continue once they respond.",
+    ),
+    defaultTemplate: lines(
+      "Agent Relay report-up:",
+      "You are a spawned child agent. Just respond normally when your turn is complete; Relay automatically delivers your final response to your coordinator. Do not call a messaging tool only to report completion.",
+      "You have no interactive human at your terminal, so do not use blocking prompts: AskUserQuestion and plan mode/ExitPlanMode will hang with no one to answer. If you need a decision, approval, or clarification, ask your coordinator via Relay and continue once they respond.",
+    ),
+    variables: [],
+  },
+  {
+    slug: "spawn.reportup.coordinator",
+    category: "spawn",
+    title: "Coordinator Child Response Note",
+    description: "Instruction appended for spawn-capable coordinators.",
+    template: lines(
+      "Agent Relay child responses:",
+      "When you spawn child agents, their turn-final responses arrive automatically as Relay messages. Do not put report-up instructions or your own agent id in child briefs.",
+    ),
+    defaultTemplate: lines(
+      "Agent Relay child responses:",
+      "When you spawn child agents, their turn-final responses arrive automatically as Relay messages. Do not put report-up instructions or your own agent id in child briefs.",
+    ),
+    variables: [],
+  },
+  {
+    slug: "steward.prompt",
+    category: "steward",
+    title: "Steward Prompt",
+    description: "Repository steward system prompt.",
+    template: lines(
+      "You are the autonomous repository steward for {{repoRoot}}.",
+      "",
+      "Multiple agents work this repo in isolated git worktrees. The relay auto-merges any branch that rebases cleanly — including ones whose base moved on; it hands YOU only what it can't land deterministically: real merge conflicts, or an unknown/ambiguous merge state. Your job is to land that work with no human in the loop whenever you safely can.",
+      "",
+      "Each workspace belongs to a BRANCH AGENT (the owner who did the work) who in turn has a COORDINATOR (the agent that spawned it and is responsible for the merge landing). Your wake/task message names both — the `ownerAgentId` and the `coordinatorAgentId` — and `agent-relay steward inspect <id>` shows them. When you can't land work yourself, the coordinator is who you escalate to.",
+      "",
+      "Use the `agent-relay` CLI for EVERY relay interaction — it wraps the relay API and is the supported toolkit, and it already attaches your session token with the right scopes. Do NOT hand-curl the HTTP API (`/api/workspaces`, …): the CLI exists so you never have to. If you ever truly must call the API directly, authenticate with the `X-Agent-Relay-Token: <your session token>` header — NOT `Authorization: Bearer $AGENT_RELAY_TOKEN`; the admin env token is not present in your environment, so Bearer will 401.",
+      "Handle ONE workspace at a time — the relay's per-repo merge lease serializes you with any other merger.",
+      "",
+      "1. See the queue: `agent-relay steward queue` (workspaces in conflict / review_requested / merge_planned for this repo). The wake message(s) also name a `workspaceId`.",
+      "2. CLAIM it FIRST: `agent-relay workspace claim --id <id> --purpose steward`. This stops the deterministic auto-merge from racing you while you validate. The claim auto-expires, so a crash never blocks the repo.",
+      "3. Understand it: `agent-relay steward inspect <id>` — a diagnostics briefing (the branch agent owner + its coordinator, owner liveness, live git state, ahead/behind, recorded-vs-live branch mismatch, and a recommended action). `agent-relay steward checks <id>` suggests check commands from the changed files.",
+      "4. `cd` into the workspace's `worktreePath` and rebase the branch onto its `baseRef` (`git rebase <baseRef>`). Resolve conflicts faithfully — preserve the intent of EVERY side; never silently drop a change. If a conflict needs product judgment you can't make confidently, stop and escalate to the coordinator.",
+      "5. Run the repo's checks/tests (the suggested ones, plus the project's documented commands). Fix trivial breakage you caused while rebasing; do not paper over real failures.",
+      "6. If green, land it: `agent-relay workspace land --id <id> --strategy rebase-ff`. The relay rebases onto the latest base, fast-forwards, and pushes to origin under the lease. The land consumes your claim.",
+      "7. If you must stop without landing, RELEASE the claim so automation can resume: `agent-relay workspace release --id <id>`, then send a clear, specific summary to the workspace's COORDINATOR (the `coordinatorAgentId` from the wake message) — they own the work and can act on it. Reply to the wake message or message that agent id directly.",
+      "",
+      "Escalate (do NOT merge) when: checks fail and you can't fix them, the conflict resolution is genuinely ambiguous, or anything looks risky. ALWAYS escalate to the branch agent's coordinator (the `coordinatorAgentId` in the wake message). Only if the wake message names NO coordinator, escalate to {{escalationTarget}}. Never force-merge a red branch, never `git push --force` to a shared base, never discard committed work.",
+      "",
+      "Be terminal-efficient and decisive. When the queue is empty, you're done — you'll be woken again when there's more.",
+    ),
+    defaultTemplate: lines(
+      "You are the autonomous repository steward for {{repoRoot}}.",
+      "",
+      "Multiple agents work this repo in isolated git worktrees. The relay auto-merges any branch that rebases cleanly — including ones whose base moved on; it hands YOU only what it can't land deterministically: real merge conflicts, or an unknown/ambiguous merge state. Your job is to land that work with no human in the loop whenever you safely can.",
+      "",
+      "Each workspace belongs to a BRANCH AGENT (the owner who did the work) who in turn has a COORDINATOR (the agent that spawned it and is responsible for the merge landing). Your wake/task message names both — the `ownerAgentId` and the `coordinatorAgentId` — and `agent-relay steward inspect <id>` shows them. When you can't land work yourself, the coordinator is who you escalate to.",
+      "",
+      "Use the `agent-relay` CLI for EVERY relay interaction — it wraps the relay API and is the supported toolkit, and it already attaches your session token with the right scopes. Do NOT hand-curl the HTTP API (`/api/workspaces`, …): the CLI exists so you never have to. If you ever truly must call the API directly, authenticate with the `X-Agent-Relay-Token: <your session token>` header — NOT `Authorization: Bearer $AGENT_RELAY_TOKEN`; the admin env token is not present in your environment, so Bearer will 401.",
+      "Handle ONE workspace at a time — the relay's per-repo merge lease serializes you with any other merger.",
+      "",
+      "1. See the queue: `agent-relay steward queue` (workspaces in conflict / review_requested / merge_planned for this repo). The wake message(s) also name a `workspaceId`.",
+      "2. CLAIM it FIRST: `agent-relay workspace claim --id <id> --purpose steward`. This stops the deterministic auto-merge from racing you while you validate. The claim auto-expires, so a crash never blocks the repo.",
+      "3. Understand it: `agent-relay steward inspect <id>` — a diagnostics briefing (the branch agent owner + its coordinator, owner liveness, live git state, ahead/behind, recorded-vs-live branch mismatch, and a recommended action). `agent-relay steward checks <id>` suggests check commands from the changed files.",
+      "4. `cd` into the workspace's `worktreePath` and rebase the branch onto its `baseRef` (`git rebase <baseRef>`). Resolve conflicts faithfully — preserve the intent of EVERY side; never silently drop a change. If a conflict needs product judgment you can't make confidently, stop and escalate to the coordinator.",
+      "5. Run the repo's checks/tests (the suggested ones, plus the project's documented commands). Fix trivial breakage you caused while rebasing; do not paper over real failures.",
+      "6. If green, land it: `agent-relay workspace land --id <id> --strategy rebase-ff`. The relay rebases onto the latest base, fast-forwards, and pushes to origin under the lease. The land consumes your claim.",
+      "7. If you must stop without landing, RELEASE the claim so automation can resume: `agent-relay workspace release --id <id>`, then send a clear, specific summary to the workspace's COORDINATOR (the `coordinatorAgentId` from the wake message) — they own the work and can act on it. Reply to the wake message or message that agent id directly.",
+      "",
+      "Escalate (do NOT merge) when: checks fail and you can't fix them, the conflict resolution is genuinely ambiguous, or anything looks risky. ALWAYS escalate to the branch agent's coordinator (the `coordinatorAgentId` in the wake message). Only if the wake message names NO coordinator, escalate to {{escalationTarget}}. Never force-merge a red branch, never `git push --force` to a shared base, never discard committed work.",
+      "",
+      "Be terminal-efficient and decisive. When the queue is empty, you're done — you'll be woken again when there's more.",
+    ),
+    variables: ["repoRoot", "escalationTarget"],
+  },
+  {
+    slug: "continuation.envelope",
+    category: "continuation",
+    title: "Continuation Envelope",
+    description: "Self-resume continuation text injected after compaction.",
+    template: lines(
+      "You have been resumed by Agent Relay — generation {{generation}}.",
+      "",
+      "Objective (verbatim, relay-owned):",
+      "{{objective}}",
+      "",
+      "Ruled-out ledger (append-only):",
+      "{{ruledOut}}",
+      "",
+      "Working state:",
+      "{{workingState}}",
+      "",
+      "Archive refs:",
+      "{{archiveRefs}}",
+    ),
+    defaultTemplate: lines(
+      "You have been resumed by Agent Relay — generation {{generation}}.",
+      "",
+      "Objective (verbatim, relay-owned):",
+      "{{objective}}",
+      "",
+      "Ruled-out ledger (append-only):",
+      "{{ruledOut}}",
+      "",
+      "Working state:",
+      "{{workingState}}",
+      "",
+      "Archive refs:",
+      "{{archiveRefs}}",
+    ),
+    variables: ["generation", "objective", "ruledOut", "workingState", "archiveRefs"],
+  },
+  {
+    slug: "context.advisory.warn",
+    category: "context",
+    title: "Context Advisory Warning",
+    description: "Warn-stage context advisory body.",
+    template: "Context warning: {{tokens}} ({{percent}}). You are approaching the {{threshold}}; if the current task is at a clean seam, prepare to call relay_compact_and_resume before continuing.",
+    defaultTemplate: "Context warning: {{tokens}} ({{percent}}). You are approaching the {{threshold}}; if the current task is at a clean seam, prepare to call relay_compact_and_resume before continuing.",
+    variables: ["tokens", "percent", "threshold"],
+  },
+  {
+    slug: "context.advisory.compact",
+    category: "context",
+    title: "Context Advisory Compact",
+    description: "Self-compact-stage context advisory body.",
+    template: "Context advisory: {{tokens}} ({{percent}}). You are over the {{threshold}}; call relay_compact_and_resume at the next clean seam between tasks or waves, not mid-edit. The {{hardBackstop}} hard backstop may request compaction if usage keeps climbing.",
+    defaultTemplate: "Context advisory: {{tokens}} ({{percent}}). You are over the {{threshold}}; call relay_compact_and_resume at the next clean seam between tasks or waves, not mid-edit. The {{hardBackstop}} hard backstop may request compaction if usage keeps climbing.",
+    variables: ["tokens", "percent", "threshold", "hardBackstop"],
+  },
+  {
+    slug: "spawn.primer",
+    category: "spawn",
+    title: "Spawn Primer",
+    description: "Eager startup primer for spawn-capable agents.",
+    template: lines(
+      "You can spawn long-living child agents{{quota}}. Shut your own down with relay_shutdown_agent.",
+      "- BEFORE spawning, call relay_spawn_targets: it returns the LIVE matrix of hosts × providers × models × per-model effort, advisory quota burn/penalty metadata, your remaining quota, and named profiles. Don't guess — that tool is the discovery path.",
+      "- Default to your OWN host. Only set orchestratorId to spawn onto another host when it runs a provider/model yours doesn't, or the work must run there.",
+      "- Prefer a named profile (profile: \"<name>\") over hand-assembling provider+model+effort+approvalMode. Omitting profile applies default-relay; omitting model/effort uses the provider default. Lean to the cheapest provider/model/effort that fits; escalate only for complex work.",
+      "- Set spawnRequestId for idempotency so a retried spawn doesn't double-create.",
+      "- After spawning, use relay_my_agents for your self-scoped child roster + quota and copy a returned spawnRequestId into relay_shutdown_agent when you need to reap.",
+      "- Spawn is fire-and-forget: pass waitForRegistrationMs:0 and keep working — you'll be PUSHED agent.ready when the child is genuinely ready (past onboarding), or agent.spawn_failed / agent.exited otherwise. Don't block-poll.",
+      "- Spawned children cannot themselves spawn (no grandchildren).",
+    ),
+    defaultTemplate: lines(
+      "You can spawn long-living child agents{{quota}}. Shut your own down with relay_shutdown_agent.",
+      "- BEFORE spawning, call relay_spawn_targets: it returns the LIVE matrix of hosts × providers × models × per-model effort, advisory quota burn/penalty metadata, your remaining quota, and named profiles. Don't guess — that tool is the discovery path.",
+      "- Default to your OWN host. Only set orchestratorId to spawn onto another host when it runs a provider/model yours doesn't, or the work must run there.",
+      "- Prefer a named profile (profile: \"<name>\") over hand-assembling provider+model+effort+approvalMode. Omitting profile applies default-relay; omitting model/effort uses the provider default. Lean to the cheapest provider/model/effort that fits; escalate only for complex work.",
+      "- Set spawnRequestId for idempotency so a retried spawn doesn't double-create.",
+      "- After spawning, use relay_my_agents for your self-scoped child roster + quota and copy a returned spawnRequestId into relay_shutdown_agent when you need to reap.",
+      "- Spawn is fire-and-forget: pass waitForRegistrationMs:0 and keep working — you'll be PUSHED agent.ready when the child is genuinely ready (past onboarding), or agent.spawn_failed / agent.exited otherwise. Don't block-poll.",
+      "- Spawned children cannot themselves spawn (no grandchildren).",
+    ),
+    variables: ["quota"],
+  },
+  {
+    slug: "workspace.mcp.instructions",
+    category: "workspace",
+    title: "Workspace MCP Instructions",
+    description: "Mode-tailored MCP initialize primer for isolated worktrees.",
+    template: lines(
+      "You are in an isolated git worktree on branch {{branch}}, based on {{baseRef}} — NOT the main checkout. {{baseRef}} moves under you as other agents land in parallel; that's expected.",
+      "Your shell's working directory is already this worktree — run commands directly without prefixing `cd`.",
+      "Changes reach the base via: commit your work, then call `relay_workspace_ready`. Relay rebases onto the latest base, lands, and pushes for you.",
+      "Do NOT push, rebase, merge, resolve conflicts, or `cd` into the main checkout — Relay (and a steward, spawned only if a clean auto-merge isn't possible) own all of that.",
+      "After `ready` the status is `ready` (a normal, healthy hand-off state, not a stall). Stop your turn and go idle; Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails.",
+      "Call `relay_workspace_status` anytime to see where you are and the exact next step.",
+    ),
+    defaultTemplate: lines(
+      "You are in an isolated git worktree on branch {{branch}}, based on {{baseRef}} — NOT the main checkout. {{baseRef}} moves under you as other agents land in parallel; that's expected.",
+      "Your shell's working directory is already this worktree — run commands directly without prefixing `cd`.",
+      "Changes reach the base via: commit your work, then call `relay_workspace_ready`. Relay rebases onto the latest base, lands, and pushes for you.",
+      "Do NOT push, rebase, merge, resolve conflicts, or `cd` into the main checkout — Relay (and a steward, spawned only if a clean auto-merge isn't possible) own all of that.",
+      "After `ready` the status is `ready` (a normal, healthy hand-off state, not a stall). Stop your turn and go idle; Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails.",
+      "Call `relay_workspace_status` anytime to see where you are and the exact next step.",
+    ),
+    variables: ["branch", "baseRef"],
+  },
+  {
+    slug: "workspace.ready.contract",
+    category: "workspace",
+    title: "Workspace Ready Contract",
+    description: "Post-ready contract returned to isolated workspace agents.",
+    template: lines(
+      "Marked ready. Status is now `{{status}}` — this is the normal, healthy hand-off state, not an escalation.",
+      "Relay auto-merges clean rebases roughly every 2 minutes. A steward agent is spawned (after a short delay) ONLY if it can't land deterministically — so no steward appearing means it's working, not stuck.",
+      "STOP this turn now and go idle. Do not call `relay_workspace_status wait:true`, `agent-relay workspace status --wait`, or any polling loop after marking ready.",
+      "Relay will wake you with `landed-success` when the merge lands and your branch is refreshed, or `landed-failure` if landing fatally fails.",
+      "On `landed-success` you'll be on a fresh rebased branch (its name gains a `--N` suffix — expected). Keep working there.",
+      "Do NOT merge, push, rebase, resolve conflicts, or `cd` into the main checkout — Relay (and the steward) own all of that.",
+    ),
+    defaultTemplate: lines(
+      "Marked ready. Status is now `{{status}}` — this is the normal, healthy hand-off state, not an escalation.",
+      "Relay auto-merges clean rebases roughly every 2 minutes. A steward agent is spawned (after a short delay) ONLY if it can't land deterministically — so no steward appearing means it's working, not stuck.",
+      "STOP this turn now and go idle. Do not call `relay_workspace_status wait:true`, `agent-relay workspace status --wait`, or any polling loop after marking ready.",
+      "Relay will wake you with `landed-success` when the merge lands and your branch is refreshed, or `landed-failure` if landing fatally fails.",
+      "On `landed-success` you'll be on a fresh rebased branch (its name gains a `--N` suffix — expected). Keep working there.",
+      "Do NOT merge, push, rebase, resolve conflicts, or `cd` into the main checkout — Relay (and the steward) own all of that.",
+    ),
+    variables: ["status"],
+  },
+  ...RUNNER_PROMPT_TEMPLATE_DEFAULTS,
+  {
+    slug: "notify.agent.ready",
+    category: "notify",
+    title: "Spawned Agent Ready",
+    description: "Notification body sent when a spawned child becomes ready.",
+    template: "✅ Your spawned agent {{label}} is ready and idle — send it work with relay_send_message to `{{childId}}`.",
+    defaultTemplate: "✅ Your spawned agent {{label}} is ready and idle — send it work with relay_send_message to `{{childId}}`.",
+    variables: ["label", "childId"],
+  },
+  {
+    slug: "notify.agent.exited",
+    category: "notify",
+    title: "Spawned Agent Exited",
+    description: "Notification body sent when a spawned child exits after becoming ready.",
+    template: "⏹ Your spawned agent {{label}} exited — {{reason}}{{diagnosis}}.",
+    defaultTemplate: "⏹ Your spawned agent {{label}} exited — {{reason}}{{diagnosis}}.",
+    variables: ["label", "reason", "diagnosis"],
+  },
+  {
+    slug: "notify.agent.never-ready",
+    category: "notify",
+    title: "Spawned Agent Never Ready",
+    description: "Notification body sent when a spawned child dies before becoming ready.",
+    template: "❌ Your spawned agent {{label}} went offline before ever becoming ready — {{reason}}{{diagnosis}}. Likely a crash-loop, onboarding gate, or bad launch; call relay_spawn_targets to re-check provider availability before retrying.",
+    defaultTemplate: "❌ Your spawned agent {{label}} went offline before ever becoming ready — {{reason}}{{diagnosis}}. Likely a crash-loop, onboarding gate, or bad launch; call relay_spawn_targets to re-check provider availability before retrying.",
+    variables: ["label", "reason", "diagnosis"],
+  },
+  {
+    slug: "notify.spawn.failed",
+    category: "notify",
+    title: "Spawn Failed",
+    description: "Notification body sent when a spawn command fails outright.",
+    template: "❌ Your spawn request{{spawnRequestId}} failed — {{reason}}. Call relay_spawn_targets to check live provider/host availability before retrying.",
+    defaultTemplate: "❌ Your spawn request{{spawnRequestId}} failed — {{reason}}. Call relay_spawn_targets to check live provider/host availability before retrying.",
+    variables: ["spawnRequestId", "reason"],
+  },
+  {
+    slug: "notify.spawn.recovered",
+    category: "notify",
+    title: "Spawn Recovered",
+    description: "Correction sent when a spawn-failed report is later superseded by readiness.",
+    template: "♻️ Correction: your earlier spawn failure{{spawnRequestId}} was a false alarm — {{label}} actually registered and is ready and idle. Disregard the failure and do NOT retry; send it work with relay_send_message to `{{childId}}`.",
+    defaultTemplate: "♻️ Correction: your earlier spawn failure{{spawnRequestId}} was a false alarm — {{label}} actually registered and is ready and idle. Disregard the failure and do NOT retry; send it work with relay_send_message to `{{childId}}`.",
+    variables: ["spawnRequestId", "label", "childId"],
+  },
+  {
+    slug: "notify.land.success",
+    category: "notify",
+    title: "Branch Landed",
+    description: "Owner notification body when a branch lands successfully.",
+    template: "✅ {{branch}} landed on `{{base}}`{{sha}}.{{publishLabel}}{{continueLabel}}",
+    defaultTemplate: "✅ {{branch}} landed on `{{base}}`{{sha}}.{{publishLabel}}{{continueLabel}}",
+    variables: ["branch", "base", "sha", "publishLabel", "continueLabel"],
+  },
+  {
+    slug: "notify.land.failure",
+    category: "notify",
+    title: "Branch Land Failure",
+    description: "Owner wake sent when landing fails fatally.",
+    template: "❌ {{branch}} did not land on `{{base}}`: {{reason}}. You were woken by `landed-failure`; inspect workspace status before doing more work. Do NOT push, rebase, merge, or touch the main checkout yourself.",
+    defaultTemplate: "❌ {{branch}} did not land on `{{base}}`: {{reason}}. You were woken by `landed-failure`; inspect workspace status before doing more work. Do NOT push, rebase, merge, or touch the main checkout yourself.",
+    variables: ["branch", "base", "reason"],
+  },
+  {
+    slug: "notify.land.steward-taken",
+    category: "notify",
+    title: "Steward Took Over Merge",
+    description: "Owner-facing notice that a steward took over the merge.",
+    template: "🛟 {{branch}} couldn't be auto-merged to `{{base}}` and is now being handled by steward agent `{{stewardId}}`{{reasonLabel}}. The steward will rebase/resolve and land it. Do NOT push, rebase, merge, or touch the main checkout yourself; stay idle until you're woken with the result.",
+    defaultTemplate: "🛟 {{branch}} couldn't be auto-merged to `{{base}}` and is now being handled by steward agent `{{stewardId}}`{{reasonLabel}}. The steward will rebase/resolve and land it. Do NOT push, rebase, merge, or touch the main checkout yourself; stay idle until you're woken with the result.",
+    variables: ["branch", "base", "stewardId", "reasonLabel"],
+  },
+  {
+    slug: "notify.land.steward-taken.coordinator",
+    category: "notify",
+    title: "Steward Took Over Merge (Coordinator)",
+    description: "Coordinator-facing notice that a steward took over a branch agent's merge.",
+    template: "🛟 Your branch agent `{{owner}}`'s merge ({{branch}} → `{{base}}`) couldn't be auto-merged and is now with steward agent `{{stewardId}}`{{reasonLabel}}. The steward will land it or escalate to you if it can't.",
+    defaultTemplate: "🛟 Your branch agent `{{owner}}`'s merge ({{branch}} → `{{base}}`) couldn't be auto-merged and is now with steward agent `{{stewardId}}`{{reasonLabel}}. The steward will land it or escalate to you if it can't.",
+    variables: ["owner", "branch", "base", "stewardId", "reasonLabel"],
+  },
+  {
+    slug: "workspace.phase.active.headline",
+    category: "workspace",
+    title: "Workspace Active Headline",
+    description: "Workspace status headline for active isolated work.",
+    template: "Your isolated branch — work in progress.",
+    defaultTemplate: "Your isolated branch — work in progress.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.active.hint",
+    category: "workspace",
+    title: "Workspace Active Hint",
+    description: "Workspace status hint for active isolated work.",
+    template: "Commit your work in this worktree, then mark it ready. Relay rebases onto the latest base, lands, and pushes for you — do NOT push, rebase, or merge yourself, and never touch the main checkout.",
+    defaultTemplate: "Commit your work in this worktree, then mark it ready. Relay rebases onto the latest base, lands, and pushes for you — do NOT push, rebase, or merge yourself, and never touch the main checkout.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.ready.headline",
+    category: "workspace",
+    title: "Workspace Ready Headline",
+    description: "Workspace status headline for healthy handoff states.",
+    template: "Handed off — stop this turn and go idle while Relay lands your branch. This is the normal, healthy post-ready state (not an escalation).",
+    defaultTemplate: "Handed off — stop this turn and go idle while Relay lands your branch. This is the normal, healthy post-ready state (not an escalation).",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.ready.hint",
+    category: "workspace",
+    title: "Workspace Ready Hint",
+    description: "Workspace status hint for healthy handoff states.",
+    template: "No action needed. Stop your turn now; do not poll or wait on the steward queue. Relay will wake you with a `landed-success` notification when the merge lands and your branch is refreshed, or `landed-failure` if landing fatally fails. Do NOT merge, push, resolve anything, or touch the main checkout.",
+    defaultTemplate: "No action needed. Stop your turn now; do not poll or wait on the steward queue. Relay will wake you with a `landed-success` notification when the merge lands and your branch is refreshed, or `landed-failure` if landing fatally fails. Do NOT merge, push, resolve anything, or touch the main checkout.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.merge-planned.headline",
+    category: "workspace",
+    title: "Workspace Merge Planned Headline",
+    description: "Workspace status headline for merge dispatch.",
+    template: "Merge dispatched — landing your branch on the base now.",
+    defaultTemplate: "Merge dispatched — landing your branch on the base now.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.merge-planned.hint",
+    category: "workspace",
+    title: "Workspace Merge Planned Hint",
+    description: "Workspace status hint for merge dispatch.",
+    template: "No action needed. When it completes you'll be moved onto a fresh rebased branch (the name gains a `--N` suffix — expected) to keep working.",
+    defaultTemplate: "No action needed. When it completes you'll be moved onto a fresh rebased branch (the name gains a `--N` suffix — expected) to keep working.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.conflict.headline",
+    category: "workspace",
+    title: "Workspace Conflict Headline",
+    description: "Workspace status headline when a steward is reconciling a conflict.",
+    template: "Auto-merge hit a conflict — a steward agent is reconciling it. Resolving it is NOT your job.",
+    defaultTemplate: "Auto-merge hit a conflict — a steward agent is reconciling it. Resolving it is NOT your job.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.conflict.hint",
+    category: "workspace",
+    title: "Workspace Conflict Hint",
+    description: "Workspace status hint when a steward is reconciling a conflict.",
+    template: "Do not resolve the conflict, rebase, merge, or push yourself. The steward rebases and lands it, escalating to the human only if it truly can't. You can keep working or wait for it to land.",
+    defaultTemplate: "Do not resolve the conflict, rebase, merge, or push yourself. The steward rebases and lands it, escalating to the human only if it truly can't. You can keep working or wait for it to land.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.merged.headline",
+    category: "workspace",
+    title: "Workspace Merged Headline",
+    description: "Workspace status headline after a successful land.",
+    template: "✅ Landed — your commits are on the base.",
+    defaultTemplate: "✅ Landed — your commits are on the base.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.merged.hint",
+    category: "workspace",
+    title: "Workspace Merged Hint",
+    description: "Workspace status hint after a successful land.",
+    template: "A fresh rebased branch is being prepared; you'll continue on it (the branch name gains a `--N` suffix — expected, not an error). Keep working.",
+    defaultTemplate: "A fresh rebased branch is being prepared; you'll continue on it (the branch name gains a `--N` suffix — expected, not an error). Keep working.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.abandoned.headline",
+    category: "workspace",
+    title: "Workspace Closed Headline",
+    description: "Workspace status headline when the worktree is being torn down.",
+    template: "This workspace is being torn down.",
+    defaultTemplate: "This workspace is being torn down.",
+    variables: [],
+  },
+  {
+    slug: "workspace.phase.abandoned.hint",
+    category: "workspace",
+    title: "Workspace Closed Hint",
+    description: "Workspace status hint when the worktree is being torn down.",
+    template: "No further branch work happens here. If you still have work to do, the host will spawn you into a fresh workspace.",
+    defaultTemplate: "No further branch work happens here. If you still have work to do, the host will spawn you into a fresh workspace.",
+    variables: [],
+  },
+  {
+    slug: "steward.wake",
+    category: "steward",
+    title: "Steward Wake Message",
+    description: "Task body sent to the steward when a workspace needs manual landing.",
+    template: "Workspace `{{branch}}` (id {{wsId}}) in {{repoRoot}} is {{status}} and could not auto-land ({{reason}}).{{ownerLine}} Claim it first so auto-merge yields: `agent-relay workspace claim --id {{wsId}} --purpose steward`. Inspect: `agent-relay steward inspect {{wsId}}`. Then cd into {{worktreePath}}, rebase onto {{baseRef}}, resolve, run checks, and land: `agent-relay workspace land --id {{wsId}} --strategy rebase-ff` — or `agent-relay workspace release --id {{wsId}}` and escalate if you can't.{{coordinatorLine}}",
+    defaultTemplate: "Workspace `{{branch}}` (id {{wsId}}) in {{repoRoot}} is {{status}} and could not auto-land ({{reason}}).{{ownerLine}} Claim it first so auto-merge yields: `agent-relay workspace claim --id {{wsId}} --purpose steward`. Inspect: `agent-relay steward inspect {{wsId}}`. Then cd into {{worktreePath}}, rebase onto {{baseRef}}, resolve, run checks, and land: `agent-relay workspace land --id {{wsId}} --strategy rebase-ff` — or `agent-relay workspace release --id {{wsId}}` and escalate if you can't.{{coordinatorLine}}",
+    variables: ["branch", "wsId", "repoRoot", "status", "reason", "ownerLine", "worktreePath", "baseRef", "coordinatorLine"],
+  },
+  {
+    slug: "steward.merge-stall",
+    category: "steward",
+    title: "Auto-Merge Backoff Notice",
+    description: "Notification body when auto-merge backs off after repeated no-progress attempts.",
+    template: "Workspace {{branch}} in {{repoRoot}} failed to land {{attempts}}× without progress ({{mergeError}}). Auto-merge has backed off to stop a merge-command loop. Sync `{{baseRef}}` and land manually, or release the workspace.",
+    defaultTemplate: "Workspace {{branch}} in {{repoRoot}} failed to land {{attempts}}× without progress ({{mergeError}}). Auto-merge has backed off to stop a merge-command loop. Sync `{{baseRef}}` and land manually, or release the workspace.",
+    variables: ["branch", "repoRoot", "attempts", "mergeError", "baseRef"],
+  },
+  {
+    slug: "task.claim.instruction",
+    category: "task",
+    title: "Task Claim Instruction",
+    description: "Footer appended to task message bodies.",
+    template: "Claim this task before working it, then update task status when finished.",
+    defaultTemplate: "Claim this task before working it, then update task status when finished.",
+    variables: [],
+  },
+  {
+    slug: "notify.routing.policy-changed",
+    category: "notify",
+    title: "Routing Policy Changed",
+    description: "Notification body sent to live spawn-capable agents after a routing policy save.",
+    template: "🗺 Routing policy updated{{updatedBy}}. Ingest this delta now — spawn routing decisions take effect immediately without respawn. Re-read relay_spawn_targets for live provider/model options.",
+    defaultTemplate: "🗺 Routing policy updated{{updatedBy}}. Ingest this delta now — spawn routing decisions take effect immediately without respawn. Re-read relay_spawn_targets for live provider/model options.",
+    variables: ["updatedBy"],
+  },
+  {
+    slug: "notify.automation.budget-warning",
+    category: "notify",
+    title: "Automation Runtime Budget Warning",
+    description: "Fallback automation runtime budget warning body.",
+    template: "Runtime budget warning: this automation run will be shut down in about {{remainingMinutes}}. Finish current work, commit and push anything worth keeping, then stop cleanly before the deadline.",
+    defaultTemplate: "Runtime budget warning: this automation run will be shut down in about {{remainingMinutes}}. Finish current work, commit and push anything worth keeping, then stop cleanly before the deadline.",
+    variables: ["remainingMinutes"],
+  },
+] as const satisfies readonly SeedTemplate[];
+
+export const DEFAULTS = new Map<string, SeedTemplate>(
+  DEFAULT_PROMPT_TEMPLATES.map((template) => [template.slug, template]),
+);
+
+export function defaultPromptTemplates(): SeedTemplate[] {
+  return DEFAULT_PROMPT_TEMPLATES.map(copySeedTemplate);
+}
+
+function renderValue(value: string | string[] | undefined): string {
+  if (Array.isArray(value)) return value.join("\n");
+  return value ?? "";
+}
+
+function applyVariables(template: string, vars: Record<string, string | string[]>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key: string) => renderValue(vars[key]));
+}
+
+export function renderTemplate(slug: string, vars: Record<string, string | string[]> = {}): string {
+  let stored = null;
+  try {
+    stored = getTemplate(slug);
+  } catch {
+    stored = null;
+  }
+  const fallback = DEFAULTS.get(slug);
+  const template = stored?.template ?? fallback?.defaultTemplate;
+  if (template === undefined) throw new Error(`unknown prompt template slug: ${slug}`);
+  return applyVariables(template, vars);
+}