agent-relay-server 0.104.5 → 0.105.0

package/src/prompt-template-defaults-runner.ts

@@ -0,0 +1,136 @@
+import type { SeedTemplate } from "./db/prompt-templates";
+
+function lines(...parts: string[]): string {
+  return parts.join("\n");
+}
+
+export const RUNNER_PROMPT_TEMPLATE_DEFAULTS = [
+  {
+    slug: "relay.manual.claude",
+    category: "runner",
+    title: "Claude Relay Manual",
+    description: "Bundled CLAUDE.md relay manual written into provisioned Claude homes.",
+    template: lines(
+      "# Agent Relay",
+      "",
+      "- Agent Relay messages may come from humans, channels, or other agents.",
+      "- Read the delivered message body and do the requested work.",
+      "- Reply through Relay only when the sender still needs an answer.",
+      "- Prefer the inline MCP tools `relay_reply` or `relay_send_message` for the actual answer to an incoming Relay message.",
+      "- Do not send `/message` with the useful answer and then a separate `/reply` that only says it was sent.",
+      "- If multiple Relay messages arrive together, answer once to the latest relevant message and cover the current request. Do not separately acknowledge stale greetings or context.",
+      "- If the useful response was already delivered through Relay, do not send an extra \"sent\", \"done\", or \"drafts sent\" confirmation unless the user explicitly asked for one.",
+      "- No reply is needed for pure info messages, passive acknowledgements, or reactions that do not ask for action.",
+      "- NEVER reply to a notification-class message. The server marks these and renders a single `↪ Notification — no reply needed.` line instead of the reply reminder — it is a fire-and-forget signal (a merge notice, lifecycle event, or FYI). Act on the information if relevant, but do not send any reply, status confirmation, or reaction back.",
+      "- Use `agent-relay /react <messageId> <emoji>` instead of a text reply for lightweight acknowledgement, approval, thanks, or \"good job\" after a completed work update.",
+      "- Good reaction uses: acknowledge praise with 👍 or ❤️, mark a completed handoff as seen, approve a proposed next step, or acknowledge a passive FYI.",
+      "- Do not use reactions when the user asked a question, gave a new task, reported a bug, or needs a textual result.",
+      "- A thumbs-up reaction to your question means approval to proceed. A thumbs-up reaction to your completed status means no further action.",
+      "- Use `agent-relay get-message <id>` when a delivered preview is truncated.",
+      "- Use `agent-relay /status --json` to inspect your current Relay identity and `agent-relay /guide` for command details.",
+    ),
+    defaultTemplate: lines(
+      "# Agent Relay",
+      "",
+      "- Agent Relay messages may come from humans, channels, or other agents.",
+      "- Read the delivered message body and do the requested work.",
+      "- Reply through Relay only when the sender still needs an answer.",
+      "- Prefer the inline MCP tools `relay_reply` or `relay_send_message` for the actual answer to an incoming Relay message.",
+      "- Do not send `/message` with the useful answer and then a separate `/reply` that only says it was sent.",
+      "- If multiple Relay messages arrive together, answer once to the latest relevant message and cover the current request. Do not separately acknowledge stale greetings or context.",
+      "- If the useful response was already delivered through Relay, do not send an extra \"sent\", \"done\", or \"drafts sent\" confirmation unless the user explicitly asked for one.",
+      "- No reply is needed for pure info messages, passive acknowledgements, or reactions that do not ask for action.",
+      "- NEVER reply to a notification-class message. The server marks these and renders a single `↪ Notification — no reply needed.` line instead of the reply reminder — it is a fire-and-forget signal (a merge notice, lifecycle event, or FYI). Act on the information if relevant, but do not send any reply, status confirmation, or reaction back.",
+      "- Use `agent-relay /react <messageId> <emoji>` instead of a text reply for lightweight acknowledgement, approval, thanks, or \"good job\" after a completed work update.",
+      "- Good reaction uses: acknowledge praise with 👍 or ❤️, mark a completed handoff as seen, approve a proposed next step, or acknowledge a passive FYI.",
+      "- Do not use reactions when the user asked a question, gave a new task, reported a bug, or needs a textual result.",
+      "- A thumbs-up reaction to your question means approval to proceed. A thumbs-up reaction to your completed status means no further action.",
+      "- Use `agent-relay get-message <id>` when a delivered preview is truncated.",
+      "- Use `agent-relay /status --json` to inspect your current Relay identity and `agent-relay /guide` for command details.",
+    ),
+    variables: [],
+  },
+  {
+    slug: "relay.context.claude",
+    category: "runner",
+    title: "Claude Relay Context",
+    description: "One-line relay context note for Claude sessions.",
+    template: "[agent-relay] Relay is available. Follow the Agent Relay rules in CLAUDE.md when present, or run agent-relay /guide. Reply through Relay only when a response is needed; do not send status-only follow-ups after the useful Relay response was already delivered.",
+    defaultTemplate: "[agent-relay] Relay is available. Follow the Agent Relay rules in CLAUDE.md when present, or run agent-relay /guide. Reply through Relay only when a response is needed; do not send status-only follow-ups after the useful Relay response was already delivered.",
+    variables: [],
+  },
+  {
+    slug: "relay.context.claude.readonly",
+    category: "runner",
+    title: "Claude Relay Context (Read Only)",
+    description: "Read-only relay context note for Claude sessions.",
+    template: lines(
+      "[agent-relay] Relay is available. Follow the Agent Relay rules in CLAUDE.md when present, or run agent-relay /guide. Reply through Relay only when a response is needed; do not send status-only follow-ups after the useful Relay response was already delivered.",
+      "",
+      "This Claude session is running with restricted read-only Relay permissions. Do not invoke Agent Relay skills. If you need to reply, use this Bash command shape:",
+      "",
+      "agent-relay /reply <messageId> \"<your reply>\"",
+    ),
+    defaultTemplate: lines(
+      "[agent-relay] Relay is available. Follow the Agent Relay rules in CLAUDE.md when present, or run agent-relay /guide. Reply through Relay only when a response is needed; do not send status-only follow-ups after the useful Relay response was already delivered.",
+      "",
+      "This Claude session is running with restricted read-only Relay permissions. Do not invoke Agent Relay skills. If you need to reply, use this Bash command shape:",
+      "",
+      "agent-relay /reply <messageId> \"<your reply>\"",
+    ),
+    variables: [],
+  },
+  {
+    slug: "relay.context.codex",
+    category: "runner",
+    title: "Codex Relay Context",
+    description: "Relay context note injected into Codex sessions.",
+    template: "[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> \"<your reply>\". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide",
+    defaultTemplate: "[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> \"<your reply>\". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide",
+    variables: [],
+  },
+  {
+    slug: "workspace.lifecycle",
+    category: "runner",
+    title: "Runner Workspace Lifecycle Note",
+    description: "Lifecycle note injected by the runner for isolated workspaces.",
+    template: lines(
+      "[agent-relay] Isolated workspace: you are in a git worktree on branch {{branch}}, based on {{baseRef}} — NOT the main checkout. Other agents may work in parallel and land to {{baseRef}}, so {{baseRef}} will move under you. That is expected; don't fight it.",
+      "Do NOT push this branch yourself — not with `git push`, not with `tl push` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, run `agent-relay workspace ready` — Relay rebases onto the latest {{baseRef}}, lands your work, and pushes for you. If the installed `agent-relay` binary is stale and says the workspace command is unknown, run the repo-local fallback: `bun src/index.ts workspace ready`.",
+      "After `ready`, the status becomes `review_requested` — this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. 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 seeing no steward means it's working, not stuck. Stop your turn after `ready` and go idle; do NOT wait or poll the steward queue. Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails. On success you'll be on a fresh rebased branch whose name gains a `--N` suffix — expected, keep working there. Never `cd` into the main checkout, and never merge/push/resolve conflicts yourself — Relay and the steward own all of that. `agent-relay workspace status` anytime shows your current state and the exact next step.",
+    ),
+    defaultTemplate: lines(
+      "[agent-relay] Isolated workspace: you are in a git worktree on branch {{branch}}, based on {{baseRef}} — NOT the main checkout. Other agents may work in parallel and land to {{baseRef}}, so {{baseRef}} will move under you. That is expected; don't fight it.",
+      "Do NOT push this branch yourself — not with `git push`, not with `tl push` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, run `agent-relay workspace ready` — Relay rebases onto the latest {{baseRef}}, lands your work, and pushes for you. If the installed `agent-relay` binary is stale and says the workspace command is unknown, run the repo-local fallback: `bun src/index.ts workspace ready`.",
+      "After `ready`, the status becomes `review_requested` — this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. 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 seeing no steward means it's working, not stuck. Stop your turn after `ready` and go idle; do NOT wait or poll the steward queue. Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails. On success you'll be on a fresh rebased branch whose name gains a `--N` suffix — expected, keep working there. Never `cd` into the main checkout, and never merge/push/resolve conflicts yourself — Relay and the steward own all of that. `agent-relay workspace status` anytime shows your current state and the exact next step.",
+    ),
+    variables: ["branch", "baseRef"],
+  },
+  {
+    slug: "workspace.deps.symlink",
+    category: "runner",
+    title: "Runner Workspace Deps Symlink Note",
+    description: "Symlinked node_modules caveat injected by the runner.",
+    template: "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout — dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If typecheck/build fails on a missing module (a dependency added to the base AFTER this worktree was created), run `agent-relay workspace deps` — it re-provisions only the stale dirs with a real isolated install, safely, without touching the shared node_modules. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.",
+    defaultTemplate: "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout — dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If typecheck/build fails on a missing module (a dependency added to the base AFTER this worktree was created), run `agent-relay workspace deps` — it re-provisions only the stale dirs with a real isolated install, safely, without touching the shared node_modules. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.",
+    variables: [],
+  },
+  {
+    slug: "workspace.deps.none",
+    category: "runner",
+    title: "Runner Workspace Deps None Note",
+    description: "Missing dependency provisioning caveat injected by the runner.",
+    template: "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.",
+    defaultTemplate: "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.",
+    variables: [],
+  },
+  {
+    slug: "workspace.symlinks",
+    category: "runner",
+    title: "Runner Workspace Symlink Note",
+    description: "Write-through symlink caveat injected by the runner.",
+    template: "[agent-relay] Isolated workspace: these untracked paths are SYMLINKED from the main checkout: {{linked}}. They resolve to the real files in main, so editing or deleting them writes THROUGH to main — treat them as read-only unless you intend to change main.",
+    defaultTemplate: "[agent-relay] Isolated workspace: these untracked paths are SYMLINKED from the main checkout: {{linked}}. They resolve to the real files in main, so editing or deleting them writes THROUGH to main — treat them as read-only unless you intend to change main.",
+    variables: ["linked"],
+  },
+] as const satisfies readonly SeedTemplate[];

