@humwick/server 0.130.2 → 0.130.4

package/src/services/runtime-dependency-alert.ts

@@ -0,0 +1,27 @@
+import { createHash } from "node:crypto";
+import { isRecord } from "@humwick/sdk";
+import { createActivityEventByClientIdAsync } from "../db/activity-async";
+import { notifyWorkspaceHumanEscalation } from "../workspace-human-escalation";
+import { stewardFallbackTarget } from "../config";
+import { notifyTarget } from "../maintenance/events";
+
+/** Heartbeats already persist provider failures for Fleet; page once per broken checkout (#3791). */
+export async function reportRuntimeDependencyFailure(hostId: string, hostname: string, body: unknown): Promise<void> {
+  if (!isRecord(body) || !Array.isArray(body.providerStatus)) return;
+  const failure = body.providerStatus.find((status) => isRecord(status) && status.available === false
+    && typeof status.reason === "string" && status.reason.startsWith("Runtime dependencies unavailable in "));
+  if (!failure) return;
+  const reason = failure.reason as string;
+  const checkout = reason.split(": ")[0]!;
+  const key = `runtime-dependencies:${hostId}:${createHash("sha256").update(checkout).digest("hex")}`;
+  const subject = `Runtime dependencies broken on ${hostname}`;
+  const message = `${hostname}: ${reason}. Providers are unavailable until this checkout is repaired.`;
+  const event = await createActivityEventByClientIdAsync({ clientId: key, kind: "state", title: subject, body: message,
+    meta: hostId, icon: "ti-alert-triangle", view: "orchestrators", metadata: { hostId, reason } });
+  if (!event.created) return;
+  const payload = { hostId, reason, kind: "runtime-dependencies.failed" };
+  const human = await notifyWorkspaceHumanEscalation({ subject, body: message, priority: "urgent", source: "runtime-dependencies", payload, idempotencyKey: key });
+  const target = stewardFallbackTarget();
+  const routed = target ? await notifyTarget("maintenance.degraded", {}, target, subject, message, payload, key) : null;
+  console.warn(`[relay] ${subject}: ${reason}${human.accepted || routed ? "" : " — no notification target configured"}`);
+}

package/src/services/scheduler-command.ts

@@ -1,9 +1,11 @@
+import { updateCommandAsync } from "../commands-write";
 import { writeChildEnv } from "@humwick/sdk/env";
 import { basename } from "node:path";
 import { SCHEDULER_RETRY_MS } from "../config";
 import { errMessage, stringValue } from "@humwick/sdk";
 import { hasScope } from "@humwick/sdk/types";
-import { findLatestCommandByCorrelation, getCommand, updateCommand } from "../commands-db";
+import { getCommand } from "../commands-db";
+import { findLatestCommandByCorrelationAsync } from "../commands-write";
 import { RELAY_RUN_DEADLINE_GRACE_MS } from "../relay-run-lease";
 import { storeTextArtifact } from "../artifact-text";
 import { gateRunIdentity, recordAgentGateRun } from "../gate-run-capture";
