@humwick/server 0.130.1 → 0.130.3

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-grant.ts

@@ -1,3 +1,5 @@
+import { grantSelfEffortAsync } from "../db/agent-control-async";
+export { SELF_EFFORT_GRANT_COMMAND } from "../db/agent-control-write";
 import { randomUUID } from "node:crypto";
 import { stringValue } from "@humwick/sdk";
 import { createCommandInternal, updateCommandInternal } from "../commands-db";
@@ -14,7 +16,7 @@ import type { Command } from "../types";
 
 // #2966 — the operator turns selfEffort on or off for a running agent. The permission row is the
 // state; the settled command written beside it is the audit record.
-export const SELF_EFFORT_GRANT_COMMAND = "agent.grantSelfEffort";
+
 
 interface SelfEffortGrantInput extends SelfEffortSpawnInput {
   agentId: string;
@@ -27,7 +29,7 @@ interface SelfEffortGrantInput extends SelfEffortSpawnInput {
 export async function grantSelfEffort(input: SelfEffortGrantInput, ctx: AuthContext): Promise<{ selfEffort: SelfEffortPolicy | null; command: Command }> {
   const agent = getAgent(input.agentId);
   if (!agent) throw new AgentActionTargetError(`agent ${input.agentId} not found`);
-  authorizeShutdown(ctx, { agentId: agent.id, requestedVia: input.requestedVia });
+  (await authorizeShutdown(ctx, { agentId: agent.id, requestedVia: input.requestedVia }));
   const spawnRequestId = stringValue(agent.meta?.spawnRequestId);
   if (typeof input.selfEffort !== "boolean") throw new ValidationError("selfEffort must be true or false");
   const model = agent.providerCapabilities?.model;
@@ -64,29 +66,7 @@ export async function grantSelfEffort(input: SelfEffortGrantInput, ctx: AuthCont
   revalidateAgentInstance(agent);
   // Nothing executes a grant: it is written settled with the permission in one transaction. The
   // identity is resolved inside it, so a stale writer cannot restore a deleted policy's row.
-  const command = writeTransaction(() => {
-    const now = Date.now();
-    const identity = selfEffortIdentity(agent);
-    setSelfEffortCeilingInternal(identity, !grant ? null : "band" in grant ? SELF_EFFORT_BAND : grant.ceiling, requestedBy, now);
-    createCommandInternal({ id: commandId, input: {
-      type: SELF_EFFORT_GRANT_COMMAND,
-      source: "system",
-      target: agent.id,
-      ...(spawnRequestId ? { correlationId: spawnRequestId } : {}),
-      params: {
-        agentId: agent.id,
-        ...(spawnRequestId ? { spawnRequestId } : {}),
-        permission: identity,
-        selfEffort,
-        previousSelfEffort: previous,
-        requestedBy,
-        ...(input.requestedByUser ? { requestedByUser: input.requestedByUser } : {}),
-        requestedVia: input.requestedVia,
-        requestedAt: now,
-      },
-    } }, now);
-    return updateCommandInternal(commandId, { status: "succeeded", result: { selfEffort } }, {}, now).command!;
-  });
+  const command = await grantSelfEffortAsync({ agent, grant, requestedBy, commandId, spawnRequestId, input, selfEffort, previous });
   emitCommandEvent(command, "command.succeeded");
   emitActivityEvent(event);
   return { selfEffort, command };

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

@@ -1,7 +1,9 @@
+import { promoteLineageCapturedResponseAsync } from "../db/runtime-tail-async";
+import { sendMessageWithResultAsync } from "../db/message-send";
 import { refusedResponseReport } from "./response-report-admission";
 import { suppressResultsOnlyAck, isResultsOnlyAckCandidate } from "../db/message-send-suppression";
 import { getGateway } from "../db/gateway";
-import { getMessageAsync, channelObligationAnsweredByAsync } from "../db";
+import { getMessageAsync, channelObligationAnsweredByAsync, ValidationError, getAgent, getMessage, isChannelAgentId, listAgents, sendMessagesBatchWithResultAsync, channelObligationAnsweredBy, agentPrincipalUserId, isMultiUserWorld, type SendMessageResult as DbSendMessageResult } from "../db";
 import { agentPrincipalSink } from "../db/agent-ownership";
 // Transport convergence (epic #342, slice #346) — the message-send service.
 //
@@ -27,24 +29,10 @@ import { agentPrincipalSink } from "../db/agent-ownership";
 // OUT OF SCOPE (transport-edge, excluded from the parity facet): automatic memory injection
 // (needs request-derived context) and per-transport audit (HTTP domain row vs MCP tool-call row).
 import { LEGACY_HUMAN_AGENT_ID, USER_NAMESPACE_PREFIX, userSinkId, canonicalHumanAgentId, heldForSender, isHumanAgentId, isMechanicalMessageKind, isRecord, isReservedAgentId, isTurnFinalSession } from "@humwick/sdk";
-import {
-  ValidationError,
-  getAgent,
-  getMessage,
-  isChannelAgentId,
-  listAgents,
-  promoteLineageCapturedResponse,
-  sendMessagesBatchWithResultAsync,
-  sendMessageWithResult,
-  sendMessageWithResultAsync,
-  channelObligationAnsweredBy,
-  agentPrincipalUserId,
-  isMultiUserWorld,
-  type SendMessageResult as DbSendMessageResult,
-} from "../db";
 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 +191,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 +204,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;
 }
 
@@ -363,18 +354,12 @@ function agentSendAllowed(input: SendMessageInput, ctx: AuthContext, sender: Mes
   return inSameMessagingRun(sender, getAgent(input.to));
 }
 
-export function sendMessageService(
+export async function sendMessageService(
   input: SendMessageInput,
   ctx: AuthContext,
   opts: SendMessageOptions = {},
-): SendMessageResult {
-  const { receipt, suppressedParent } = prepareSendMessage(input, ctx, opts);
-  if (suppressedParent) return { message: suppressedParent, created: false, receipt };
-  const result = sendMessageWithResult(input, { allowUnregisteredSender: opts.allowUnregisteredSender });
-  const sent = { message: result.message, created: result.created, receipt: finalizeReceipt(result.message, receipt) };
-  if (opts.deferLiveEffects) return { ...sent, publish: () => emitSendResults([result]) };
-  emitSendResults([result]);
-  return sent;
+): Promise<SendMessageResult> {
+  return sendMessageServiceAsync(input, ctx, opts);
 }
 
 /** Async persistence and message-history reads; live target authorization and emits stay on main.
@@ -387,8 +372,10 @@ export async function sendMessageServiceAsync(
   const { receipt, suppressedParent } = await prepareSendMessageAsync(input, ctx, opts);
   if (suppressedParent) return { message: suppressedParent, created: false, receipt };
   const result = await sendMessageWithResultAsync(input, { allowUnregisteredSender: opts.allowUnregisteredSender });
-  emitSendResults([result]);
-  return { message: result.message, created: result.created, receipt: finalizeReceipt(result.message, receipt) };
+  const sent = { message: result.message, created: result.created, receipt: finalizeReceipt(result.message, receipt) };
+  if (opts.deferLiveEffects) return { ...sent, publish: async () => (await emitSendResults([result])) };
+  (await emitSendResults([result]));
+  return sent;
 }
 
 export async function sendMessagesBatchService(
@@ -422,7 +409,7 @@ export async function sendMessagesBatchService(
       receipt: finalizeReceipt(result.message, prepared[outputIndex]!.receipt),
     };
   }
-  emitSendResults(stored);
+  (await emitSendResults(stored));
   return results;
 }
 
@@ -500,11 +487,11 @@ export async function sweepDeferredLineageReportsOnStartup(now: number = Date.no
     // A tagged capture was already flushed before boot (or by an earlier sweep). Skipping it avoids
     // re-arming the held ring, minting a second finality window, and re-emitting `message.finalized`.
     if (isRecord(capture.payload?.finality)) continue;
-    const promoted = promoteLineageCapturedResponse(capture);
+    const promoted = (await promoteLineageCapturedResponseAsync(capture));
     if (promoted?.created) emitted.push(promoted.message);
     // The ordinary 10-minute cutoff protects live coalescing. Recovery is already bounded by the
     // 24-hour query, and persistence proves this capture's source turn completed before boot.
-    const recovered = markAgentWorkFinal(capture.from, "edge-fallback", { includeStaleCompletedFinals: true });
+    const recovered = (await markAgentWorkFinal(capture.from, "edge-fallback", { includeStaleCompletedFinals: true }));
     recoveredCount += recovered.forwarded.filter((entry) => entry.created).length;
   }
   if (emitted.length > 0) emitNewMessages(emitted);
@@ -513,7 +500,7 @@ export async function sweepDeferredLineageReportsOnStartup(now: number = Date.no
   return { promoted: emitted.length + recoveredCount, scanned, ...(signal?.aborted ? { aborted: true as const } : {}) };
 }
 
-function emitSendResults(results: DbSendMessageResult[]): void {
+export async function emitSendResults(results: DbSendMessageResult[]): Promise<void> {
   const liveMessages: Message[] = [];
   for (const result of results) {
     if (result.created) {
@@ -534,13 +521,13 @@ function emitSendResults(results: DbSendMessageResult[]): void {
           emitMessageDeliveryUpdated(result.message);
         }
       }
-      const promoted = promoteLineageCapturedResponse(result.message);
+      const promoted = (await promoteLineageCapturedResponseAsync(result.message));
       if (promoted?.created) liveMessages.push(promoted.message);
     } else if (result.updated) {
       // Session-step upsert (#parity): the row changed in place (same DB id). Re-emit so the
       // dashboard's id-keyed merge replaces the existing step live — no duplicate row.
       liveMessages.push(result.message);
-      const promoted = promoteLineageCapturedResponse(result.message);
+      const promoted = (await promoteLineageCapturedResponseAsync(result.message));
       if (promoted?.created) liveMessages.push(promoted.message);
     }
   }

package/src/services/shutdown-agent.ts

@@ -1,3 +1,5 @@
+import { createAgentControlAsync } from "../db/agent-control-async";
+import type { SafeCandidate } from "./idle-agent-digest";
 import { spawnTreeContains } from "../db/spawn-tree";
 import { spawnDelegationState } from "../db/spawn-delegation-state";
 // Transport convergence (epic #342, slice #347) — the agent-shutdown service.
@@ -37,7 +39,6 @@ import { spawnDelegationState } from "../db/spawn-delegation-state";
 // system auth" — the steward-reaper's forceful escalation does; its graceful first attempt does not.
 import {
   ValidationError,
-  inWriteTransaction,
   createActivityEventAsync,
   getAgent,
   getOrchestrator,
@@ -46,7 +47,7 @@ import {
   mergeAgentMetaAsync,
 } from "../db";
 import { randomUUID } from "node:crypto";
-import { createCommandInternal, findSpawnCommandByRequestId, getCommand } from "../commands-db";
+import { findSpawnCommandByRequestId, getCommand } from "../commands-db";
 import { SPAWN_CANCELABLE_STATUSES } from "../spawn-intent";
 import { isRestartSensitiveCommand } from "../db/restart-sensitive";
 import { cancelCommandIfStatusAsync } from "../commands-write";
@@ -112,6 +113,7 @@ interface ShutdownAgentInput {
   /** #3428 — automatic disposal only: re-checked on the fresh card at command admission, after
    * every await; a returned reason refuses the shutdown. */
   admit?: (agent: AgentCard) => string | undefined;
+  idleCandidate?: SafeCandidate;
 }
 
 interface ShutdownAgentResult {
@@ -173,7 +175,7 @@ export interface ShutdownAuthorization {
 
 /** The #221 parent→child gate — the single home for shutdown authorization across all
  * three transports. Throws `ShutdownAuthError` on denial; full-reach callers bypass ownership. */
-export function authorizeShutdown(ctx: AuthContext, input: ShutdownAgentInput, action = "shutdown"): ShutdownAuthorization {
+export async function authorizeShutdown(ctx: AuthContext, input: ShutdownAgentInput, action = "shutdown"): Promise<ShutdownAuthorization> {
   const callerId = ctx.callerAgentId;
   // A scoped agent caller may target only its OWN live spawned children — or (#2618) live members
   // of a team it currently coordinates, e.g. after claiming a dead coordinator's team. Two PRECISE
@@ -211,7 +213,7 @@ export function authorizeShutdown(ctx: AuthContext, input: ShutdownAgentInput, a
       }
     }
     // #3567 — the one lifecycle-control check (principal, role, coordinator authority).
-    const denied = authorizeAgentControl(ctx, target, action);
+    const denied = (await authorizeAgentControl(ctx, target, action));
     if (denied) {
       throw new ShutdownAuthError(denied.reason === "coordinator" && !input.agentId
         ? `no spawned child of yours matches spawnRequestId ${input.spawnRequestId}` : denied.message);
@@ -315,7 +317,7 @@ async function reapInFlightSpawnCommand(
     return { command: canceled ?? command, orchestratorId: (canceled ?? command).target, agent: null };
   }
   emitCommandEvent(canceled, "command.canceled");
-  notifyAgentSpawnFailed({
+  await notifyAgentSpawnFailed({
     parent: stringValue(canceled.params.spawnedBy) ?? ctx.callerAgentId ?? ctx.actor.id,
     spawnRequestId: input.spawnRequestId,
     provider: stringValue(canceled.params.provider),
@@ -334,11 +336,11 @@ async function reapInFlightSpawnCommand(
  * shutting-down (uniform across transports — MCP previously skipped this), and writes the
  * audit row. The single fat-service entry point the three thin transports call. */
 export function shutdownAgent(input: ShutdownAgentInput, ctx: AuthContext): Promise<ShutdownAgentResult> {
-  return withRelayEventDrain(() => shutdownAgentBody(input, ctx));
+  return withRelayEventDrain(async () => (await shutdownAgentBody(input, ctx)));
 }
 
 async function shutdownAgentBody(input: ShutdownAgentInput, ctx: AuthContext): Promise<ShutdownAgentResult> {
-  const authz = authorizeShutdown(ctx, input);
+  const authz = (await authorizeShutdown(ctx, input));
   if (authz.spawnCommand) return reapInFlightSpawnCommand(authz.spawnCommand, input, ctx);
 
   const agent = input.agentId ? getAgent(input.agentId) : null;
@@ -414,19 +416,20 @@ async function shutdownAgentBody(input: ShutdownAgentInput, ctx: AuthContext): P
   const priorCommand = input.commandId ? getCommand(commandId) : null;
   if (priorCommand) return { command: priorCommand, orchestratorId: orchestrator.id, agent: currentAgent };
   const admit = input.admit;
-  // #3428 — automatic disposal re-decides on the fresh card in the same write transaction as the insert.
-  const command = admit && currentAgent ? inWriteTransaction(() => {
-    const refused = admit(getAgent(currentAgent.id) ?? currentAgent);
+  if (admit && currentAgent) {
+    const refused = admit(currentAgent);
     if (refused) throw new AutomaticShutdownRefused(`automatic shutdown of ${currentAgent.id} refused at admission: ${refused}`);
-    return createCommandInternal({ input: commandInput, id: commandId });
-  }) : createCommandInternal({ input: commandInput, id: commandId });
+  }
+  const admitted = await createAgentControlAsync({ agent: currentAgent, commandId, commandInput, idleCandidate: input.idleCandidate });
+  if (!admitted.command) throw new AutomaticShutdownRefused(`automatic shutdown of ${currentAgent?.id} refused at admission: ${admitted.refused}`);
+  const command = admitted.command;
   emitCommandEvent(command, "command.requested");
-  if (targetAgentId) reapAgentBrowserSessions(targetAgentId); // #3489 — a requested stop takes its browser with it
+  if (targetAgentId) (await reapAgentBrowserSessions(targetAgentId)); // #3489 — a requested stop takes its browser with it
   // #1084 — an explicit shutdown is a platform-owned teardown signal: close the target's work
   // window now rather than let a held final group die silently with the process. `edge-fallback`
   // is the closest fit in the closed source enum — there is no cleaner workspace-ready/task-done
   // signal backing an arbitrary teardown (which may target an agent with neither).
-  if (targetAgentId) markAgentWorkFinal(targetAgentId, "edge-fallback");
+  if (targetAgentId) (await markAgentWorkFinal(targetAgentId, "edge-fallback"));
 
   // Lifecycle indicator — uniform across transports. The MCP path previously skipped
   // this, so an MCP-initiated shutdown left the agent with no "shutting down" signal in

package/src/services/spawn-agent.ts

@@ -1,9 +1,10 @@
+import { taskLinkedRepoCwd } from "./task-repo-cwd";
+export { taskLinkedRepoCwd } from "./task-repo-cwd";
 import { writeChildEnv } from "@humwick/sdk/env";
 import { bindSpawnProjectCheckout } from "./project-checkout-binding";
-import { REPORT_VERBOSITIES, resolveReportVerbosity } from "@humwick/sdk";
+import { REPORT_VERBOSITIES, resolveReportVerbosity, DEFAULT_USER_ID, errMessage, isRecord, stringValue, type LaunchMode, type ReportVerbosity, type SpawnProvider, type TaskDispatch } from "@humwick/sdk";
 import { cleanCallerSpawnEnv } from "../spawn-env";
-import { optionalEnum } from "../validation";
-import { optionalNonNegativeInt } from "../validation";
+import { optionalEnum, optionalNonNegativeInt } from "../validation";
 import { cleanSpawnBudget } from "../spawn-budget";
 import { teamId as newTeamId } from "../db/teams";
 import { getGateway } from "../db/gateway";
@@ -35,8 +36,7 @@ import type { WorkflowSpawnQuota } from "../db/spawn-in-flight";
 // deliberately out of scope here — this slice converges the two external TRANSPORTS.
 import { resolveSpawnApprovalMode } from "./spawn-approval";
 import { assertOrchestratorSupportsLaunchMode, resolveSpawnLaunchMode } from "../launch-mode";
-import { DEFAULT_USER_ID, errMessage, isRecord, stringValue, type LaunchMode, type ReportVerbosity, type SpawnProvider, type TaskDispatch } from "@humwick/sdk";
-import { addProjectRootAsync, countLiveSpawnedAgents, createActivityEventAsync, getAgent, getProject, getTaskDetailAsync, listAgents, listProjects, listWorkspaces, recordTaskSpawnRequestedAsync, reportedRepoRootForCwd, resolveAgentOwnershipAsync, resolveProjectForCwd, rootsForProject, ValidationError, withResolvedProvisioningAsync } from "../db";
+import { addProjectRootAsync, countLiveSpawnedAgents, createActivityEventAsync, getAgent, getProject, listAgents, listWorkspaces, recordTaskSpawnRequestedAsync, reportedRepoRootForCwd, resolveAgentOwnershipAsync, resolveProjectForCwd, rootsForProject, ValidationError, withResolvedProvisioningAsync } from "../db";
 import { acquireCoordinatorTeam } from "./team";
 import { countInFlightSpawnCommands } from "../commands-db";
 import { createSpawnCommandWithinQuotaAsync } from "../commands-write";
@@ -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";
@@ -54,11 +54,12 @@ import { profileNotFoundMessage } from "../spawn-profile-errors";
 import { composeSpawnInstructionsWithEventsAsync } from "../project-instructions";
 import { applyDefaultSharedMcp, type SharedMcpSpawnOverride } from "../shared-mcp";
 import { findGitRepoRoot, isInsideGitWorkTree, pathVisibleLocally } from "./canonical-root";
-import { selectSpawnCwdPlacement } from "./spawn-cwd-placement";
+import { selectSpawnCwdPlacement, spawnBuildWork } from "./spawn-cwd-placement";
 import { isolatedSpawnGitRepoError, resolveSpawnRepoRoot } from "./spawn-repo-probe";
 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";
@@ -151,35 +152,6 @@ export function acquisitionManifestFor(projectId: string, cwd: string): {
   };
 }
 
-export async function taskLinkedRepoCwd(taskId: number, callerCwd?: string): Promise<string> {
-  const task = await getTaskDetailAsync(taskId);
-  if (!task) throw new ValidationError(`task ${taskId} not found or not a deliverable task`);
-  // #2844 — a Task created with `repo:` but no linked issue still names its project repo.
-  const repos = [...new Set([...task.issues.map((issue) => issue.repo), task.repo].filter((repo): repo is string => Boolean(repo)))];
-  if (repos.length === 0) {
-    throw new ValidationError(`task ${taskId} has no linked issue repo; pass cwd/orchestratorId explicitly`);
-  }
-  const candidates = listProjects()
-    .filter((project) => project.issueRepo && repos.includes(project.issueRepo))
-    .flatMap((project) => rootsForProject(project.id).map((root) => ({ project, root })));
-  if (candidates.length === 0) {
-    // #1627 — this refusal is real and names its own cause: with no registered root, relay has no
-    // way to turn "repo owner/name" into a checkout path on a specific host. What made it a trap
-    // was the NEXT step: following its advice (pass cwd + orchestratorId) used to hit the isolated
-    // precondition's local-filesystem probe and get told the repo was "not a git repo". That lie is
-    // fixed at assertIsolatedSpawnHasGitRepo, so the remedy below now works. Name the tool so it is
-    // mechanical rather than a step you have to know exists.
-    throw new ValidationError(`task ${taskId} links repo ${repos.join(", ")} but no Relay project root is registered for it, so relay cannot resolve a checkout path for it; pass cwd + orchestratorId explicitly, or register the checkout with relay_project_add_root`);
-  }
-  const matchingCallerRoot = callerCwd
-    ? candidates
-      .filter((candidate) => isPathWithinBase(callerCwd, candidate.root.rootPath))
-      .sort((a, b) => b.root.rootPath.length - a.root.rootPath.length)[0]
-    : undefined;
-  if (matchingCallerRoot) return matchingCallerRoot.root.rootPath;
-  if (candidates.length === 1) return candidates[0]!.root.rootPath;
-  throw new ValidationError(`task ${taskId} links repo ${repos.join(", ")} with multiple registered roots; pass cwd explicitly`);
-}
 
 /**
  * A normalized spawn request — every transport validates its own wire shape (enums,
@@ -210,6 +182,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 +298,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). */
@@ -385,7 +361,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   const lineageAgent: AgentCard | undefined = (lineageAgentId ? getAgent(lineageAgentId) : undefined) ?? undefined;
   const callerCwd = stringValue(caller?.meta?.cwd) ?? stringValue(lineageAgent?.meta?.cwd);
   const taskDefaultCwd = input.taskId !== undefined && (!input.orchestratorId || input.role !== undefined) && !input.cwd
-    ? input.taskRepoCwd ?? await taskLinkedRepoCwd(input.taskId, callerCwd)
+    ? input.taskRepoCwd ?? await taskLinkedRepoCwd(input.taskId, callerCwd, caller ?? lineageAgent)
     : undefined;
   const requestedCwd = input.cwd ?? taskDefaultCwd ?? (input.role !== undefined ? callerCwd : undefined);
   const roleSpawn = input.roleSnapshot ? { role: input.roleSnapshot, warnings: [] } : input.role === undefined && input.roleSha === undefined ? undefined : await resolveSpawnProjectRole({ role: input.role, roleSha: input.roleSha, profile: input.profile, orchestratorId: input.orchestratorId, cwd: requestedCwd, preferHost: input.roleHost ?? caller?.machine ?? lineageAgent?.machine, allowedOrchestratorIds: ctx.constraints?.orchestrators, canSpawn: canSpawn(ctx) });
@@ -424,10 +400,15 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
     provider: resolvedProvider, orchestratorId: input.orchestratorId, requestedCwd: repoSource ? undefined : requestedCwd, repoSource,
     resumeWorkspace: input.resumeWorkspace, caller, lineageMachine: lineageAgent?.machine,
     callerCwd, allowedOrchestratorIds: ctx.constraints?.orchestrators,
-    shared: workspaceMode === "shared", workspaceMode, canLand: !landBlockResolution.landBlocked, model: modelParams.model, effort: modelParams.effort,
+    shared: workspaceMode === "shared", workspaceMode, canLand: !landBlockResolution.landBlocked, buildWork: spawnBuildWork(profileName, (input.dispatch ?? linkedTask?.dispatch ?? profileSpawnDefaults.dispatch)?.type), model: modelParams.model, effort: modelParams.effort,
   });
 
   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
@@ -476,7 +457,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
 
   if (shouldAutoScaffoldTask(input, profileName)) {
     const brief = spawnBrief(input)!;
-    linkedTask = createTaskEntity({
+    linkedTask = await createTaskEntity({
       title: taskTitleFromBrief(brief, input.label),
       intent: brief,
       latestSteer: input.steer,
@@ -534,7 +515,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   // disk. That's only trustworthy when the spawn's target orchestrator actually shares this
   // filesystem — a remote orchestrator's host can coincidentally have the same path with
   // DIFFERENT content, so the gate is told explicitly rather than inferring from path existence.
-  if (agentProfile.sources?.project) agentProfile = applyProjectCapabilityGates(agentProfile, resolvedCwd, registeredProjectBeforeAutoSeed, { orchestratorLocal: isOrchestratorLocalToRelay(orchestrator), ...(projectRole ? { pinnedMcpCommit: projectRole.source.sha } : {}) });
+  if (agentProfile.sources?.project) agentProfile = (await applyProjectCapabilityGates(agentProfile, resolvedCwd, registeredProjectBeforeAutoSeed, { orchestratorLocal: isOrchestratorLocalToRelay(orchestrator), ...(projectRole ? { pinnedMcpCommit: projectRole.source.sha } : {}) }));
   if (projectRole) assertProjectRoleMcpTrusted(projectRole, agentProfile);
 
   // N7 — project hooks/MCP are executable code and are gated against the project
@@ -589,7 +570,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
   }
 
   // #3107 — the lineage coordinator's active team; a coordinator takes its project's seat, never a dissolved id.
-  const callerTeam = lineageAgentId ? acquireCoordinatorTeam(lineageAgentId) : undefined;
+  const callerTeam = lineageAgentId ? (await acquireCoordinatorTeam(lineageAgentId)) : undefined;
   const privateTeamId = profileName === "sub-coordinator" ? newTeamId() : undefined;
   const launchTeamId = privateTeamId ?? callerTeam?.id;
 
@@ -703,7 +684,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,
@@ -875,7 +856,7 @@ export async function spawnAgent(input: SpawnAgentInput, ctx: AuthContext): Prom
         requestedBy,
         ...(currentTask?.latestSteer ? { steer: currentTask.latestSteer } : {}),
       });
-      autoSubscribeTaskCoordinator(requestedBy, input.taskId);
+      (await autoSubscribeTaskCoordinator(requestedBy, input.taskId));
     } catch (err) {
       console.warn(`task ${input.taskId} spawn attribution skipped: ${errMessage(err)}`);
     }
@@ -900,6 +881,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";
@@ -50,7 +50,7 @@ export interface SpawnChainInspection {
   settings: Record<string, unknown> | null;
   /** The effective launch argv the adapter would exec. */
   argv: string[];
-  /** The launch command (claude / claude-rig). */
+  /** The launch command (e.g. claude). */
   command: string;
   /** relay-provisioned-hooks/<ref> dir for the baseline guard. */
   baselineHookAssetDir: string | undefined;
@@ -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-cwd-placement.ts

@@ -1,16 +1,21 @@
 import { basename, join, relative } from "node:path";
 import { hostname } from "node:os";
-import { normalizeGitRemoteIdentity, stringValue, type AgentCard, type Orchestrator, type SpawnProvider, type WorkspaceMode, type ProjectRoot } from "@humwick/sdk";
-import { listAgents, listOrchestrators, listWorkspaces, resolveProjectForCwd, rootsForProject, ValidationError } from "../db";
+import { normalizeGitRemoteIdentity, stringValue, type AgentCard, type Orchestrator, type SpawnProvider, type WorkspaceMode, type ProjectRoot, type TaskDispatch } from "@humwick/sdk";
+import { getOrchestrator, listAgents, listOrchestrators, listWorkspaces, resolveProjectForCwd, rootsForProject, ValidationError } from "../db";
+import { listHostViews } from "../db/hosts-views";
 import { unboundOnHost, unboundProjectRoots } from "../db/project-lifecycle";
 import { isOrchestratorLocalToRelay, isPathWithinBase, sameHostIdentity } from "../utils";
 import { findGitRepoRoot } from "./canonical-root";
 import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
-import { selectSpawnPlacement, spawnPlacementCandidates, isRelayHost } from "../spawn-placement";
+import { selectSpawnPlacement, spawnPlacementCandidates, isRelayHost, type SpawnCapOptions } from "../spawn-placement";
 import { remoteUrlFromGitRemote } from "./git-remote";
 import { probeHostRepo, probeLocalSourceRepo } from "./spawn-repo-probe";
 import { hostProjectReadiness } from "./host-project-readiness";
 
+export function spawnBuildWork(profile: string, type?: TaskDispatch["type"]): boolean {
+  return type ? !["review", "research", "ops"].includes(type) : !["reviewer", "qa", "probe", "sec-ops"].includes(profile.toLowerCase());
+}
+
 /** Resolve host and working directory together so capacity routing keeps the caller's repo. */
 export async function selectSpawnCwdPlacement(input: {
   provider: SpawnProvider;
@@ -26,15 +31,16 @@ export async function selectSpawnCwdPlacement(input: {
   shared: boolean;
   workspaceMode?: WorkspaceMode;
   canLand?: boolean;
+  buildWork?: boolean;
   model?: string;
   effort?: string;
 }): Promise<{ orchestrator: Orchestrator; placementReason: string; resolvedCwd: string; lazyRoot?: ProjectRoot }> {
   const platformRule = input.workspaceMode === "isolated" && !input.shared && input.resumeWorkspace?.mode !== "attach"
     ? await sourcePlacementPlatforms(input) : undefined;
-  const capOpts = { ...(input.caller ? { callerAgentId: input.caller.id } : {}), attach: input.resumeWorkspace?.mode === "attach" };
+  const capOpts: SpawnCapOptions = { ...(input.caller ? { callerAgentId: input.caller.id } : {}), attach: input.resumeWorkspace?.mode === "attach", buildWork: input.buildWork };
   const earlyPlacement = !input.orchestratorId && input.resumeWorkspace?.mode !== "attach"
     ? spawnPlacementCandidates(input.provider, input.requestedCwd, input.allowedOrchestratorIds,
-      input.shared, input.model, input.effort, input.workspaceMode, platformRule, input.canLand, capOpts)
+      input.shared, input.model, input.effort, input.buildWork === false ? undefined : input.workspaceMode, platformRule, input.canLand, capOpts)
     : undefined;
   const survivors = earlyPlacement?.candidates.map((host) => host.id) ?? input.allowedOrchestratorIds;
   // Preserve selection's detailed exclusion error without probing hosts already ruled out.
@@ -43,6 +49,16 @@ export async function selectSpawnCwdPlacement(input: {
     input.model, input.effort, input.workspaceMode, platformRule, input.canLand, capOpts);
   const { attachWorkspace, hostCwds, allowedOrchestratorIds, lazyRoots, exclusions: checkoutExclusions = [] } = await omittedHostContext({ ...input, allowedOrchestratorIds: survivors });
   const requestedCwd = input.repoSource && !hostCwds ? input.repoSource : input.requestedCwd;
+  // Review/QA setup depends on the target checkout HEAD; a caller's policy base cannot vouch for it (#3805).
+  if (input.workspaceMode === "isolated" && input.buildWork === false && !input.resumeWorkspace) {
+    const views = new Map(listHostViews(Date.now()).map((view) => [view.id, view]));
+    const hosts = input.orchestratorId ? [getOrchestrator(input.orchestratorId)].filter((host): host is Orchestrator => !!host) : earlyPlacement?.candidates ?? [];
+    const lightHosts = await Promise.all(hosts.filter((host) => isRelayHost(host, host.hostId ? views.get(host.hostId) : undefined)).map(async (host) => {
+      const probe = await probeHostRepo(host, requestedCwd ?? hostCwds?.get(host.id) ?? input.callerCwd ?? host.baseDir, undefined, true);
+      return probe.kind === "present" && probe.workspaceDepsDisabled === true ? host.id : undefined;
+    }));
+    capOpts.workspaceDepsDisabledHosts = lightHosts.filter((id): id is string => id !== undefined);
+  }
   // #3169/#3625 — capacity ranks only hosts whose own checkout is ready for the project (refresh hook, toolchain).
   const readiness = hostProjectReadiness();
   const readinessExclusions: string[] = [];