package/src/routes/index.ts

@@ -40,6 +40,7 @@ import { getAgentIssueActivityRoute, getIssueActivityAgentsRoute, postIssueActiv
 import { postIssueLifecycleReopenRoute } from "./issue-lifecycle";
 import { deleteIssueRefRoute, getIssueRefRoute, listIssueRefsRoute, patchIssueRefRoute, postIssueRefRoute, resolveIssueRefRoute } from "./issue-refs";
 import { getProjectEntriesRoute, getProjectEntryRoute, getProjectResolveRoute, getProjectRoute, getProjectsRoute } from "./projects";
+import { getPromptTemplateRoute, getPromptTemplatesRoute, postPromptTemplateResetRoute, putPromptTemplateRoute } from "./prompt-templates";
 import { getRecipeByName, getRecipeInstanceArtifacts, getRecipeInstanceById, getRecipeInstances, getRecipes, postRecipeInstanceArtifacts, postRecipeStart, postRecipeStop } from "./recipes";
 import { getSettingRoute, getSettingsNamespaceRoute, getSettingsRoute, putSettingRoute, putSettingsDefaultRoute } from "./settings";
 import { postNotificationPreviewRoute } from "./notifications";
@@ -256,6 +257,10 @@ const routes: Route[] = [
   route("GET", "/api/insights/observations", getInsightsObservationsRoute),
   route("POST", "/api/insights/observations", postInsightsObservationRoute),
   route("POST", "/api/continuation-archives", postContinuationArchiveRoute),
+  route("GET", "/api/settings/prompts", getPromptTemplatesRoute),
+  route("GET", "/api/settings/prompts/:slug", getPromptTemplateRoute),
+  route("PUT", "/api/settings/prompts/:slug", putPromptTemplateRoute),
+  route("POST", "/api/settings/prompts/:slug/reset", postPromptTemplateResetRoute),
   route("GET", "/api/settings", getSettingsRoute),
   route("GET", "/api/settings/:namespace", getSettingsNamespaceRoute),
   route("GET", "/api/settings/:namespace/:key", getSettingRoute),

package/src/routes/prompt-templates.ts

@@ -0,0 +1,60 @@
+import { ValidationError } from "../db";
+import { getComponentAuth, hasComponentScope } from "../security";
+import { getPromptTemplate, listPromptTemplates, resetPromptTemplate, updatePromptTemplate } from "../services/prompt-templates";
+import { cleanString } from "../validation";
+import { authorizeRoute, error, json, parseBody, type Handler } from "./_shared";
+
+function slugParam(params: Record<string, string | undefined>): string {
+  return cleanString(params.slug, "slug", { required: true, max: 200 })!;
+}
+
+function routeError(err: unknown): Response {
+  if (err instanceof ValidationError) return error(err.message, 400);
+  if (err instanceof Error && /not found/.test(err.message)) return error(err.message, 404);
+  return error(err instanceof Error ? err.message : "prompt template route failed");
+}
+
+function authorizePromptRead(req: Request): Response | null {
+  const auth = getComponentAuth(req);
+  if (auth && (hasComponentScope(auth, "system:admin") || hasComponentScope(auth, "agent:read"))) return null;
+  return authorizeRoute(req, { scope: "system:admin" });
+}
+
+export const getPromptTemplatesRoute: Handler = (req) => {
+  const denied = authorizePromptRead(req);
+  if (denied) return denied;
+  const category = cleanString(new URL(req.url).searchParams.get("category"), "category", { max: 120 }) ?? undefined;
+  return json({ templates: listPromptTemplates(category) });
+};
+
+export const getPromptTemplateRoute: Handler = (req, params) => {
+  const denied = authorizePromptRead(req);
+  if (denied) return denied;
+  const template = getPromptTemplate(slugParam(params));
+  return template ? json(template) : error("prompt template not found", 404);
+};
+
+export const putPromptTemplateRoute: Handler = async (req, params) => {
+  const denied = authorizeRoute(req, { scope: "system:admin" });
+  if (denied) return denied;
+  const parsed = await parseBody<Record<string, unknown>>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const template = cleanString(parsed.body?.template, "template", { required: true, max: 200_000 })!;
+    const slug = slugParam(params);
+    return json(updatePromptTemplate(slug, template));
+  } catch (err) {
+    return routeError(err);
+  }
+};
+
+export const postPromptTemplateResetRoute: Handler = (req, params) => {
+  const denied = authorizeRoute(req, { scope: "system:admin" });
+  if (denied) return denied;
+  try {
+    const slug = slugParam(params);
+    return json(resetPromptTemplate(slug));
+  } catch (err) {
+    return routeError(err);
+  }
+};

package/src/routes/workspaces.ts

@@ -2,7 +2,7 @@
 import { RELAY_TOKEN_HEADER, isRecord } from "agent-relay-sdk";
 import { TERMINAL_WORKSPACE_STATUSES, describeWorkspacePhase, landReceipt } from "../workspace-phase";
 import { VALID_WORKSPACE_STATUSES, cleanMeta, cleanString, optionalEnum } from "../validation";
-import { ValidationError, deleteWorkspace, getAgent, getWorkspace, listMergeLeases, listOrchestrators, listRepoStewards, listWorkspaces, updateWorkspaceStatus } from "../db";
+import { ValidationError, deleteWorkspace, getAgent, getWorkspace, listMergeLeases, listOrchestrators, listRepoStewards, listWorkspaces, updateWorkspaceStatus, withResolvedWorkspaceProjects } from "../db";
 import { WORKSPACE_ACTIONS, applyWorkspaceAction, buildWorkspaceCleanupCommand, waitForWorkspaceStatus } from "../workspace-actions";
 import { auditEvent, authAuditMetadata, authorizeRoute, emitCommand, error, json, parseBody, type Handler } from "./_shared";
 import { collectWorkspaceOrphans } from "../workspace-orphans";
@@ -21,8 +21,9 @@ export const getWorkspaces: Handler = (req) => {
     const url = new URL(req.url);
     const repoRoot = cleanString(url.searchParams.get("repoRoot") ?? undefined, "repoRoot", { max: 1000 });
     const ownerAgentId = cleanString(url.searchParams.get("agentId") ?? undefined, "agentId", { max: 240 });
+    const projectId = cleanString(url.searchParams.get("projectId") ?? undefined, "projectId", { max: 120 });
     const status = optionalEnum(url.searchParams.get("status") ?? undefined, "status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
-    return json(listWorkspaces({ repoRoot, ownerAgentId, status }).map(withOwnerOnline));
+    return json(withResolvedWorkspaceProjects(listWorkspaces({ repoRoot, ownerAgentId, status }), { projectId }).map(withOwnerOnline));
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -32,7 +33,7 @@ export const getWorkspaces: Handler = (req) => {
 export const getWorkspaceById: Handler = (_req, params) => {
   const workspace = getWorkspace(params.id!);
   if (!workspace) return error("workspace not found", 404);
-  return json(withOwnerOnline(workspace));
+  return json(withOwnerOnline(withResolvedWorkspaceProjects([workspace])[0]!));
 };
 
 export const getWorkspaceStewards: Handler = () => json({ stewards: listRepoStewards(), mergeLeases: listMergeLeases() });

package/src/routing-policy-push.ts

@@ -14,6 +14,7 @@
 import { getDb } from "./db";
 import { emitRelayEvent } from "./events";
 import { routeNotification } from "./notification-router";
+import { renderTemplate } from "./prompt-resolver";
 import { parseJson } from "./utils";
 import { isRecord } from "agent-relay-sdk";
 import type { RoutingPolicy } from "agent-relay-sdk";
@@ -43,7 +44,9 @@ export function notifyRoutingPolicyChanged(policy: RoutingPolicy, opts: { update
     ttlMs: PUSH_TTL_MS,
     message: {
       subject: "Routing policy updated",
-      body: `🗺 Routing policy updated${opts.updatedBy ? ` by ${opts.updatedBy}` : ""}. Ingest this delta now — spawn routing decisions take effect immediately without respawn. Re-read relay_spawn_targets for live provider/model options.`,
+      body: renderTemplate("notify.routing.policy-changed", {
+        updatedBy: opts.updatedBy ? ` by ${opts.updatedBy}` : "",
+      }),
       payload: { kind: "routing.policy.changed", policy: policy as unknown as Record<string, unknown>, updatedBy: opts.updatedBy ?? null },
       replyExpected: false,
     },

package/src/security.ts

@@ -202,6 +202,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname === "/api/provider-quotas") return method === "GET" ? "agent:read" : "quota:write";
   if (pathname === "/api/routing-policy") return method === "GET" ? "agent:read" : "settings:write:routing";
   if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
+  if (pathname === "/api/settings/prompts" || pathname.startsWith("/api/settings/prompts/")) return method === "GET" ? "agent:read" : "system:admin";
   if (pathname.startsWith("/api/teams")) return method === "GET" ? "teams:read" : "teams:write";
   if (pathname.startsWith("/api/blackboard")) return method === "GET" ? "blackboard:read" : "blackboard:write";
   if (pathname.startsWith("/api/issue-associations")) return method === "GET" ? "issue:read" : "issue:write";
@@ -297,6 +298,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
     return method === "GET" ? "agent:read" : "settings:write:routing";
   }
   if (pathname === "/api/teams/config") return method === "GET" ? "teams:read" : "settings:write:teams";
+  if (pathname === "/api/settings/prompts" || pathname.startsWith("/api/settings/prompts/")) return method === "GET" ? "agent:read" : "system:admin";
   if (pathname.startsWith("/api/messages") || pathname.startsWith("/api/inbox")) return method === "GET" ? "message:read" : "message:send";
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/provisioning")) return method === "GET" ? "provisioning:read" : "provisioning:write";
@@ -326,6 +328,7 @@ const CONFIG_SETTINGS_NAMESPACES = new Set(["steward", "insights", "notification
 
 function requiredSettingsScopeFor(method: string, pathname: string): string | null | undefined {
   if (pathname === "/api/settings") return method === "GET" ? "settings:read" : null;
+  if (pathname === "/api/settings/prompts" || pathname.startsWith("/api/settings/prompts/")) return undefined;
   const settingsMatch = pathname.match(/^\/api\/settings\/([^/]+)(?:\/[^/]+)?$/);
   if (settingsMatch) return settingsScope(method, decodeURIComponent(settingsMatch[1]!));
   if (pathname === "/api/steward-config") return settingsScope(method, "steward");

package/src/self-resume.ts

@@ -13,6 +13,7 @@ import {
 } from "./db";
 import { emitRelayEvent } from "./events";
 import { routeNotification } from "./notification-router";
+import { renderTemplate } from "./prompt-resolver";
 import type { AgentCard, Command, ContinuationEnvelope, ContinuationLedgerEntry, SelfResumeMode } from "./types";
 
 interface CompactAndResumeInput {
@@ -149,21 +150,13 @@ function renderContinuation(envelope: ContinuationEnvelope): string {
   const ledger = envelope.ledger.length
     ? envelope.ledger.map((entry) => `- gen ${entry.gen} @ ${new Date(entry.at).toISOString()}: ${entry.ruledOut}${entry.why ? `; why: ${entry.why}` : ""}`).join("\n")
     : "- none";
-  return [
-    `You have been resumed by Agent Relay — generation ${envelope.generation}.`,
-    "",
-    "Objective (verbatim, relay-owned):",
-    envelope.objective,
-    "",
-    "Ruled-out ledger (append-only):",
-    ledger,
-    "",
-    "Working state:",
-    envelope.workingState,
-    "",
-    "Archive refs:",
-    envelope.archiveRefs.length ? envelope.archiveRefs.join("\n") : "- none",
-  ].join("\n");
+  return renderTemplate("continuation.envelope", {
+    generation: String(envelope.generation),
+    objective: envelope.objective,
+    ruledOut: ledger,
+    workingState: envelope.workingState,
+    archiveRefs: envelope.archiveRefs.length ? envelope.archiveRefs.join("\n") : "- none",
+  });
 }
 
 function assertResumeSupported(agent: AgentCard, mode: SelfResumeMode): void {

package/src/services/prompt-templates.ts

@@ -0,0 +1,19 @@
+import { getTemplate, listTemplates, resetTemplate, upsertTemplate, type PromptTemplateRecord } from "../db";
+
+export function listPromptTemplates(category?: string): PromptTemplateRecord[] {
+  return listTemplates(category);
+}
+
+export function getPromptTemplate(slug: string): PromptTemplateRecord | null {
+  return getTemplate(slug);
+}
+
+export function updatePromptTemplate(slug: string, template: string): PromptTemplateRecord | null {
+  upsertTemplate(slug, template);
+  return getTemplate(slug);
+}
+
+export function resetPromptTemplate(slug: string): PromptTemplateRecord | null {
+  resetTemplate(slug);
+  return getTemplate(slug);
+}

package/src/services/register-agent.ts

@@ -18,6 +18,7 @@ import { notifyAgentReady } from "../agent-lifecycle-events";
 import { resolveSpawnLineage, resolveTeamLineage } from "../security";
 import { flushQueuedDirectMessages, markManagedAgentRunning } from "./managed-running";
 import { isAgentUnavailable } from "../db/agent-predicates";
+import { recordSpawnPromptIssueActivity } from "./spawn-issue-activity";
 import type { AuthContext } from "./auth-context";
 import type { AgentCard, RegisterAgentInput } from "../types";
 
@@ -86,6 +87,7 @@ export function registerAgent(input: RegisterAgentInput, ctx: AuthContext): Agen
     const promptMirror = seedSpawnPromptMirror(agent.id, spawnRequestId);
     if (promptMirror?.created || promptMirror?.updated) emitNewMessage(promptMirror.message);
     seedSpawnReplyObligation(agent.id, agent.spawnedBy, spawnRequestId);
+    recordSpawnPromptIssueActivity(agent, spawnRequestId);
     createActivityEvent({
       clientId: `server-agent-${agent.id}-registered`,
       kind: "state",

package/src/services/spawn-issue-activity.ts

@@ -0,0 +1,107 @@
+import { isRecord } from "agent-relay-sdk";
+import { getDb, resolveProjectForCwd } from "../db";
+import { resolveIssueRefFromString } from "../db/issue-refs";
+import { defaultIssueRepo } from "../config";
+import { parseJson } from "../utils";
+import { recordAndEmitIssueActivity } from "./issue-activity";
+import type { AgentCard, WorkspaceRecord } from "../types";
+
+const BARE_ISSUE_REF_RE = /#([0-9]+)/g;
+
+/**
+ * Parse spawn prompt for bare #NNN refs and record "edit" activity for the
+ * newly registered agent. Called once on first registration. Silently ignores
+ * prompts with no refs or refs that can't be resolved (no issueRepo configured).
+ * Uses a stable clientId so repeated registration never double-records.
+ */
+export function recordSpawnPromptIssueActivity(agent: AgentCard, spawnRequestId: string | undefined): void {
+  if (!spawnRequestId) return;
+  try {
+    const row = getDb().query(`
+      SELECT params FROM commands
+      WHERE type = 'agent.spawn' AND correlation_id = ?
+      ORDER BY created_at DESC
+      LIMIT 1
+    `).get(spawnRequestId) as { params: string } | undefined;
+    const params = row ? parseJson<unknown>(row.params, {}) : {};
+    if (!isRecord(params) || typeof params.prompt !== "string") return;
+    const prompt = params.prompt;
+    if (!prompt.trim()) return;
+
+    const cwd = typeof agent.meta?.cwd === "string" ? agent.meta.cwd : undefined;
+    const issueRepo = (cwd ? resolveProjectForCwd(cwd)?.issueRepo : undefined) ?? defaultIssueRepo();
+
+    const seen = new Set<string>();
+    for (const match of prompt.matchAll(BARE_ISSUE_REF_RE)) {
+      const num = match[1];
+      if (!num || seen.has(num)) continue;
+      seen.add(num);
+      try {
+        const issueRef = resolveIssueRefFromString({ ref: `#${num}`, defaultRepo: issueRepo });
+        recordAndEmitIssueActivity({
+          agentId: agent.id,
+          action: "edit",
+          issueRefId: issueRef.id,
+          clientId: `spawn-issue:${agent.id}:${issueRef.id}`,
+          title: "Issue referenced in spawn prompt",
+          metadata: { source: "spawn-prompt", spawnRequestId },
+        });
+      } catch {
+        // Unresolvable ref (no issueRepo configured) — skip silently.
+      }
+    }
+  } catch {
+    // Must never break registration.
+  }
+}
+
+/**
+ * Inspect a newly created isolated workspace for issue refs from:
+ *   1. metadata.issueNumber (set by some spawn flows)
+ *   2. branch name (e.g. "agent/build-389-p1-..." → 389)
+ * Records "edit" activity for the owning agent. Uses the same stable clientId
+ * as recordSpawnPromptIssueActivity so prompt + branch refs for the same issue
+ * are deduplicated at the DB layer.
+ */
+export function recordWorkspaceIssueActivity(workspace: WorkspaceRecord): void {
+  const agentId = workspace.ownerAgentId;
+  if (!agentId || workspace.mode !== "isolated") return;
+
+  const seen = new Set<string>();
+
+  const issueNumber = workspace.metadata?.issueNumber;
+  if (typeof issueNumber === "number") {
+    seen.add(String(Math.trunc(issueNumber)));
+  } else if (typeof issueNumber === "string") {
+    const t = issueNumber.trim();
+    if (/^[0-9]+$/.test(t)) seen.add(t);
+  }
+
+  if (workspace.branch) {
+    // Match the first 3+-digit number surrounded by separators in the branch name
+    // (e.g. agent/build-389-p1-foo → "389"). Skip 1–2-digit numbers to avoid
+    // partition or sequence suffixes (e.g. issue-activity-auto-01 → skip "01").
+    const match = workspace.branch.match(/(?:^|[-/])([0-9]{3,})(?:[-/]|$)/);
+    if (match?.[1]) seen.add(match[1]);
+  }
+
+  if (seen.size === 0) return;
+
+  const issueRepo = resolveProjectForCwd(workspace.repoRoot)?.issueRepo ?? defaultIssueRepo();
+
+  for (const num of seen) {
+    try {
+      const issueRef = resolveIssueRefFromString({ ref: `#${num}`, defaultRepo: issueRepo });
+      recordAndEmitIssueActivity({
+        agentId,
+        action: "edit",
+        issueRefId: issueRef.id,
+        clientId: `spawn-issue:${agentId}:${issueRef.id}`,
+        title: "Issue referenced in workspace",
+        metadata: { source: "workspace", workspaceId: workspace.id, branch: workspace.branch },
+      });
+    } catch {
+      // Unresolvable ref — skip silently.
+    }
+  }
+}

package/src/spawn-targets.ts

@@ -1,6 +1,7 @@
 import { countLiveSpawnedAgents, getAgent, getOrchestrator, listOrchestrators, listProviderQuotas, ValidationError } from "./db";
 import { DEFAULT_SPAWN_PROFILE_NAME, listAgentProfiles } from "./config-store";
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
+import { renderTemplate } from "./prompt-resolver";
 import { getRoutingPolicy } from "./routing-policy-store";
 import { isPathWithinBase } from "./utils";
 import { McpNotFoundError } from "./mcp-errors";
@@ -436,17 +437,8 @@ function spawnAlternatives(provider?: SpawnProvider): string {
 // stays lazy — fetched only when the agent actually decides to spawn. Returns "" for non-spawn agents.
 export function spawnCapablePrimer(input: { canSpawn: boolean; quota?: number }): string {
   if (!input.canSpawn) return "";
-  const quotaLabel = typeof input.quota === "number" && input.quota > 0 ? ` (live-children quota: ${input.quota})` : "";
-  return [
-    `You can spawn long-living child agents${quotaLabel}. 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_SPAWN_PROFILE_NAME}; 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).",
-  ].join("\n");
+  const quota = typeof input.quota === "number" && input.quota > 0 ? ` (live-children quota: ${input.quota})` : "";
+  return renderTemplate("spawn.primer", { quota, defaultProfile: DEFAULT_SPAWN_PROFILE_NAME });
 }
 
 // === Orchestrator selection ===

package/src/steward.ts

@@ -4,6 +4,7 @@ import { stewardFallbackTarget } from "./config";
 import { getSpawnPolicy, getStewardConfig, setConfig } from "./config-store";
 import { listOrchestrators } from "./db";
 import { getLifecycleManager } from "./lifecycle-manager";
+import { renderTemplate } from "./prompt-resolver";
 import type { Orchestrator, SpawnPolicy, StewardConfig } from "./types";
 import { isPathWithinBase } from "./utils";
 
@@ -25,29 +26,10 @@ export function buildStewardPrompt(repoRoot: string): string {
   // wake/task message via #640), not a static `system` dead-end. The fallback target below is
   // used ONLY when a wake message names no coordinator.
   const fallback = stewardFallbackTarget();
-  const fallbackTarget = fallback ? `\`${fallback}\`` : "the human operator who configured this relay";
-  return [
-    `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 ${fallbackTarget}. 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.",
-  ].join("\n");
+  return renderTemplate("steward.prompt", {
+    repoRoot,
+    escalationTarget: fallback ? `\`${fallback}\`` : "the human operator who configured this relay",
+  });
 }
 
 function desiredStewardPolicy(repoRoot: string, owner: Orchestrator, config: StewardConfig): SpawnPolicy {

package/src/workspace-auto-merge.ts

@@ -31,6 +31,7 @@ import { emitCommandEvent } from "./command-events";
 import { getLandingConfig, getStewardConfig } from "./config-store";
 import { getLifecycleManager } from "./lifecycle-manager";
 import { routeNotification } from "./notification-router";
+import { renderTemplate } from "./prompt-resolver";
 import { isAwaitingReviewerApproval } from "./reviewer-pipeline";
 import { ensureRepoSteward } from "./steward";
 import { requestWorkspaceMerge } from "./workspace-merge";
@@ -115,7 +116,17 @@ export function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | n
       recipients: [`policy:${policyName}`],
       message: {
         subject: `Steward: ${ws.status} workspace needs attention`,
-        body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}).${ownerLine} Claim it first so auto-merge yields: \`agent-relay workspace claim --id ${ws.id} --purpose steward\`. Inspect: \`agent-relay steward inspect ${ws.id}\`. Then cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, and land: \`agent-relay workspace land --id ${ws.id} --strategy rebase-ff\` — or \`agent-relay workspace release --id ${ws.id}\` and escalate if you can't.${coordinatorLine}`,
+        body: renderTemplate("steward.wake", {
+          branch: ws.branch ?? ws.id,
+          wsId: ws.id,
+          repoRoot: ws.repoRoot,
+          status: ws.status,
+          reason,
+          ownerLine,
+          worktreePath: ws.worktreePath ?? ws.sourceCwd,
+          baseRef: ws.baseRef ?? "base",
+          coordinatorLine,
+        }),
         payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason, ownerAgentId, coordinatorAgentId },
       },
     });
@@ -202,7 +213,13 @@ function escalateNoProgressMerge(ws: WorkspaceRecord): void {
       recipients,
       message: {
         subject: "Workspace can't auto-land — needs attention",
-        body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} failed to land ${MAX_NO_PROGRESS_MERGE_ATTEMPTS}× without progress (${mergeError}). Auto-merge has backed off to stop a merge-command loop. Sync \`${ws.baseRef ?? "base"}\` and land manually, or release the workspace.`,
+        body: renderTemplate("steward.merge-stall", {
+          branch: `\`${ws.branch ?? ws.id}\``,
+          repoRoot: ws.repoRoot,
+          attempts: String(MAX_NO_PROGRESS_MERGE_ATTEMPTS),
+          mergeError,
+          baseRef: ws.baseRef ?? "base",
+        }),
         payload: { kind: "workspace.auto-merge-stuck", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: ws.baseRef, attempts: MAX_NO_PROGRESS_MERGE_ATTEMPTS, reason: mergeError },
       },
     });