@@ -119,7 +121,7 @@ export async function dispatchScheduledCommand(timer: ScheduledTimer, ctx = pers
   // Freeze the agent generation that owns this command. Managed restarts reuse the
   // durable agent id, so agentId alone would let predecessor teardown kill a successor's command.
   const executionOwnerSpawnRequestId = spawnRequestIds?.length === 1 ? spawnRequestIds[0] : undefined;
-  const command = findLatestCommandByCorrelation("scheduler.command", timer.correlationId) ?? await dispatchCommandAsync({
+  const command = await findLatestCommandByCorrelationAsync("scheduler.command", timer.correlationId) ?? await dispatchCommandAsync({
     type: "scheduler.command",
     source: timer.createdBy,
     target: `orchestrator-${timer.command.orchestratorId}`,
@@ -186,7 +188,7 @@ export async function fireScheduledCommandTimeout(timer: ScheduledTimer, now: nu
     return { status: "deferred" };
   }
   const neverStarted = !!command && (command.status === "pending" || command.status === "accepted") && commandResult(command).phase !== "running";
-  if (command) updateCommand(command.id, { status: "timed_out", error: "background command timed out" });
+  if (command) (await updateCommandAsync(command.id, { status: "timed_out", error: "background command timed out" }));
   const result = command ? commandResult(command) : {};
   const admittedAt = numberValue(result.admittedAt) ?? timer.command.admittedAt;
   const durationMs = admittedAt === undefined ? 0 : Math.max(0, now - admittedAt);
@@ -202,7 +204,7 @@ export async function fireScheduledCommandTimeout(timer: ScheduledTimer, now: nu
     stdoutTail: stringValue(result.stdoutTail) ?? timer.command.stdoutTail ?? "",
     stderrTail: stringValue(result.stderrTail) ?? timer.command.stderrTail ?? (neverStarted ? queuedTimeoutReason(timer.command.orchestratorId) : "background command timed out"),
   };
-  return fireScheduledCommandWake(timer, {
+  return (await fireScheduledCommandWake(timer, {
     status: "timed_out",
     finishedAt: timer.command.finishedAt ?? now,
     durationMs,
@@ -213,7 +215,7 @@ export async function fireScheduledCommandTimeout(timer: ScheduledTimer, now: nu
     exitCode: null,
     stdoutTail: timeoutResult.stdoutTail,
     stderrTail: timeoutResult.stderrTail,
-  }, timeoutResult, now, inlineWakeSuppressed(timer.command, now));
+  }, timeoutResult, now, inlineWakeSuppressed(timer.command, now)));
 }
 
 /** #2776 — admission report: the fallback timer now guards the RUN (end + grace), not the queue ceiling. */
@@ -243,7 +245,7 @@ export async function settleScheduledCommandTimer(command: Command, now = Date.n
       : "failed";
   const stdout = clipTail(stringValue(result.stdoutTail) ?? stringValue(result.stdout) ?? "");
   const stderr = clipTail(stringValue(result.stderrTail) ?? stringValue(result.stderr) ?? command.error ?? "");
-  return fireScheduledCommandWake(timer, {
+  return (await fireScheduledCommandWake(timer, {
     status,
     finishedAt: timer.command.finishedAt ?? now,
     startedAt: numberValue(result.startedAt),
@@ -262,7 +264,7 @@ export async function settleScheduledCommandTimer(command: Command, now = Date.n
     // Strictly stronger than truncation: the command was KILLED for flooding, it did not finish.
     outputLimitExceeded: result.outputLimitExceeded === true,
     logArtifactId: stringValue(result.logArtifactId),
-  }, result, now, inlineWakeSuppressed(timer.command, now));
+  }, result, now, inlineWakeSuppressed(timer.command, now)));
 }
 
 /**
@@ -358,7 +360,7 @@ async function fireScheduledCommandWake(
   try {
     const runNumber = timerForSend.runCount + 1;
     const payloadResult = commandPayload(timerForSend.command!, rawResult, logArtifactId);
-    const send = sendMessageService({
+    const send = (await sendMessageService({
       from: timerForSend.deliveryFrom,
       to: timerForSend.target,
       kind: timerForSend.messageKind as SendMessageInput["kind"] | undefined,
@@ -387,7 +389,7 @@ async function fireScheduledCommandWake(
       },
       // One stable key per command completion (not per run count): overlapping settlements dedupe.
       idempotencyKey: `${timerForSend.idempotencyKey ?? `scheduler:${timerForSend.id}`}:completion`,
-    }, persistedCommandAuthContext(timerForSend));
+    }, persistedCommandAuthContext(timerForSend)));
     await completeTimerRunAsync(timerForSend, send.message.id, now);
     return { status: "fired", messageId: send.message.id };
   } catch (error) {

package/src/services/scheduler.ts

@@ -1,3 +1,4 @@
+import { framed } from "../hub-metrics";
 import { createScheduledTimer } from "./scheduler-create";
 import { planScheduledTimerCreate, cleanOptionalString, canAdministerTimers, type ScheduleTimerInput } from "./scheduler-plan";
 export { type ScheduleTimerInput } from "./scheduler-plan";
@@ -84,9 +85,8 @@ export function startRelayScheduler(): void {
   if (isEphemeralMode()) return;
   if (schedulerTimer) return;
   void timePostBindPhase("runDueScheduledTimers", runDueScheduledTimers).catch((error) => console.warn(`relay scheduler tick failed: ${errMessage(error)}`));
-  schedulerTimer = setInterval(() => {
-    void timePostBindPhase("runDueScheduledTimers", runDueScheduledTimers).catch((error) => console.warn(`relay scheduler tick failed: ${errMessage(error)}`));
-  }, SCHEDULER_TICK_MS);
+  schedulerTimer = setInterval(framed("timer scheduled-timers", () =>
+    timePostBindPhase("runDueScheduledTimers", runDueScheduledTimers).catch((error) => console.warn(`relay scheduler tick failed: ${errMessage(error)}`))), SCHEDULER_TICK_MS);
   // #1408 K7 Phase-2: additively light up the kernel-served timers supervisor iff the reversible
   // switch is on (default OFF ⇒ pure no-op). Legacy above stays authoritative; the kernel path is
   // not yet a functional replacement for message/command dispatch (see kernel-timers.ts).
@@ -292,7 +292,7 @@ async function fireClaimedTimer(
       await disableTimerAsync(timer.id, "timer expired before delivery");
       return { status: "disabled" };
     }
-    return fireScheduledCommandTimeout(timer, now);
+    return (await fireScheduledCommandTimeout(timer, now));
   }
 
   try {
@@ -323,7 +323,7 @@ async function fireClaimedTimer(
       await disableTimerAsync(timer.id, "timer expired before delivery");
       return { status: "disabled" };
     }
-    const result = sendMessageService(sendInput, persistedAuthContext(timer));
+    const result = (await sendMessageService(sendInput, persistedAuthContext(timer)));
     await completeTimerRunAsync(timer, result.message.id, now);
     return { status: "fired", messageId: result.message.id };
   } catch (error) {

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/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,21 +29,6 @@ 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";
@@ -367,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.
@@ -391,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(
@@ -426,7 +409,7 @@ export async function sendMessagesBatchService(
       receipt: finalizeReceipt(result.message, prepared[outputIndex]!.receipt),
     };
   }
-  emitSendResults(stored);
+  (await emitSendResults(stored));
   return results;
 }
 
@@ -504,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);
@@ -517,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) {
@@ -538,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";
@@ -54,7 +54,7 @@ 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";
@@ -152,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,
@@ -390,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) });
@@ -429,7 +400,7 @@ 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);
@@ -486,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,
@@ -544,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
@@ -599,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;
 
@@ -885,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)}`);
     }

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

@@ -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;

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[] = [];