@humwick/server 0.130.1 → 0.130.2

package/src/maintenance/jobs.ts

@@ -498,8 +498,9 @@ export const definitions: MaintenanceJobDefinition[] = [
       // event loop was stalled, a live replacement's heartbeats may still be unprocessed, so the
       // grace widens by the observed lag instead of misreading the backlog as post-mortem silence.
       // #1895 (S3.2 L10, review finding 3) — routed through the async gateway facade.
-      const revokedOrphanTokens = await revokeOrphanedRuntimeTokensAsync(STALE_TTL_MS, eventLoopLagGraceMs());
-      return { revokedOrphanTokens };
+      // #3776 — paged short writes, bounded by the abort signal and a time budget.
+      const { revoked, complete } = await revokeOrphanedRuntimeTokensAsync(STALE_TTL_MS, eventLoopLagGraceMs(), { signal: context.signal });
+      return { revokedOrphanTokens: revoked, moreWork: !complete };
     },
   },
   {

package/src/maintenance/scheduler.ts

@@ -2,8 +2,11 @@ import { timePostBindPhase } from "../post-bind-startup";
 import { randomUUID } from "node:crypto";
 import { errMessage, isRecord } from "@humwick/sdk";
 import { classifyPidLiveness } from "@humwick/sdk/process-utils";
-import { CRITICAL_MAINTENANCE_PROGRESS_STALE_MS, createActivityEventAsync, getDb, isSqliteBusyError, MAINTENANCE_RUN_AUTORESET_GUARD_SQL, recordDrainConvoy, writeTransaction } from "../db";
+import { CRITICAL_MAINTENANCE_PROGRESS_STALE_MS, createActivityEventAsync, getDb, MAINTENANCE_RUN_AUTORESET_GUARD_SQL, recordDrainConvoy, writeTransaction } from "../db";
 import { claimMaintenanceRunAsync, finishMaintenanceRunAsync, heartbeatMaintenanceRunAsync } from "../db/maintenance-job-runs-async";
+import { ensureMaintenanceJobsAsync, reclaimDeadLeasesAsync, rescheduleRunOnStartJobsAsync } from "../db/maintenance-job-runs-async";
+import { reclaimDeadLeases, rescheduleRunOnStartJobs, upsertMaintenanceJobs } from "../db/maintenance-job-reconcile";
+import type { DeadLease, MaintenanceJobSpec } from "../db/maintenance-job-reconcile";
 import type { MaintenanceRunOutcome } from "../db/maintenance-job-runs";
 import { withAbortDeadline } from "../async-deadline";
 import { MAINTENANCE_BREAKER_LAG_MS } from "../config";
@@ -173,36 +176,13 @@ export function resetOrphanTrackerForTests(): void {
 }
 
 export function startMaintenanceScheduler(): void {
-  // Reconcile the job table once at boot. A transient SQLITE_BUSY here must not
-  // abort startup — the first scheduler tick re-runs the reconcile with retry.
-  try {
-    ensureMaintenanceJobs();
-    scheduleRunOnStartJobs();
-  } catch (error) {
-    console.warn(`maintenance job reconcile at startup failed (will retry on next tick): ${errMessage(error)}`);
-    void ensureMaintenanceJobsResilient()
-      .then(() => {
-        scheduleRunOnStartJobs();
-        return runDueMaintenanceJobs();
-      })
-      .catch((retryError) => console.warn(`maintenance startup retry failed (will retry on next tick): ${errMessage(retryError)}`));
-  }
-  // #1493 — a relay restart orphans the maintenance-job lease its own dying
-  // process held moments earlier: lease_owner still names the dead PID and
-  // lease_until is still in the future, so the claim guard in runJob/
-  // runDueMaintenanceJobs (lease_until IS NULL OR lease_until <= now) blocks
-  // the job — e.g. the CD watcher — until the lease's TTL self-expires (up to
-  // deadlineMs + 5s). Reclaim any lease whose owner PID is no longer alive so
-  // maintenance resumes immediately after a restart instead of stalling.
-  try {
-    reclaimDeadPidLeases();
-  } catch (error) {
-    console.warn(`dead-PID maintenance lease reclaim at startup failed (will retry on next tick): ${errMessage(error)}`);
-  }
+  // #1870 S7: the boot reconcile, run-on-start reschedule and dead-lease reclaim are writer ops. The first
+  // tick waits for them, so a due run-on-start job is never claimed before its reschedule lands.
+  void bootMaintenanceJobs().then(() => runDueMaintenanceJobs())
+    .catch((error) => console.warn(`maintenance tick failed: ${errMessage(error)}`));
   // Floated ticks are wrapped defensively: runDueMaintenanceJobs already catches
   // its own errors (#1481), but a stray rejection from a floated promise must
   // never bubble to an unhandledRejection that exits the relay process.
-  void runDueMaintenanceJobs().catch((error) => console.warn(`maintenance tick failed: ${errMessage(error)}`));
   if (timer) return;
   timer = setInterval(
     () => void runDueMaintenanceJobs().catch((error) => console.warn(`maintenance tick failed: ${errMessage(error)}`)),
@@ -210,6 +190,29 @@ export function startMaintenanceScheduler(): void {
   );
 }
 
+async function bootMaintenanceJobs(): Promise<void> {
+  // A transient SQLITE_BUSY here must not abort startup: every scheduler tick runs the reconcile again.
+  try {
+    await ensureMaintenanceJobsAsync(jobSpecs());
+  } catch (error) {
+    console.warn(`maintenance job reconcile at startup failed (will retry on next tick): ${errMessage(error)}`);
+  }
+  try {
+    await rescheduleRunOnStartJobsAsync();
+  } catch (error) {
+    // The next tick retries it, so run-on-start jobs do not wait a full interval (#1870 S7).
+    runOnStartPending = true;
+    console.warn(`maintenance run-on-start reschedule failed (will retry on next tick): ${errMessage(error)}`);
+  }
+  // #1493 — a restart orphans the lease its dying process held: lease_owner still names the dead PID and
+  // lease_until is still in the future, which blocks the job (e.g. the CD watcher) until the TTL expires.
+  try {
+    await reclaimDeadLeasesAsync(findDeadLeases());
+  } catch (error) {
+    console.warn(`dead-PID maintenance lease reclaim at startup failed (will retry on next tick): ${errMessage(error)}`);
+  }
+}
+
 /**
  * `runOnStart` means every Relay process start, not only the first insertion of
  * a durable maintenance_jobs row. Historically ensureMaintenanceJobs used
@@ -219,29 +222,37 @@ export function startMaintenanceScheduler(): void {
  * scheduler tick.
  */
 export function scheduleRunOnStartJobs(now: number = Date.now()): void {
-  getDb().query(`
-    UPDATE maintenance_jobs
-    SET next_run_at = ?, updated_at = ?
-    WHERE enabled = 1 AND run_on_start = 1
-  `).run(now, now);
+  rescheduleRunOnStartJobs(now);
 }
 
+function readMaintenanceJobs(): MaintenanceJob[] {
+  const rows = getDb().query("SELECT * FROM maintenance_jobs ORDER BY title COLLATE NOCASE ASC").all() as MaintenanceJobRow[];
+  const now = Date.now();
+  const currentIds = new Set(definitions.map((definition) => definition.id));
+  return rows.filter((row) => currentIds.has(row.id)).map((row) => rowToJob(row, now));
+}
+
+// A transient lock while reconciling must not fail a listing; return the current rows (a later reconcile catches up). #1481.
 export function listMaintenanceJobs(): MaintenanceJob[] {
   try {
     ensureMaintenanceJobs();
   } catch (error) {
-    // A transient lock while reconciling must not fail a read-only listing; fall
-    // through and return the current rows (a later reconcile catches up). #1481.
     console.warn(`maintenance job reconcile during list failed: ${errMessage(error)}`);
   }
-  const rows = getDb().query("SELECT * FROM maintenance_jobs ORDER BY title COLLATE NOCASE ASC").all() as MaintenanceJobRow[];
-  const now = Date.now();
-  const currentIds = new Set(definitions.map((definition) => definition.id));
-  return rows.filter((row) => currentIds.has(row.id)).map((row) => rowToJob(row, now));
+  return readMaintenanceJobs();
+}
+
+export async function listMaintenanceJobsAsync(): Promise<MaintenanceJob[]> {
+  try {
+    await ensureMaintenanceJobsAsync(jobSpecs());
+  } catch (error) {
+    console.warn(`maintenance job reconcile during list failed: ${errMessage(error)}`);
+  }
+  return readMaintenanceJobs();
 }
 
 export async function runMaintenanceJobNow(id: string, options: { overridePause?: boolean } = {}): Promise<MaintenanceJobRun> {
-  await ensureMaintenanceJobsResilient();
+  await ensureMaintenanceJobsAsync(jobSpecs());
   const definition = definitions.find((job) => job.id === id);
   if (!definition) throw new Error("maintenance job not found");
   return runJob(definition, { force: true, overridePause: options.overridePause });
@@ -266,6 +277,7 @@ async function runMaintenanceJobsNow(ids: string[]): Promise<MaintenanceJobRun[]
 // no-op (the still-open tick, or the one after, picks up whatever came due). Combined with the
 // serialized drain below, this is the "one job at a time from a queue" the design (§5.4) calls for.
 let tickInFlight = false;
+let runOnStartPending = false;
 
 export async function runDueMaintenanceJobs(): Promise<void> {
   if (tickInFlight) return;
@@ -274,7 +286,11 @@ export async function runDueMaintenanceJobs(): Promise<void> {
   // is guarded: a transient SQLITE_BUSY (or any other failure) reconciling or
   // querying the job table is logged and the tick is skipped — the next tick retries.
   try {
-    await ensureMaintenanceJobsResilient();
+    await ensureMaintenanceJobsAsync(jobSpecs());
+    if (runOnStartPending) {
+      await rescheduleRunOnStartJobsAsync();
+      runOnStartPending = false;
+    }
     const now = Date.now();
     const progressStaleAt = now - CRITICAL_MAINTENANCE_PROGRESS_STALE_MS;
     const rows = getDb().query(`
@@ -363,84 +379,28 @@ export function drainDueMaintenanceJobsForTests(dueDefinitions: MaintenanceJobDe
  *  otherwise leave it latched, wedging every later test's tick). Production never calls this. */
 export function resetSchedulerTickGuardForTests(): void {
   tickInFlight = false;
+  runOnStartPending = false;
 }
 
-// Bounded, ASYNC, loop-yielding retry around the (synchronous) job-table reconcile.
-// Mirrors runWriteWithBusyRetry (connection.ts) but wraps ensureMaintenanceJobs,
-// which runs its own BEGIN IMMEDIATE transaction and so cannot be nested inside
-// runWriteWithBusyRetry. busy_timeout already makes SQLite WAIT on a held lock; the
-// rare BUSY that survives it is retried here with jittered backoff that yields the
-// event loop between attempts. Anything else — or exhausted attempts — rethrows to
-// the caller, which degrades the tick rather than crashing the process (#1481).
-const ENSURE_BUSY_RETRY_ATTEMPTS = 4;
-const ENSURE_BUSY_RETRY_BASE_MS = 15;
-const ENSURE_BUSY_RETRY_MAX_MS = 120;
-
-async function ensureMaintenanceJobsResilient(): Promise<void> {
-  for (let attempt = 1; ; attempt++) {
-    try {
-      ensureMaintenanceJobs();
-      return;
-    } catch (error) {
-      if (attempt < ENSURE_BUSY_RETRY_ATTEMPTS && isSqliteBusyError(error)) {
-        const cap = Math.min(ENSURE_BUSY_RETRY_MAX_MS, ENSURE_BUSY_RETRY_BASE_MS * 2 ** (attempt - 1));
-        const delay = cap / 2 + Math.random() * (cap / 2);
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        continue;
-      }
-      throw error;
-    }
-  }
+function jobSpecs(): MaintenanceJobSpec[] {
+  return definitions.map((definition) => ({
+    id: definition.id,
+    title: definition.title,
+    description: definition.description,
+    intervalMs: definition.intervalMs,
+    deadlineMs: definition.deadlineMs ?? DEFAULT_DEADLINE_MS,
+    enabled: !isEphemeralMode() || definition.instanceSafe === true,
+    critical: definition.critical === true,
+    runOnStart: definition.runOnStart === true,
+  }));
 }
 
+// Boot/test twin of `ensureMaintenanceJobsAsync`: one BEGIN IMMEDIATE so busy_timeout governs a single lock
+// acquisition (#1481). The listing read path and tests use it; the running scheduler uses the writer op.
 function ensureMaintenanceJobs(): void {
-  const db = getDb();
+  const specs = jobSpecs();
   const now = Date.now();
-  // #1645 — `enabled` is re-asserted from `definitions` on every reconcile, which is what makes it
-  // CODE-owned and therefore self-healing. Before this it was set only on INSERT and deliberately
-  // omitted from the conflict clause, because the one column doubled as the operator's "stop" lever
-  // and a redeploy would have clobbered their intent. Operator intent now lives in
-  // `maintenance_job_pauses` (holder, reason, expiry), so re-asserting `enabled` overrides nobody —
-  // and a hand-written `UPDATE maintenance_jobs SET enabled=0` recovers at the next boot instead of
-  // persisting until someone writes more raw SQL (nine hours of deploy blackout, #1645).
-  //
-  // PRECONDITION: convertManualJobDisablesToPauses() (src/db/migrations.ts) must have run first, or
-  // this silently switches back on a job an operator deliberately stopped.
-  const stmt = db.query(`
-    INSERT INTO maintenance_jobs (id, title, description, interval_ms, timeout_ms, enabled, critical, run_on_start, next_run_at, updated_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(id) DO UPDATE SET
-      title = excluded.title,
-      description = excluded.description,
-      interval_ms = excluded.interval_ms,
-      timeout_ms = excluded.timeout_ms,
-      run_on_start = excluded.run_on_start,
-      enabled = excluded.enabled, -- #1645: code-owned, see the note above this query
-      critical = excluded.critical,
-      next_run_at = COALESCE(maintenance_jobs.next_run_at, excluded.next_run_at),
-      updated_at = excluded.updated_at
-  `);
-  // Batch the upserts into a single BEGIN IMMEDIATE write so busy_timeout governs
-  // ONE lock acquisition (SQLite waits) instead of one per definition, cutting the
-  // lock churn that made this loop the crash site under contention (#1481).
-  writeTransaction(() => {
-    for (const definition of definitions) {
-      stmt.run(
-        definition.id,
-        definition.title,
-        definition.description,
-        definition.intervalMs,
-        // #1728: the DB column stays `timeout_ms` — renaming it is a migration, not asked for here.
-        // Code-side this is `deadlineMs`: see MaintenanceJobDefinition for why.
-        definition.deadlineMs ?? DEFAULT_DEADLINE_MS,
-        !isEphemeralMode() || definition.instanceSafe === true ? 1 : 0,
-        definition.critical ? 1 : 0,
-        definition.runOnStart ? 1 : 0,
-        definition.runOnStart ? now : now + definition.intervalMs,
-        now,
-      );
-    }
-  });
+  writeTransaction(() => upsertMaintenanceJobs(specs, now));
 }
 
 // #1493 — reclaim current-schema maintenance_jobs leases whose owner PID is proven dead.
@@ -455,23 +415,19 @@ function ensureMaintenanceJobs(): void {
 // #3645: the crash is not a job failure — it neither bumps consecutive_failures nor replaces an existing
 // last_error (a non-null one belongs to the live failure streak; success clears it). The page-only guard remains on every
 // deadline-based reclaim/claim path, where that positive evidence is unavailable.
-export function reclaimDeadPidLeases(): void {
-  const db = getDb();
-  const now = Date.now();
-  const leased = db.query(`
-    SELECT id, lease_owner FROM maintenance_jobs
-    WHERE lease_owner IS NOT NULL
-  `).all() as Array<{ id: string; lease_owner: string }>;
+function findDeadLeases(): DeadLease[] {
+  const leased = getDb().query("SELECT id, lease_owner FROM maintenance_jobs WHERE lease_owner IS NOT NULL").all() as Array<{ id: string; lease_owner: string }>;
+  const dead: DeadLease[] = [];
   for (const row of leased) {
     const pid = parseLeaseOwnerPid(row.lease_owner);
-    if (pid === null || classifyPidLiveness(pid) !== "dead") continue;
-    db.query(`
-      UPDATE maintenance_jobs
-      SET lease_owner = NULL, lease_until = NULL, last_status = 'failed',
-          last_error = COALESCE(last_error, ?), run_token = NULL, last_progress_at = ?, updated_at = ?
-      WHERE id = ? AND lease_owner = ?
-    `).run(`reclaimed stale lease at startup: owner pid ${pid} is confirmed dead`, now, now, row.id, row.lease_owner);
+    if (pid !== null && classifyPidLiveness(pid) === "dead") dead.push({ id: row.id, owner: row.lease_owner, pid });
   }
+  return dead;
+}
+
+export function reclaimDeadPidLeases(): void {
+  const dead = findDeadLeases();
+  if (dead.length) writeTransaction(() => reclaimDeadLeases(dead, Date.now()));
 }
 
 function parseLeaseOwnerPid(owner: string): number | null {
@@ -527,7 +483,7 @@ async function runJob(definition: MaintenanceJobDefinition, options: { force?: b
   const progressStaleAt = startedAt - CRITICAL_MAINTENANCE_PROGRESS_STALE_MS;
   const claimed = await claimMaintenanceRunAsync({ id: definition.id, owner, runToken, startedAt, leaseUntil, progressStaleAt, force: options.force === true });
   if (!claimed) {
-    const state = listMaintenanceJobs().find((job) => job.id === definition.id);
+    const state = readMaintenanceJobs().find((job) => job.id === definition.id);
     return { id: definition.id, status: "skipped", startedAt, finishedAt: Date.now(), durationMs: 0, result: { reason: "not due or already running", state } };
   }
 

package/src/maintenance/stalled-delivery-pager.ts

@@ -1,5 +1,6 @@
 import { errMessage } from "@humwick/sdk";
-import { getConfig, setConfig } from "../config-store";
+import { getConfig } from "../config-store";
+import { setConfigAsync } from "../config-store-write";
 import { getStalledDeliverySignalAsync } from "../db/stats-async.ts";
 import { notifyWorkspaceHumanEscalation } from "../workspace-human-escalation";
 import type { MaintenanceJobDefinition } from "./types";
@@ -56,8 +57,8 @@ export async function runStalledDeliveryPager(now: number = Date.now()): Promise
   }
   let alerted = false;
   let recovered = false;
-  const persist = () => {
-    if (JSON.stringify(state) !== JSON.stringify(prior)) setConfig(STATE_NAMESPACE, STATE_KEY, state, "stalled-delivery-pager");
+  const persist = async () => {
+    if (JSON.stringify(state) !== JSON.stringify(prior)) await setConfigAsync(STATE_NAMESPACE, STATE_KEY, state, "stalled-delivery-pager");
   };
 
   const { check } = signal;
@@ -87,7 +88,7 @@ export async function runStalledDeliveryPager(now: number = Date.now()): Promise
     if (!state.stalled && state.failStreak >= STALL_PAGE_CONFIRM_CHECKS) state = { ...state, stalled: true, since: now, alerted: false };
     if (state.stalled && !state.alerted) {
       // Persist the episode first so a crash after the send re-sends under the same key.
-      persist();
+      await persist();
       const result = notifyWorkspaceHumanEscalation({
         subject: "Message delivery stalled",
         body: [
@@ -107,7 +108,7 @@ export async function runStalledDeliveryPager(now: number = Date.now()): Promise
       state = { ...state, alerted: true };
     }
   }
-  persist();
+  await persist();
   return { state: state.stalled ? "stalled" : "ok", alerted, recovered };
 }
 

package/src/maintenance/workspaces.ts

@@ -487,7 +487,7 @@ export async function workspaceGC(context: { signal?: AbortSignal } = {}): Promi
       const proof = landedElsewhere === "confirmed" ? "ancestor" : landedElsewhere;
       await reconcileLandedWorkspace(fresh, zeroCommitCloseOut
         ? { strategy: preview && !("available" in preview) ? preview.strategy : "rebase-ff", baseRef, ahead: 0, unmergedAhead: 0, dirtyCount: 0 }
-        : { strategy: preview && !("available" in preview) ? preview.strategy : "rebase-ff", baseRef, headSha: currentTip, landed: true, landedSha: currentTip });
+        : { strategy: preview && !("available" in preview) ? preview.strategy : "rebase-ff", baseRef, headSha: currentTip, landed: true, landedSha: currentTip }, landedElsewhere === "confirmed" ? currentTip : undefined);
       await patchWorkspaceMetadataAsync(fresh.id, {
         landedElsewhere: true,
         landedElsewhereAt: now,

package/src/managed-policy.ts

@@ -7,14 +7,13 @@ import { getAgent } from "./db/agents";
 import { getOrchestratorAsync } from "./db/orchestrators-async";
 import { composeProfileSpawnInstructions, composeProfileSpawnInstructionsAsync } from "./project-instructions";
 import { getSelfEffortCeiling } from "./db/self-effort-permissions";
-import { runnerRuntimeTokenEnv, type RunnerLaunchAuthority } from "./runtime-tokens";
-import { gatewayBackend } from "./db/gateway";
+import { runnerRuntimeTokenEnv, runnerRuntimeTokenEnvAsync, type RunnerLaunchAuthority, type RunnerRuntimeTokenInput } from "./runtime-tokens";
 import { recordedLaunchMode, resolveHostLaunchMode } from "./launch-mode";
 import { buildSpawnCommand, generateSpawnAgentId, resolveSpawnModelParams, resolveSpawnModelParamsAsync } from "./spawn-command";
 import { applyDefaultSharedMcp } from "./shared-mcp";
 import { AGENT_SYSTEM_TAGS, systemTagsForSpawn } from "./agent-system-tags";
 import { buildWhoamiDefaultForAgent } from "./mcp/identity-projection";
-import { isStewardPolicy, isGenuineStewardPolicy, stewardWorktreeCwdPrefixes } from "./steward-spawn-guard";
+import { isGenuineStewardPolicy, stewardWorktreeCwdPrefixes } from "./steward-spawn-guard";
 // #2033 — from isolated-workspace-placement.ts, NOT ./services/spawn-identity: that module also
 // exports buildProspectiveSpawnIdentity, which imports mcp/identity.ts → self-resume.ts →
 // restart-spawn.ts → managed-policy.ts, and importing it here would close that into a cycle.
@@ -97,7 +96,8 @@ export function buildManagedSpawnParams(policy: SpawnPolicy, requestId: string,
   const composed = composeProfileSpawnInstructions(managedInstructionInput(policy, agentProfile, agentRelayIdentity, orchestratorHost, alwaysOnAppend));
 
   return buildManagedCommand({ policy, requestId, ctx, agentId, prompt, agentProfile, orchestrator, extraCwdPrefixes, composed,
-    modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort, { skipDefaultWhenEmpty: !isStewardPolicy(policy) }),
+    modelParams: resolveSpawnModelParams(policy.provider, policy.model, policy.effort),
+    env: runnerRuntimeTokenEnv(managedTokenInput(policy, requestId, ctx, agentId, extraCwdPrefixes)),
   });
 }
 
@@ -147,6 +147,7 @@ function buildManagedCommand(input: {
   extraCwdPrefixes: string[];
   composed: ReturnType<typeof composeProfileSpawnInstructions>;
   modelParams: ReturnType<typeof resolveSpawnModelParams>;
+  env: Record<string, string>;
 }): Record<string, unknown> {
   const { policy, requestId, ctx, agentId, prompt, agentProfile, orchestrator, extraCwdPrefixes, composed, modelParams } = input;
   return buildSpawnCommand({
@@ -177,26 +178,31 @@ function buildManagedCommand(input: {
     headless: true,
     policyName: policy.name,
     spawnRequestId: requestId,
-    env: runnerRuntimeTokenEnv({
-      agentId,
-      orchestratorId: policy.orchestratorId,
-      cwd: policy.cwd,
-      provider: policy.provider,
-      label: policy.label,
-      policyName: policy.name,
-      spawnRequestId: requestId,
-      createdBy: ctx.createdBy,
-      authority: ctx.authority,
-      profile: policy.profile || undefined,
-      // #2245 — the same posture this launch is given above; stamped into the signed constraints.
-      approvalMode: policy.permissionMode,
-      ...(extraCwdPrefixes.length ? { extraCwdPrefixes } : {}),
-    }),
+    env: input.env,
     requestedBy: ctx.createdBy,
     requestedAt: ctx.requestedAt ?? Date.now(),
   });
 }
 
+/** The runner token a managed launch carries; the sync builder and the writer-op builder mint the same input. */
+function managedTokenInput(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext, agentId: string, extraCwdPrefixes: string[]): RunnerRuntimeTokenInput {
+  return {
+    agentId,
+    orchestratorId: policy.orchestratorId,
+    cwd: policy.cwd,
+    provider: policy.provider,
+    label: policy.label,
+    policyName: policy.name,
+    spawnRequestId: requestId,
+    createdBy: ctx.createdBy,
+    authority: ctx.authority,
+    profile: policy.profile || undefined,
+    // #2245 — the same posture this launch is given above; stamped into the signed constraints.
+    approvalMode: policy.permissionMode,
+    ...(extraCwdPrefixes.length ? { extraCwdPrefixes } : {}),
+  };
+}
+
 // #2656 — backstop for every managed launch path (policy start/restart routes, agent restart): no
 // new process starts on a disabled provider. The lifecycle manager parks the policy before this.
 function assertManagedProviderEnabled(message: string | undefined): void {
@@ -205,15 +211,12 @@ function assertManagedProviderEnabled(message: string | undefined): void {
 
 /** Worker-safe counterpart used by every runtime managed launch path.  The synchronous builder
  * remains for in-process unit fixtures; production must never borrow its main-thread connection. */
-export function buildManagedSpawnParamsAsync(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Record<string, unknown> | Promise<Record<string, unknown>> {
+export async function buildManagedSpawnParamsAsync(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Promise<Record<string, unknown>> {
   if (effectiveManagedPolicyWorkspaceMode(policy) === "isolated" && ctx.gitRepoRoot === undefined) {
-    return getOrchestratorAsync(policy.orchestratorId).then(async (host) => buildManagedSpawnParamsAsync(policy, requestId, {
-      ...ctx, gitRepoRoot: host ? await resolveSpawnRepoRoot(host, policy.cwd) : null,
-    }));
+    const host = await getOrchestratorAsync(policy.orchestratorId);
+    ctx = { ...ctx, gitRepoRoot: host ? await resolveSpawnRepoRoot(host, policy.cwd) : null };
   }
-  // Preserve immediate in-process command construction for durable policy wake callers. The worker
-  // backend never enters this synchronous branch, so it cannot reopen the closed-main DB path.
-  return gatewayBackend() === "in-process" ? buildManagedSpawnParams(policy, requestId, ctx) : buildManagedSpawnParamsWorkerAsync(policy, requestId, ctx);
+  return buildManagedSpawnParamsWorkerAsync(policy, requestId, ctx);
 }
 
 async function buildManagedSpawnParamsWorkerAsync(policy: SpawnPolicy, requestId: string, ctx: ManagedSpawnContext): Promise<Record<string, unknown>> {
@@ -231,6 +234,7 @@ async function buildManagedSpawnParamsWorkerAsync(policy: SpawnPolicy, requestId
   const extraCwdPrefixes = managedCwdPrefixes(policy, requestId, ctx, orchestrator);
   const composed = await composeProfileSpawnInstructionsAsync(managedInstructionInput(policy, agentProfile, agentRelayIdentity, orchestratorHost, alwaysOnAppend));
   return buildManagedCommand({ policy, requestId, ctx, agentId, prompt, agentProfile, orchestrator, extraCwdPrefixes, composed,
-    modelParams: await resolveSpawnModelParamsAsync(policy.provider, policy.model, policy.effort, { skipDefaultWhenEmpty: !isStewardPolicy(policy) }),
+    modelParams: await resolveSpawnModelParamsAsync(policy.provider, policy.model, policy.effort),
+    env: await runnerRuntimeTokenEnvAsync(managedTokenInput(policy, requestId, ctx, agentId, extraCwdPrefixes)),
   });
 }

package/src/mcp/index.ts

@@ -1,5 +1,6 @@
 import { normalizeOutputArgs, outputToolDefinition, presentToolOutput } from "./output-levels";
 import { PROMPT_TOOLS, relayPrompt } from "./prompts";
+import { PROJECT_PROFILE_INSTRUCTION_TOOLS, relayProjectProfileInstructions } from "./project-profile-instructions";
 import { PromptVersionConflictError } from "../prompt-version-errors";
 import { memoryRetirementMessage } from "../memory-retirement";
 import { GUIDE_TOOLS, relayGuide } from "./guides";
@@ -60,6 +61,7 @@ const MCP_PROTOCOL_VERSION = "2024-11-05";
 const MCP_BODY_OVERHEAD_BYTES = ARTIFACT_BODY_OVERHEAD_BYTES;
 const TOOLS: ToolDefinition[] = [
   ...PROMPT_TOOLS,
+  ...PROJECT_PROFILE_INSTRUCTION_TOOLS,
   ...WEB_TOOL_CALL_TOOLS,
   ...MESSAGING_TOOLS,
   ...ARTIFACT_TOOLS,
@@ -215,6 +217,7 @@ async function callTool(auth: VerifiedMcpAuthContext, params: unknown, signal?:
     else if (name === "relay_hosts") result = await relayHosts(auth, args);
     else if (name === "relay_host_gate_budget") result = await relayHostGateBudget(auth, args);
     else if (name === "relay_prompt") result = await relayPrompt(auth, args);
+    else if (name === "relay_project_profile_instructions") result = await relayProjectProfileInstructions(auth, args);
     else if (name === "relay_service_access") result = await relayServiceAccess(auth, args);
     else if (name.startsWith("relay_secret_")) result = await relaySecretTool(auth, name, args);
     else if (name === "relay_my_agents") result = await relayMyAgents(auth, args);
@@ -223,7 +226,7 @@ async function callTool(auth: VerifiedMcpAuthContext, params: unknown, signal?:
     else if (name === "relay_agent_keep") result = await relayAgentKeep(auth, args);
     else if (name === "relay_codex_reset_consume") result = await relayCodexResetConsume(args);
     else if (name === "relay_claude_api_budget") result = await relayClaudeApiBudget(args);
-    else if (name === "relay_profile_trust") result = relayProfileTrust(auth, args);
+    else if (name === "relay_profile_trust") result = await relayProfileTrust(auth, args);
     else if (name.startsWith("relay_routing_policy_")) result = await relayRoutingPolicyTool(auth, name, args);
     else if (name === "relay_agent_action") result = await relayAgentAction(auth, args);
     else if (name === "relay_set_effort") result = await relaySetEffort(auth, args);
@@ -253,7 +256,7 @@ async function callTool(auth: VerifiedMcpAuthContext, params: unknown, signal?:
     // #2591 — the journal tools must claim their prefix BEFORE the generic relay_project_
     // dispatcher, or they would fall through to relayProjectTool as "unknown tool".
     else if (name.startsWith("relay_project_journal_")) result = relayProjectJournalTool(auth, name, args);
-    else if (name === "relay_project_ingest_claudemd") result = await relayProjectIngestClaudeMd(auth, args); else if (name.startsWith("relay_project_")) result = await relayProjectTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = await relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
+    else if (name === "relay_project_ingest_claudemd") result = await relayProjectIngestClaudeMd(auth, args); else if (name.startsWith("relay_project_")) result = await relayProjectTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = await relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = await relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
     else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions" || name === "relay_why_notified" || name === "relay_notification_preview") result = await relayNotificationSubscriptionTool(auth, name, args);
     else if (name === "relay_notify_ntfy") result = relayNotifyNtfy(args);
     else if (name === "relay_delete_channel_binding") result = await relayDeleteChannelBinding(args, auth);

package/src/mcp/output-descriptions.ts

@@ -27,14 +27,14 @@ export const OUTPUT_DESCRIPTIONS: Record<string, string> = {
   relay_kernel_listEntities: "List entities.",
   relay_kernel_listEvents: "List events.",
   relay_kernel_listInstances: "List workflow instances.",
-  relay_list_artifacts: "List artifacts; relay_read_artifact reads bodies.",
+  relay_list_artifacts: "List artifacts (metadata only).",
   relay_list_subscriptions: "Your subscriptions",
   relay_list_timers: "List your scheduled timers.",
   relay_maintenance_jobs: "Job health; jobId reads runbook.",
   relay_maintenance_pauses: "Maintenance pauses.",
   relay_merge_pauses: "Merge holds",
   relay_notification_preview: "Preview notification routing.",
-  relay_plan_get: "Read plan; mode:resume selects the frontier view.",
+  relay_plan_get: "Read plan; mode:resume reads the frontier.",
   relay_plan_list: "List team plans.",
   relay_project_checkout: "Inspect, bind, unbind (keeps files) or remove (deletes files) a checkout.",
   relay_project_get: "Read project and roots.",
@@ -44,7 +44,7 @@ export const OUTPUT_DESCRIPTIONS: Record<string, string> = {
   relay_project_search: "Search memory; read full bodies by returned ids.",
   relay_prompt: "Read/edit prompts; writes need expectedVersion; restore/adopt append.",
   relay_read_artifact: "Page artifact text; binary returns download command.",
-  relay_recall: "Search history; read a returned ref for the segment.",
+  relay_recall: "Search history; read a returned ref.",
   relay_release_readiness: "Read release readiness.",
   relay_routing_policy_get: "Read policy",
   relay_run: "Run shell work. Long work: waitMs:0, END YOUR TURN and await completion; never poll.",
@@ -53,17 +53,17 @@ export const OUTPUT_DESCRIPTIONS: Record<string, string> = {
   relay_task_close_bridge: "Read Task close-bridge state.",
   relay_task_get: "Read Task hydration.",
   relay_task_history: "Read Task history.",
-  relay_task_list: "List your Tasks; mine:false lists all.",
+  relay_task_list: "Tasks.",
   relay_task_memory_read: "Read Task continuation.",
   relay_task_needs_validation: "List Tasks awaiting validation.",
   relay_team_get: "Read team and roster summary.",
   relay_team_template_get: "Read saved",
   relay_team_template_list: "Saved",
-  relay_web_tool_calls: "Page web calls newest first; times are epoch milliseconds.",
+  relay_web_tool_calls: "Page web calls, newest first; epoch ms.",
   relay_why_notified: "Explain delivery.",
-  relay_workflow_cancel: "Cancel run and reap agents.",
-  relay_workflow_get: "Read run status; history and result pages are opt-in.",
-  relay_workflow_resume: "Resume or answer/escalate a decision.",
+  relay_workflow_cancel: "Cancel run; reap agents.",
+  relay_workflow_get: "Read run status; history opt-in.",
+  relay_workflow_resume: "Resume, pause/unpause, or answer/escalate a decision.",
   relay_workflow_start: "Start Task workflow.",
   relay_workspace_deps: "Check or refresh workspace dependencies.",
   relay_workspace_list: "List workspaces.",

package/src/mcp/presentation.ts

@@ -50,7 +50,7 @@ export type PresentationVerbosity = "brief" | "lean" | "default" | "verbose";
 
 type TaskGateSummary = Record<TaskGateStatus, number> & { total: number };
 
-type TaskDetailLeanPresentation = Pick<TaskDetail, "validationItems" | "staleOwnerGone" | "terminalStage" | "completedAt" | "owner"> & {
+type TaskDetailLeanPresentation = Pick<TaskDetail, "validationItems" | "staleOwnerGone" | "terminalStage" | "completedAt" | "owner" | "onDeploy"> & {
   id: number;
   title: string;
   status: string;
@@ -328,7 +328,7 @@ export function projectTaskList(
     return tasks.map((task) => ({
       id: task.id,
       label: truncateTaskListLabel(task.label),
-      status: task.status, ...taskValidationProjection(task),
+      status: task.status, ...taskValidationProjection(task), ...(task.onDeploy ? { onDeploy: task.onDeploy } : {}),
     }));
   }
   return tasks.map((task) => {
@@ -339,7 +339,7 @@ export function projectTaskList(
       status: task.status,
       deliverableStage: task.deliverableStage ?? null,
       ownerAgentId: task.ownerAgentId ?? null,
-      ...taskValidationProjection(task),
+      ...taskValidationProjection(task), ...(task.onDeploy ? { onDeploy: task.onDeploy } : {}),
       updatedAt: updatedAt.relative,
       ...(crossRepo && task.repo ? { repo: task.repo } : {}),
     };
@@ -368,7 +368,7 @@ export function projectTaskDetail(
     deliverableStage: task.deliverableStage ?? null,
     ownerAgentLabel: task.ownerAgentLabel ?? null,
     ...(task.owner ? { owner: task.owner } : {}),
-    ...taskValidationProjection(task),
+    ...taskValidationProjection(task), ...(task.onDeploy ? { onDeploy: task.onDeploy } : {}),
     issues: task.issues,
     ...(task.waitedOnBy?.length ? { waitedOnByPlans: task.waitedOnBy.length } : {}),
     gates: summarizeTaskGates(task.gates),

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

@@ -0,0 +1,32 @@
+import { ValidationError } from "../db/connection";
+import { authContextFromMcp } from "../services/auth-context";
+import { listProjectProfileInstructions, mutateProjectProfileInstructions, projectProfileInstructionHistory, readProjectProfileInstructions } from "../services/project-profile-instructions";
+import { stringField } from "./validation";
+import type { McpAuthContext, ToolDefinition } from "./types";
+import { hasAnyScope } from "./identity";
+import { McpAuthError } from "../mcp-errors";
+
+export const PROJECT_PROFILE_INSTRUCTION_TOOLS: ToolDefinition[] = [{
+  name: "relay_project_profile_instructions",
+  description: "Project additions to profile instructions. Empty version is 0. Writes need expectedVersion; restore appends history.",
+  requiredScopes: ["agent:read"],
+  inputSchema: { type: "object", properties: {
+    operation: { type: "string", enum: ["list", "get", "set", "history", "restore"] },
+    projectId: { type: "string" }, profile: { type: "string" }, template: { type: "string" },
+    expectedVersion: { type: "integer", minimum: 0 }, version: { type: "integer", minimum: 1 }, reason: { type: "string" },
+  }, required: ["operation"], additionalProperties: false },
+}];
+
+export async function relayProjectProfileInstructions(auth: McpAuthContext, args: Record<string, unknown>) {
+  if (["set", "restore"].includes(String(args.operation)) && !hasAnyScope(auth, ["agent:write"])) throw new McpAuthError("agent:write scope required");
+  const required = args.operation !== "list";
+  const projectId = stringField(args.projectId, "projectId", { required, max: 200 });
+  const profile = stringField(args.profile, "profile", { required, max: 200 });
+  switch (args.operation) {
+    case "list": return listProjectProfileInstructions({ projectId: projectId || undefined, profile: profile || undefined });
+    case "get": return readProjectProfileInstructions(projectId, profile);
+    case "history": return projectProfileInstructionHistory(projectId, profile);
+    case "set": case "restore": return mutateProjectProfileInstructions(authContextFromMcp(auth), projectId, profile, args, args.operation === "restore");
+    default: throw new ValidationError("unknown project profile instructions operation");
+  }
+}

package/src/mcp/tool-groups.ts

@@ -29,7 +29,7 @@ export const RELAY_TOOL_GROUPS: Record<string, readonly string[]> = {
   // #3110 — opt-in: only profiles that list it (plus coordinator/ops-assistant by default) get the
   // tools AND the secrets:write scope; see runtime-tokens.ts.
   secrets: ["relay_service_access", "relay_secret_reader_create", "relay_secret_project_create", "relay_secret_set"],
-  prompts: ["relay_prompt"],
+  prompts: ["relay_prompt", "relay_project_profile_instructions"],
   quota: ["relay_codex_reset_consume", "relay_claude_api_budget"],
   // #3327 — coordinator-only, like decisions: edits the fleet's routing preferences.
   routing: ["relay_routing_policy_get", "relay_routing_policy_set"],