@humwick/server 0.130.1 → 0.130.2

package/src/services/plan-wake-digest.ts

@@ -70,6 +70,7 @@ export function renderPlanWakeDigest(agentId: string, now = Date.now()): string
     do {
       const page = listPlansByTeam(teamId, { limit: 8, cursor });
       for (const summary of page.plans) {
+        if (!summary.nodeCount) continue;
         const plan = getPlan(summary.id);
         if (!plan) continue;
         const line = planLine(plan, now);

package/src/services/profile-trust.ts

@@ -1,7 +1,8 @@
 // #3636 — project trust edits without the dashboard: set a profile's review mode, acknowledge its
 // project hooks/MCP, approve an observed value. One seam for the HTTP routes and the MCP tool.
 import { ValidationError, type AgentProfile, type ProfileProjectReviewMode } from "@humwick/sdk";
-import { getAgentProfile, setAgentProfile, validateAgentProfile } from "../config-store";
+import { getAgentProfile, validateAgentProfile } from "../config-store";
+import { setAgentProfileAsync } from "../config-store-write";
 import type { ConfigEntry } from "../types";
 import type { ProjectTrustApproval, ProjectTrustCapability } from "../db/project-trust-approvals";
 import { approveProjectCapabilityReview, projectCellsHash } from "../project-trust";
@@ -38,9 +39,9 @@ export function withProjectTrust(profile: AgentProfile, update: ProjectTrustUpda
   return validated;
 }
 
-export function updateProfileProjectTrust(name: string, update: ProjectTrustUpdate, by: string): ConfigEntry<AgentProfile> {
+export async function updateProfileProjectTrustAsync(name: string, update: ProjectTrustUpdate, by: string): Promise<ConfigEntry<AgentProfile>> {
   if (!update.review && !update.ack?.length) throw new ValidationError("nothing to update: pass review and/or ack");
-  const saved = setAgentProfile(withProjectTrust(existingProfile(name).value, update, by), by, { overrideBuiltIn: true });
+  const saved = await setAgentProfileAsync(withProjectTrust(existingProfile(name).value, update, by), by, { overrideBuiltIn: true });
   emitConfigChanged(saved.namespace, saved.key, saved.version);
   return saved;
 }

package/src/services/project-config-read.ts

@@ -0,0 +1,70 @@
+// #3635/#3736 — one reader for `.agent-relay/*.json` project config (areas.json, spawn-policy.json): the
+// file at the checkout's default branch (origin/<default>, fetched first), read on the checkout's host
+// through the #3043 project-files reader. Never a working tree and never cached, so a stale checkout or
+// an old negative answer cannot hide a file that landed.
+import { readProjectFiles } from "@humwick/sdk";
+import type { ConfigAtCommit } from "@humwick/sdk/repo-config-file";
+import { errMessage } from "@humwick/sdk";
+import { rootsForProject } from "../db";
+import { localProjectGit, readHostProjectFiles } from "../project-roles";
+import { hostIsRelayHost } from "../relay-host-locality";
+import { resolveProjectFilesHost } from "./spawn-project-role";
+
+/** A checkout to read from: a cwd on a host (a hostname or a registered orchestrator). */
+export interface ProjectCheckout {
+  cwd: string;
+  host?: string;
+  orchestratorId?: string;
+}
+
+export type ConfigLookup<T> = ConfigAtCommit<T> | { status: "unreadable"; error: string };
+
+type Snapshot = { ref: string; sha: string; files: Record<string, string | null> };
+
+const warned = new Set<string>();
+
+/** One warning per distinct problem, so a broken file does not flood the log on every read. */
+export function warnConfigOnce(key: string, message: string): void {
+  if (warned.has(key)) return;
+  if (warned.size >= 1000) warned.clear();
+  warned.add(key);
+  console.warn(message);
+}
+
+/** `file` at the checkout's default branch; a read failure is `unreadable`, never a throw. Invalid and
+ *  unreadable outcomes warn once, naming `file`, the checkout and why, with `consequence` appended. */
+export async function readProjectConfig<T>(checkout: ProjectCheckout, file: string, parse: (snapshot: Snapshot) => ConfigAtCommit<T>, consequence: string): Promise<ConfigLookup<T>> {
+  const where = `${checkout.orchestratorId ?? checkout.host ?? "local"}:${checkout.cwd}`;
+  try {
+    const snapshot = !checkout.orchestratorId && hostIsRelayHost(checkout.host)
+      ? await readProjectFiles({ paths: [file] }, localProjectGit(checkout.cwd))
+      : await readHostProjectFiles(
+        resolveProjectFilesHost({ subject: file, cwd: checkout.cwd, orchestratorId: checkout.orchestratorId, preferHost: checkout.host }),
+        checkout.cwd, { paths: [file] }, file,
+      );
+    const lookup = parse(snapshot);
+    if (lookup.status === "invalid") warnConfigOnce(`${file}@${where}@${lookup.sha}`, `[project-config] ${file} for ${where} at ${lookup.sha.slice(0, 12)} is invalid: ${lookup.error}; ${consequence}`);
+    return lookup;
+  } catch (err) {
+    const error = errMessage(err);
+    warnConfigOnce(`${file}@${where}`, `[project-config] ${file} for ${where}: unreadable: ${error}; ${consequence}`);
+    return { status: "unreadable", error };
+  }
+}
+
+/** The first checkout that can be read answers: the preferred ones, then each registered root of the project. */
+export async function readProjectConfigFirst<T>(
+  projectId: string | undefined, preferred: readonly ProjectCheckout[], file: string, parse: (snapshot: Snapshot) => ConfigAtCommit<T>, consequence: string,
+): Promise<{ lookup?: ConfigAtCommit<T>; failures: string[] }> {
+  const checkouts: ProjectCheckout[] = [
+    ...preferred,
+    ...(projectId ? rootsForProject(projectId).map((root) => ({ cwd: root.rootPath, ...(root.orchestratorId ? { orchestratorId: root.orchestratorId } : {}) })) : []),
+  ];
+  const failures: string[] = [];
+  for (const checkout of checkouts) {
+    const lookup = await readProjectConfig(checkout, file, parse, consequence);
+    if (lookup.status !== "unreadable") return { lookup, failures };
+    failures.push(lookup.error);
+  }
+  return { failures };
+}

package/src/services/project-profile-instructions.ts

@@ -0,0 +1,54 @@
+import { randomUUID } from "node:crypto";
+import { hasScope, isRecord } from "@humwick/sdk";
+import type { ProjectProfileInstructions } from "../types";
+import { listAgentProfiles, resolveAgentProfileKey } from "../config-store";
+import { getGateway } from "../db/gateway";
+import { ValidationError } from "../db/connection";
+import { promptActorFromContext, promptVersionNumber } from "./prompt-version-writer";
+import type { AuthContext } from "./auth-context";
+import { cleanString } from "../validation";
+import { emitConfigChanged } from "../sse";
+
+export async function projectProfileInstructionKey(projectId: string, profile: string) {
+  const canonical = resolveAgentProfileKey(profile);
+  if (!canonical) throw new ValidationError("profile not found");
+  if (!await getGateway().read("projects.get", { id: projectId })) throw new ValidationError("project not found");
+  return { projectId, profile: canonical };
+}
+
+export async function readProjectProfileInstructions(projectId: string, profile: string) {
+  return getGateway().read("projectProfileInstructions.get", await projectProfileInstructionKey(projectId, profile));
+}
+
+export async function projectProfileInstructionHistory(projectId: string, profile: string) {
+  return { versions: await getGateway().read("projectProfileInstructions.history", await projectProfileInstructionKey(projectId, profile)) };
+}
+
+export async function listProjectProfileInstructions(filter: { projectId?: string; profile?: string }) {
+  const gateway = getGateway();
+  const profile = filter.profile ? resolveAgentProfileKey(filter.profile) : undefined;
+  if (filter.profile && !profile) throw new ValidationError("profile not found");
+  if (filter.projectId && !await gateway.read("projects.get", { id: filter.projectId })) throw new ValidationError("project not found");
+  if (!filter.projectId && !profile) throw new ValidationError("projectId or profile required");
+  const stored = await gateway.read("projectProfileInstructions.list", { projectId: filter.projectId, profile });
+  const byKey = new Map(stored.map(entry => [JSON.stringify([entry.projectId, entry.profile]), entry]));
+  const entry = (projectId: string, profile: string): ProjectProfileInstructions => byKey.get(JSON.stringify([projectId, profile])) ?? { projectId, profile, template: "", version: 0, updatedAt: 0 };
+  return { instructions: filter.projectId
+    ? listAgentProfiles().filter(item => !profile || item.key === profile).map(item => entry(filter.projectId!, item.key))
+    : (await gateway.read("projects.list", { includeArchived: true })).map(project => ({ ...entry(project.id, profile!), projectTitle: project.title, projectSlug: project.slug })) };
+}
+
+export async function mutateProjectProfileInstructions(ctx: AuthContext, projectId: string, profile: string, input: unknown, restore = false) {
+  if (ctx.actor.kind !== "system" && !hasScope(ctx.scopes, "agent:write")) throw new ValidationError("agent:write scope required");
+  const key = await projectProfileInstructionKey(projectId, profile);
+  if (!isRecord(input)) throw new ValidationError("JSON object body required");
+  if (!Number.isSafeInteger(input.expectedVersion) || (input.expectedVersion as number) < 0) throw new ValidationError("expectedVersion must be a non-negative integer");
+  const result = await getGateway().write("projectProfileInstructions.write", {
+    ...key, expectedVersion: input.expectedVersion as number,
+    template: restore ? undefined : input.template as string,
+    restoreVersion: restore ? promptVersionNumber(input.version, "version") : undefined,
+    actor: promptActorFromContext(ctx), reason: cleanString(input.reason, "reason", { max: 2000 }),
+  }, { idempotencyKey: randomUUID() }) as unknown as ProjectProfileInstructions;
+  emitConfigChanged("project-profile-instructions", `${key.projectId}:${key.profile}`, result.version);
+  return result;
+}

package/src/services/provisioning-harness/budget-baseline.json

@@ -19,7 +19,7 @@
           "unknown": 0
         },
         "mcp:relay-schemas": {
-          "residentKnown": 24523,
+          "residentKnown": 24574,
           "onDemandAvailable": 0,
           "unknown": 0
         },
@@ -114,7 +114,7 @@
           "unknown": 0
         },
         "mcp:relay-schemas": {
-          "residentKnown": 24523,
+          "residentKnown": 24574,
           "onDemandAvailable": 0,
           "unknown": 0
         },
@@ -364,11 +364,11 @@
     "reviewer:codex": 11221,
     "sec-ops:claude": 11610,
     "sec-ops:codex": 10644,
-    "ops-assistant:claude": 25307,
+    "ops-assistant:claude": 25390,
     "ops-assistant:codex": 25562,
     "sub-coordinator:claude": 20137,
     "sub-coordinator:codex": 20392,
-    "coordinator:claude": 26501,
+    "coordinator:claude": 26584,
     "coordinator:codex": 26622,
     "isolated-research:claude": 2852,
     "isolated-research:codex": 2790,

package/src/services/restart-spawn.ts

@@ -16,7 +16,7 @@ import { resolveWhoamiRole } from "../mcp/identity-projection";
 import { listManagedOrchestratorsForAgent } from "../orchestrator-lookup";
 import { applyDefaultSharedMcp } from "../shared-mcp";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, resolveSpawnModelParamsAsync } from "../spawn-command";
-import { SUCCESSOR_LAUNCH, runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { SUCCESSOR_LAUNCH, runnerRuntimeTokenEnv, runnerRuntimeTokenEnvAsync, type RunnerRuntimeTokenInput } from "../runtime-tokens";
 import { restartEffortState } from "./self-effort";
 // #2033 — from isolated-workspace-placement.ts, NOT ./spawn-identity: that module also exports
 // buildProspectiveSpawnIdentity, which imports mcp/identity.ts → self-resume.ts → restart-spawn.ts,
@@ -27,7 +27,7 @@ import { restartInstructionParamsForAgent, restartInstructionParamsForAgentAsync
 import { launchedProjectRole, projectRoleRestartError, refuseSyncProjectRoleRestart, restartProjectRole } from "./restart-project-role";
 import { authContextFromSystem } from "./auth-context";
 import { markManagedAgentRunning } from "./managed-running";
-import type { AgentCard, AgentProfile, Command, Orchestrator, SpawnApprovalMode } from "../types";
+import type { AgentCard, AgentProfile, SpawnPolicy, Command, Orchestrator, SpawnApprovalMode } from "../types";
 
 export type SelfRestartReason = "upgrade" | "token-remint" | "manual" | "reset-unconfirmed";
 type RestartOptions = { resumeId?: string; continuation?: string; generation?: number; reason?: string };
@@ -116,30 +116,9 @@ function buildRestartSpawnParamsForAgent(
       requestedBy,
       // Override the policy builder's normal mint so stable team/project bindings are also
       // carried by the fresh token, not merely preserved incidentally on the agent row.
-      env: runnerRuntimeTokenEnv({ authority: SUCCESSOR_LAUNCH,
-        agentId: agent.id,
-        orchestratorId: policy.value.orchestratorId,
-        cwd: policy.value.cwd,
-        provider: policy.value.provider,
-        label: policy.value.label,
-        policyName: policy.value.name,
-        spawnRequestId: requestId,
-        createdBy: requestedBy,
-        profile: policy.value.profile || undefined,
-        // #2245 — the successor's posture comes from the POLICY (server config, unforgeable), the
-        // same value `buildManagedSpawnParams` launches it with; stamp it into the signed constraints.
-        approvalMode: policy.value.permissionMode,
-        ...(agent.teamId ? { teamId: agent.teamId } : {}),
-        ...(projectId ? { projectId } : {}),
-        ...([...stewardExtraCwdPrefixes, ...isolatedExtraCwdPrefixes].length
-          ? { extraCwdPrefixes: [...stewardExtraCwdPrefixes, ...isolatedExtraCwdPrefixes] }
-          : {}),
-      }),
-      ...(opts.continuation ? { prompt: opts.continuation } : {}),
-      ...(restartResumeWorkspace ? { resumeWorkspace: restartResumeWorkspace } : {}),
-      // F5 — carry the self-restart generation marker on BOTH successor spawns (policy and
-      // dashboard/non-policy), so the audit lineage is symmetric regardless of branch.
-      ...(opts.generation ? { extra: { selfRestart: { generation: opts.generation, reason: opts.reason } } } : {}),
+      env: runnerRuntimeTokenEnv(managedRestartTokenInput(agent, policy.value, requestId, requestedBy, projectId,
+        [...stewardExtraCwdPrefixes, ...isolatedExtraCwdPrefixes])),
+      ...managedRestartOptions(opts, restartResumeWorkspace),
     };
     return opts.resumeId ? withResumeParams(params, opts.resumeId, agent.id) : params;
   }
@@ -160,7 +139,7 @@ function buildRestartSpawnParamsForAgent(
   const resolvedProfile = withResolvedProvisioning(profileName ? getAgentProfile(profileName)?.value : undefined, provider);
   const agentProfile = resolvedProfile ? applyDefaultSharedMcp(resolvedProfile) : undefined;
   const workspaceMode = stringValue(agent.meta?.workspaceMode) ?? "inherit";
-  const resolvedModel = resolveSpawnModelParams(provider, model, effort, { modelSource: "runtime", skipDefaultWhenEmpty: true });
+  const resolvedModel = resolveSpawnModelParams(provider, model, effort, { modelSource: "runtime" });
   const projectedInstructions = restartInstructionParamsForAgent(agent, { spawnRequestId: predecessorSpawnRequestId, cwd }) ?? {};
   // #1598 — canonicalize so a worktree/subdir cwd binds to its owning checkout's project.
   const projectId = resolveProjectForCanonicalCwd(cwd).project?.id;
@@ -175,7 +154,7 @@ function buildRestartSpawnParamsForAgent(
     cwd,
     orchestrator.baseDir,
   );
-  return buildRestartSpawnCommand(agent, predecessorSpawnRequestId, agentProfile, projectedInstructions, opts, {
+  const options = {
     provider,
     modelParams: resolvedModel,
     cwd,
@@ -185,7 +164,10 @@ function buildRestartSpawnParamsForAgent(
     policyName: policyName || undefined,
     spawnRequestId: requestId,
     requestedBy,
-  }, { orchestratorId: orchestrator.id, projectId, extraCwdPrefixes: stewardExtraCwdPrefixes });
+  };
+  const tokenContext = { orchestratorId: orchestrator.id, projectId, extraCwdPrefixes: stewardExtraCwdPrefixes };
+  return buildRestartSpawnCommand(agent, predecessorSpawnRequestId, agentProfile, projectedInstructions, opts, options, tokenContext,
+    runnerRuntimeTokenEnv(restartTokenInput(agent, options, tokenContext)));
 }
 
 /** Worker-safe restart command construction used by HTTP/orchestrator/self-restart flows. */
@@ -233,14 +215,8 @@ async function buildRestartSpawnParamsForAgentAsync(
     const params = {
       ...await buildManagedSpawnParamsAsync(relaunchPolicy(policy.value, relaunch.effort), requestId, { createdBy: requestedBy, authority: SUCCESSOR_LAUNCH, identityAgentId: agent.id, gitRepoRoot }),
       ...relaunch.carried, agentId: agent.id, requestedBy,
-      env: runnerRuntimeTokenEnv({ authority: SUCCESSOR_LAUNCH, agentId: agent.id, orchestratorId: policy.value.orchestratorId, cwd: policy.value.cwd,
-        provider: policy.value.provider, label: policy.value.label, policyName: policy.value.name, spawnRequestId: requestId,
-        createdBy: requestedBy, profile: policy.value.profile || undefined, ...(agent.teamId ? { teamId: agent.teamId } : {}),
-        approvalMode: policy.value.permissionMode,
-        ...(projectId ? { projectId } : {}), ...(combinedExtraCwdPrefixes.length ? { extraCwdPrefixes: combinedExtraCwdPrefixes } : {}), }),
-      ...(opts.continuation ? { prompt: opts.continuation } : {}),
-      ...(restartResumeWorkspace ? { resumeWorkspace: restartResumeWorkspace } : {}),
-      ...(opts.generation ? { extra: { selfRestart: { generation: opts.generation, reason: opts.reason } } } : {}),
+      env: await runnerRuntimeTokenEnvAsync(managedRestartTokenInput(agent, policy.value, requestId, requestedBy, projectId, combinedExtraCwdPrefixes)),
+      ...managedRestartOptions(opts, restartResumeWorkspace),
     };
     return opts.resumeId ? withResumeParams(params, opts.resumeId, agent.id) : params;
   }
@@ -257,15 +233,55 @@ async function buildRestartSpawnParamsForAgentAsync(
   const profileName = role ? role.profileName : stringValue(agent.meta?.profile);
   const resolvedProfile = role ? undefined : await withResolvedProvisioningAsync(profileName ? getAgentProfile(profileName)?.value : undefined, provider);
   const agentProfile = role?.agentProfile ?? (resolvedProfile ? applyDefaultSharedMcp(resolvedProfile) : undefined);
-  const resolvedModel = await resolveSpawnModelParamsAsync(provider, model, effort, { modelSource: "runtime", skipDefaultWhenEmpty: true });
+  const resolvedModel = await resolveSpawnModelParamsAsync(provider, model, effort, { modelSource: "runtime" });
   const projectedInstructions = await restartInstructionParamsForAgentAsync(agent, { spawnRequestId: predecessorSpawnRequestId, cwd, ...(role ? { profile: role.agentProfile } : {}) }) ?? {};
   const projectId = resolveProjectForCanonicalCwd(cwd).project?.id;
   const stewardExtraCwdPrefixes = stewardWorktreeCwdPrefixes(isProvenStewardAgent(agent.id, policyName), cwd, orchestrator.baseDir);
-  return buildRestartSpawnCommand(agent, predecessorSpawnRequestId, agentProfile, projectedInstructions, opts, {
+  const options = {
     provider, modelParams: resolvedModel, cwd, workspaceMode, profile: profileName || undefined,
     ...relaunch.carried, ...role?.spawn, policyName: policyName || undefined, spawnRequestId: requestId,
     requestedBy,
-  }, { orchestratorId: orchestrator.id, projectId, extraCwdPrefixes: stewardExtraCwdPrefixes });
+  };
+  const tokenContext = { orchestratorId: orchestrator.id, projectId, extraCwdPrefixes: stewardExtraCwdPrefixes };
+  return buildRestartSpawnCommand(agent, predecessorSpawnRequestId, agentProfile, projectedInstructions, opts, options, tokenContext,
+    await runnerRuntimeTokenEnvAsync(restartTokenInput(agent, options, tokenContext)));
+}
+
+function managedRestartOptions(opts: RestartOptions, restartResumeWorkspace: ReturnType<typeof resumeWorkspaceForRestart>) {
+  return {
+    ...(opts.continuation ? { prompt: opts.continuation } : {}),
+    ...(restartResumeWorkspace ? { resumeWorkspace: restartResumeWorkspace } : {}),
+    // F5 — carry the self-restart generation marker on BOTH successor spawns (policy and
+    // dashboard/non-policy), so the audit lineage is symmetric regardless of branch.
+    ...(opts.generation ? { extra: { selfRestart: { generation: opts.generation, reason: opts.reason } } } : {}),
+  };
+}
+
+function managedRestartTokenInput(agent: AgentCard, policy: SpawnPolicy, requestId: string, requestedBy: string, projectId: string | undefined, extraCwdPrefixes: string[]): RunnerRuntimeTokenInput {
+  return {
+    authority: SUCCESSOR_LAUNCH, agentId: agent.id, orchestratorId: policy.orchestratorId,
+    cwd: policy.cwd, provider: policy.provider, label: policy.label, policyName: policy.name,
+    spawnRequestId: requestId, createdBy: requestedBy, profile: policy.profile || undefined,
+    // #2245: both successor paths stamp the policy's current posture into signed constraints.
+    approvalMode: policy.permissionMode,
+    ...(agent.teamId ? { teamId: agent.teamId } : {}),
+    ...(projectId ? { projectId } : {}),
+    ...(extraCwdPrefixes.length ? { extraCwdPrefixes } : {}),
+  };
+}
+
+type RestartTokenContext = Pick<RunnerRuntimeTokenInput, "orchestratorId" | "projectId" | "extraCwdPrefixes">;
+const restartApprovalMode = (agent: AgentCard): SpawnApprovalMode => (stringValue(agent.meta?.approvalMode) as SpawnApprovalMode | undefined) ?? "guarded";
+const restartLabel = (agent: AgentCard): string | undefined => (stringValue(agent.meta?.label) ?? agent.label) || undefined;
+
+/** The successor token a non-policy restart carries; the sync twin and the writer-op path mint the same input. */
+function restartTokenInput(agent: AgentCard, options: Omit<Parameters<typeof buildSpawnCommand>[0], "env">, tokenContext: RestartTokenContext): RunnerRuntimeTokenInput {
+  return { ...tokenContext, authority: SUCCESSOR_LAUNCH,
+    agentId: agent.id, cwd: options.cwd, provider: options.provider, label: restartLabel(agent),
+    policyName: options.policyName, spawnRequestId: options.spawnRequestId,
+    createdBy: options.requestedBy, profile: options.profile, approvalMode: restartApprovalMode(agent),
+    ...(agent.teamId ? { teamId: agent.teamId } : {}),
+  };
 }
 
 function buildRestartSpawnCommand(
@@ -275,25 +291,21 @@ function buildRestartSpawnCommand(
   projectedInstructions: Record<string, unknown>,
   opts: RestartOptions,
   options: Omit<Parameters<typeof buildSpawnCommand>[0], "env">,
-  tokenContext: Pick<Parameters<typeof runnerRuntimeTokenEnv>[0], "orchestratorId" | "projectId" | "extraCwdPrefixes">,
+  tokenContext: RestartTokenContext,
+  env: Record<string, string>,
 ): Record<string, unknown> {
   const memorySeam = parseMemorySeam(projectedInstructions.memorySeam);
   const resumeWorkspace = resumeWorkspaceForRestart(agent);
   const providerArgs = metaStringArray(agent.meta, "providerArgs");
-  const approvalMode = (stringValue(agent.meta?.approvalMode) as SpawnApprovalMode | undefined) ?? "guarded";
-  const label = (stringValue(agent.meta?.label) ?? agent.label) || undefined;
+  const approvalMode = restartApprovalMode(agent);
+  const label = restartLabel(agent);
   const params = buildSpawnCommand({
     ...options,
     orchestratorId: tokenContext.orchestratorId,
     headless: true, requestedAt: Date.now(),
     ...(opts.continuation ? { prompt: opts.continuation } : {}),
     ...(opts.generation ? { extra: { selfRestart: { generation: opts.generation, reason: opts.reason } } } : {}),
-    env: runnerRuntimeTokenEnv({ ...tokenContext, authority: SUCCESSOR_LAUNCH,
-      agentId: agent.id, cwd: options.cwd, provider: options.provider, label,
-      policyName: options.policyName, spawnRequestId: options.spawnRequestId,
-      createdBy: options.requestedBy, profile: options.profile, approvalMode,
-      ...(agent.teamId ? { teamId: agent.teamId } : {}),
-    }),
+    env,
     agentId: agent.id, tags: agent.tags, systemTags: agent.systemTags, capabilities: agent.capabilities,
     label,
     approvalMode, permissionMode: approvalMode,

package/src/services/self-care-state.ts

@@ -2,9 +2,10 @@ import { renderLiveRunsSection } from "../live-runs-section";
 import { renderOpenDecisionsSection } from "../operator-decisions-section";
 import { renderIdleEpicsSection } from "./idle-epics";
 import { renderPlanWakeDigest } from "./plan-wake-digest";
+import { renderPausedRunsSection } from "./workflow-pause-text";
 
 /** Stored live state survives every self-care boundary; tracker refresh must never block a wake. */
 export function renderSelfCareState(agentId: string): string {
   return [renderLiveRunsSection(agentId), renderOpenDecisionsSection(agentId),
-    renderIdleEpicsSection(agentId, [], false), renderPlanWakeDigest(agentId)].filter(Boolean).join("\n\n");
+    renderIdleEpicsSection(agentId, [], false), renderPlanWakeDigest(agentId), renderPausedRunsSection(agentId)].filter(Boolean).join("\n\n");
 }

package/src/services/self-effort.ts

@@ -1,5 +1,5 @@
 import { stringValue, type SpawnProvider } from "@humwick/sdk";
-import { VALID_EFFORTS, findProviderCatalog, findProviderCatalogModel, type ProviderCatalogEntry } from "@humwick/sdk/provider-catalog";
+import { findProviderCatalog, findProviderCatalogModel, type ProviderCatalogEntry } from "@humwick/sdk/provider-catalog";
 import { findConfirmedEffortSwitch, findLaunchEffort, type LaunchEffort } from "../db/commands-effort-read";
 import { getAgentEffortState } from "../db/agent-effort-state";
 import { SELF_EFFORT_BAND, getSelfEffortCeiling, type SelfEffortIdentity } from "../db/self-effort-permissions";
@@ -44,7 +44,7 @@ export function resolveSpawnSelfEffort(
     if (!(base ?? known?.defaultEffort)) throw new ValidationError("selfEffort without selfEffortCeiling needs a base effort: set effort, or pass selfEffortCeiling");
     return { band: true };
   }
-  const levels = known?.efforts ?? VALID_EFFORTS;
+  const levels = known?.efforts ?? [];
   if (!levels.includes(ceiling)) {
     throw new ValidationError(`selfEffortCeiling ${ceiling} is not an effort ${known ? `${known.provider} model ${known.alias}` : provider} offers (${levels.join(", ")})`);
   }
@@ -90,7 +90,7 @@ export function selfEffortBase(agent: AgentCard): string | undefined {
 
 /** One step down and one step up from `base` on `ladder`, clamped at both ends. */
 export function selfEffortBand(base: string, ladder: readonly string[]): { floor: string; ceiling: string } {
-  const levels = ladder.includes(base) ? ladder : VALID_EFFORTS;
+  const levels = ladder.includes(base) ? ladder : [base];
   const at = levels.indexOf(base);
   return { floor: levels[Math.max(0, at - 1)]!, ceiling: levels[Math.min(levels.length - 1, at + 1)]! };
 }
@@ -119,7 +119,7 @@ export function selfEffortPolicyFor(agent: AgentCard, grant: SelfEffortGrant, mo
   if ("ceiling" in grant) return { ceiling: grant.ceiling };
   const base = selfEffortBase(agent);
   if (!base) throw new ValidationError("your self-change band has no base effort; ask your coordinator to set your effort");
-  return { band: true, base, ...selfEffortBand(base, modelEfforts ?? agentCatalogModel(agent)?.efforts ?? VALID_EFFORTS) };
+  return { band: true, base, ...selfEffortBand(base, modelEfforts ?? agentCatalogModel(agent)?.efforts ?? [base]) };
 }
 
 /** #2950 H3 — a restart successor launches at the agent's desired effort (#2984: applied or still pending),
@@ -138,7 +138,7 @@ export function restartEffortState(agent: AgentCard): { effort?: string; carried
 export function assertSelfEffortAllowed(agent: AgentCard, level: string, modelEfforts: readonly string[] | undefined): SelfEffortPolicy {
   const policy = spawnSelfEffortPolicy(agent, modelEfforts);
   if (!policy) throw new ValidationError("selfEffort is not enabled for you, so you cannot change your own effort; ask your coordinator");
-  const ladder = modelEfforts?.includes(policy.ceiling) ? modelEfforts : VALID_EFFORTS;
+  const ladder = modelEfforts ?? agentCatalogModel(agent)?.efforts ?? [];
   const at = ladder.indexOf(level);
   if (at < 0 || at > ladder.indexOf(policy.ceiling)) {
     throw new ValidationError(policy.band

package/src/services/send-message.ts

@@ -45,6 +45,7 @@ import {
 import { recentFinalResponseCaptureIds } from "../db/lineage-startup-captures";
 import { yieldToEventLoop } from "../event-loop-yield";
 import { markAgentWorkFinal } from "./work-finality";
+import { agentProviderState } from "../provider-state";
 import { planSend, type DeliveryReceipt } from "../agent-ref";
 import { receiptWithChannelSuppression } from "./channel-suppression-receipt";
 import { emitMessageDeliveryUpdated, emitMessageQueued, emitNewMessages } from "../sse";
@@ -203,7 +204,8 @@ function resolveSendTarget(input: SendMessageInput, from: string): DeliveryRecei
   }
   // excludeId: a bare ref must never resolve back to its own author — that self-loop silently
   // swallows the message (the reddit-briefing → telegram bridge break, #290).
-  const plan = planSend(input.to, listAgents(), { excludeId: from });
+  const agents = listAgents();
+  const plan = planSend(input.to, agents, { excludeId: from });
   // Ambiguous is a real "can't decide" → reject on every transport (categorically unlike
   // not_found, which stores). HTTP → 409, MCP → invalid-params.
   if (plan.kind === "ambiguous") throw new AmbiguousTargetError(plan.message);
@@ -215,6 +217,8 @@ function resolveSendTarget(input: SendMessageInput, from: string): DeliveryRecei
   // direct (incl. a single OFFLINE match — receipt already carries reason "recipient offline")
   // / fanout / passthrough: adopt the canonical (possibly rewritten) id + the receipt.
   input.to = plan.to;
+  const providerState = agentProviderState(agents.find(agent => agent.id === plan.to));
+  if (providerState?.reason === "providerSetupRequired") throw new ValidationError(providerState.message ?? providerState.recommendedAction ?? "Provider setup required; restart the runner after completing setup.");
   return plan.receipt;
 }
 

package/src/services/spawn-agent.ts

@@ -44,7 +44,7 @@ import { emitCommandEvent } from "../command-events";
 import { redactCommandSecrets } from "../command-secrets";
 import { buildSpawnCommand, generateSpawnRequestId } from "../spawn-command"; import { systemTagsForSpawn } from "../agent-system-tags";
 import { resolveSpawnLandBlocked } from "../land-block";
-import { runnerRuntimeTokenEnv } from "../runtime-tokens";
+import { runnerRuntimeTokenEnvAsync } from "../runtime-tokens";
 import { liveSpawnQuota } from "../spawn-quota";
 import { resolveCanonicalHost } from "../host-identity";
 import { resolveSpawnHostAnchor } from "../spawn-targets";
@@ -59,6 +59,7 @@ import { isolatedSpawnGitRepoError, resolveSpawnRepoRoot } from "./spawn-repo-pr
 import { autoSeedProjectForCwdAsync } from "./project"; import { applyProjectCapabilityGates } from "../project-trust";
 import { assertProjectRoleMcpCwd, assertProjectRoleMcpTrusted, projectRoleProfile, projectRoleProvenance, projectRoleSpawnDefaults, withRoleProfile } from "../project-roles";
 import { spawnWarnings } from "./spawn-warnings";
+import { enforceSpawnPolicy, spawnerKind, spawnPolicyTask, type AppliedSpawnPolicy } from "./spawn-policy";
 import { resolveSpawnProjectRole } from "./spawn-project-role";
 import { profileProviderPin, resolveSpawnLaunch } from "./spawn-launch";
 import { hydrateTaskContext, projectTaskHydration } from "./task-context-hydration";
@@ -210,6 +211,8 @@ export interface SpawnAgentInput extends SelfEffortSpawnInput {
   roleSnapshot?: import("../project-roles").ProjectRole;
   workflowCaller?: WorkflowSpawnQuota;
   roleSha?: string; workflowRunId?: string; roleProfile?: string; taskRepoCwd?: string; roleHost?: string;
+  /** #3736 — the workflows of the run tree spawning this step, for a spawn-policy `require.workflow`. Service-only. */
+  workflowNames?: string[];
   prompt?: string;
   systemPromptAppend?: string;
   /**
@@ -324,6 +327,8 @@ export interface SpawnAgentResult {
   dispatchDecision?: Awaited<ReturnType<typeof dispatchTaskAsync>>;
   /** #3043 — the spawn went ahead, but the caller should know (a role read from a stale default branch). */
   warnings?: string[];
+  /** #3736 — the project spawn-policy rules that applied to this spawn. */
+  spawnPolicy?: AppliedSpawnPolicy;
 }
 
 /** Reject when a component token's signed resource constraints disallow the target (#323). */
@@ -428,6 +433,11 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   });
 
   assertOrchestratorSupportsLaunchMode(orchestrator, launchMode, input.providerArgs);
+  // #3736 — the project's spawn policy, before any side effect: a refusal names the rule, the allowed set and the hint.
+  const spawnPolicy = await enforceSpawnPolicy(
+    { projectId: lazyRoot?.projectId ?? resolveProjectForCwd(resolvedCwd)?.id, ...(lazyRoot ? {} : { checkout: { cwd: resolvedCwd, orchestratorId: orchestrator.id } }) },
+    { spawner: spawnerKind(ctx, input, caller), task: spawnPolicyTask(linkedTask), subject: { role: projectRole?.name, profile: profileName, workflows: input.workflowNames } },
+  );
 
   // Resolve + validate the named agent profile server-side (was HTTP-only; the MCP path passed
   // the name through unvalidated). Omitted profile uses Relay's spawn default so coordinator
@@ -703,7 +713,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // Child runner token. `agentInitiated` (set whenever an agent is the caller) forces a
   // non-spawn-capable child (no grandchildren); `spawnedBy` stamps authoritative lineage the
   // child can't forge (it registers with spawnedBy = caller, read from the signed token).
-  const env = { ...callerEnv, ...runnerRuntimeTokenEnv({
+  const env = { ...callerEnv, ...await runnerRuntimeTokenEnvAsync({
     agentId: targetAgentId,
     orchestratorId: orchestrator.id,
     cwd: resolvedCwd,
@@ -900,6 +910,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     ...(autoScaffoldedTask ? { task: autoScaffoldedTask } : {}),
     ...(taskDispatchDecision ? { dispatchDecision: taskDispatchDecision } : {}),
     ...(warnings.length ? { warnings } : {}),
+    ...(spawnPolicy ? { spawnPolicy } : {}),
   };
 }
 

package/src/services/spawn-chain-inspector.ts

@@ -24,7 +24,7 @@ import { join } from "node:path";
 import type { LaunchMode, SpawnProvider } from "@humwick/sdk";
 import { withResolvedProvisioning } from "../db";
 import { getAgentProfile } from "../config-store";
-import { buildSpawnCommand } from "../spawn-command";
+import { buildSpawnCommand, resolveSpawnModelParams } from "../spawn-command";
 import { spawnOptionsFromControl } from "../../orchestrator/src/control";
 import type { SpawnOptions } from "../../orchestrator/src/spawn/types";
 import { buildEnv, buildRunnerCommand } from "../../orchestrator/src/spawn/command";
@@ -139,18 +139,10 @@ export function prepareSpawnChain(opts: SpawnChainRequest, observe?: SpawnChainP
     prompt: opts.spawn?.prompt,
     systemPromptAppend: opts.spawn?.systemPromptAppend,
     headless: opts.spawn?.headless ?? true,
-    ...(opts.spawn?.model || opts.spawn?.effort || opts.spawn?.contextWindowTokens !== undefined
-      ? {
-        modelParams: {
-          ...(opts.spawn.model ? { model: opts.spawn.model, providerModel: opts.spawn.model } : {}),
-          ...(opts.spawn.effort ? { effort: opts.spawn.effort } : {}),
-          // #2595 — window passes through the same payload field production threads.
-          ...(typeof opts.spawn.contextWindowTokens === "number" && Number.isSafeInteger(opts.spawn.contextWindowTokens) && opts.spawn.contextWindowTokens > 0
-            ? { contextWindowTokens: opts.spawn.contextWindowTokens }
-            : {}),
-        },
-      }
-      : {}),
+    modelParams: {
+      ...resolveSpawnModelParams(provider, opts.spawn?.model, opts.spawn?.effort),
+      ...(opts.spawn?.contextWindowTokens !== undefined ? { contextWindowTokens: opts.spawn.contextWindowTokens } : {}),
+    },
   } as Parameters<typeof buildSpawnCommand>[0]);
 
   return prepareCommandChain(cmdParams, opts, observe);
@@ -216,6 +208,7 @@ export function prepareCommandChain(
     provider: cli.provider,
     ...(cli.model ? { model: cli.model } : {}),
     ...(cli.effort ? { effort: cli.effort } : {}),
+    ...(cli.modelRecord ? { modelRecord: cli.modelRecord } : {}),
     // #2595 — the real runner CLI carries the window as a flag; carry it through the same seam.
     ...(cli.contextWindowTokens !== undefined ? { contextWindowTokens: cli.contextWindowTokens } : {}),
     runnerId: "inspector",

package/src/services/spawn-policy.ts

@@ -0,0 +1,68 @@
+// #3736 — the one spawn-policy check. spawnAgent runs it for every spawn (relay_spawn_agent,
+// relay_task_dispatch, POST /api/agents/spawn, workflow steps, sub-coordinators); the workflow
+// auto-start asks it which workflow a Task's work runs through. A project without the file, or with
+// an invalid or unreadable one, is not restricted: stored config never fails a spawn.
+import { stringValue, type AgentCard } from "@humwick/sdk";
+import {
+  matchSpawnPolicy, SPAWN_POLICY_FILE, spawnPolicyAtCommit, spawnPolicyRefusal, spawnPolicyWorkflow,
+  type SpawnerKind, type SpawnPolicy, type SpawnPolicySubject, type SpawnPolicyTask,
+} from "@humwick/sdk/spawn-policy";
+import { ValidationError } from "../db";
+import type { AuthContext } from "./auth-context";
+import { readProjectConfigFirst, type ProjectCheckout } from "./project-config-read";
+
+/** Where the policy is read: the spawn's own checkout first, then the project's registered roots. */
+export interface SpawnPolicyWhere {
+  projectId?: string;
+  checkout?: ProjectCheckout;
+}
+
+/** The rules that applied, for the caller's receipt. */
+export interface AppliedSpawnPolicy {
+  file: string;
+  ref: string;
+  sha: string;
+  rules: string[];
+}
+
+interface LoadedSpawnPolicy {
+  policy: SpawnPolicy;
+  ref: string;
+  sha: string;
+}
+
+async function loadSpawnPolicy(where: SpawnPolicyWhere): Promise<LoadedSpawnPolicy | undefined> {
+  if (!where.projectId) return undefined;
+  const { lookup } = await readProjectConfigFirst(where.projectId, where.checkout ? [where.checkout] : [], SPAWN_POLICY_FILE, spawnPolicyAtCommit, "spawns are not restricted until it is fixed");
+  return lookup?.status === "found" ? { policy: lookup.config, ref: lookup.ref, sha: lookup.sha } : undefined;
+}
+
+/** A workflow run's step, a sub-coordinator, any other agent, or a caller with no agent (dashboard, operator). */
+export function spawnerKind(ctx: AuthContext, input: { workflowRunId?: string }, caller: AgentCard | undefined): SpawnerKind {
+  if (ctx.actor.kind === "system" && input.workflowRunId) return "workflow";
+  if (!caller) return "operator";
+  return stringValue(caller.meta?.profile) === "sub-coordinator" ? "sub-coordinator" : "coordinator";
+}
+
+export function spawnPolicyTask(task: { id: number; tags?: readonly string[]; paths?: readonly string[] } | undefined): SpawnPolicyTask | undefined {
+  return task ? { id: task.id, ...(task.tags ? { tags: task.tags } : {}), ...(task.paths ? { paths: task.paths } : {}) } : undefined;
+}
+
+/** Refuses a spawn the project's policy does not allow (a `ValidationError` naming the rule, the
+ *  allowed set and the hint); otherwise the rules that applied, if any. */
+export async function enforceSpawnPolicy(where: SpawnPolicyWhere, facts: { spawner: SpawnerKind; task?: SpawnPolicyTask; subject: SpawnPolicySubject }): Promise<AppliedSpawnPolicy | undefined> {
+  const loaded = await loadSpawnPolicy(where);
+  if (!loaded) return undefined;
+  const rules = matchSpawnPolicy(loaded.policy, facts);
+  if (!rules.length) return undefined;
+  const refusal = spawnPolicyRefusal(rules, facts.subject, facts.task);
+  if (refusal) throw new ValidationError(refusal);
+  return { file: SPAWN_POLICY_FILE, ref: loaded.ref, sha: loaded.sha, rules: rules.map((rule) => rule.name) };
+}
+
+/** The workflow the project's policy routes this Task's work through, and the rule that says so. */
+export async function spawnPolicyWorkflowFor(where: SpawnPolicyWhere, facts: { spawner: SpawnerKind; task: SpawnPolicyTask }): Promise<{ workflow: string; rule: string } | undefined> {
+  const loaded = await loadSpawnPolicy(where);
+  const chosen = loaded && spawnPolicyWorkflow(matchSpawnPolicy(loaded.policy, facts));
+  return chosen ? { workflow: chosen.workflow, rule: chosen.rule.name } : undefined;
+}