@humwick/server 0.130.1 → 0.130.3

package/src/config-store.ts

@@ -1120,24 +1120,35 @@ export function listAgentProfiles(): ConfigEntry<AgentProfile>[] {
   ].sort((a, b) => Number(Boolean(b.value.builtIn)) - Number(Boolean(a.value.builtIn)) || a.key.localeCompare(b.key));
 }
 
+/** Where a profile write lands: a built-in's override row, else its own row. The rollback snapshot is
+ *  dropped by setConfigInternal on an override write (#1963 N10). */
+export function agentProfileWriteNamespace(profile: AgentProfile, opts: { overrideBuiltIn?: boolean } = {}): string {
+  return BUILT_IN_AGENT_PROFILE_NAMES.has(profile.name) && opts.overrideBuiltIn ? AGENT_PROFILE_OVERRIDE_NAMESPACE : AGENT_PROFILE_NAMESPACE;
+}
+
+/** The stored entry a profile write returns: an override reads back merged over its built-in. */
+export function savedAgentProfileEntry(saved: ConfigEntry<AgentProfile>): ConfigEntry<AgentProfile> {
+  return saved.namespace === AGENT_PROFILE_OVERRIDE_NAMESPACE ? getAgentProfile(saved.key)! : applyProfilePromptEntry(saved)!;
+}
+
+/** Sync twin for tests and boot; runtime callers use `setAgentProfileAsync` (#1870 S7). */
 export function setAgentProfile(profile: AgentProfile, updatedBy?: string, opts: { overrideBuiltIn?: boolean } = {}): ConfigEntry<AgentProfile> {
-  if (BUILT_IN_AGENT_PROFILE_NAMES.has(profile.name) && opts.overrideBuiltIn) {
-    // The rollback snapshot is dropped by setConfigInternal on this override write (#1963 N10).
-    setConfig(AGENT_PROFILE_OVERRIDE_NAMESPACE, profile.name, profile, updatedBy);
-    return getAgentProfile(profile.name)!;
-  }
-  return applyProfilePromptEntry(setConfig(AGENT_PROFILE_NAMESPACE, profile.name, profile, updatedBy))!;
+  return savedAgentProfileEntry(setConfig(agentProfileWriteNamespace(profile, opts), profile.name, profile, updatedBy));
 }
 
-export function deleteAgentProfile(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): boolean {
-  // #2791 — delete resolves case-insensitively to the stored key, so DELETE /qa drops "QA".
+/** The row a profile delete removes. #2791 — resolves case-insensitively, so DELETE /qa drops "QA". The
+ *  rollback snapshot is dropped by deleteConfigInternal on an override delete (#1963 N10). */
+export function agentProfileDeleteTarget(name: string, opts: { resetBuiltInOverride?: boolean } = {}): { namespace: string; key: string } {
   const canonical = resolveAgentProfileKey(name) ?? name;
-  if (BUILT_IN_AGENT_PROFILE_NAMES.has(canonical)) {
-    // The rollback snapshot is dropped by deleteConfigInternal on this override delete (#1963 N10).
-    if (opts.resetBuiltInOverride) return deleteConfig(AGENT_PROFILE_OVERRIDE_NAMESPACE, canonical, updatedBy);
-    throw new ValidationError("built-in agent profiles are managed by Relay");
-  }
-  return deleteConfig(AGENT_PROFILE_NAMESPACE, canonical, updatedBy);
+  if (!BUILT_IN_AGENT_PROFILE_NAMES.has(canonical)) return { namespace: AGENT_PROFILE_NAMESPACE, key: canonical };
+  if (opts.resetBuiltInOverride) return { namespace: AGENT_PROFILE_OVERRIDE_NAMESPACE, key: canonical };
+  throw new ValidationError("built-in agent profiles are managed by Relay");
+}
+
+/** Sync twin for tests; runtime callers use `deleteAgentProfileAsync` (#1870 S7). */
+export function deleteAgentProfile(name: string, updatedBy?: string, opts: { resetBuiltInOverride?: boolean } = {}): boolean {
+  const target = agentProfileDeleteTarget(name, opts);
+  return deleteConfig(target.namespace, target.key, updatedBy);
 }
 
 export function getManagedAgentState(policyName: string): ManagedAgentState | null {

package/src/config.ts

@@ -637,21 +637,14 @@ export const DB_READER_JOB_TIMEOUT_MS = envPositiveInt("AGENT_RELAY_DB_READER_JO
 export const DB_READER_MARSHAL_IN_PROCESS =
   process.env.NODE_ENV === "test" || relayEnv(process.env, "AGENT_RELAY_DB_MARSHAL") === "1";
 
-/**
- * Phase-R rollout gate (#1960 T2 — ADR 0001 §7 Phase 1) for the gateway's READER half only. The
- * writer stays in-process unconditionally: Phase W (a worker writer taking the sole RW connection) is
- * a separate, much larger burn-down (#1870) and is deliberately NOT wired here. Any value other than
- * the literal `"worker"` — unset included — resolves to `"in-process"`, so this is behavior-preserving
- * by default; an operator opts in explicitly per the same string-literal convention as
- * `parseKernelTimersMode`.
- */
+/** Explicit reader placement override. Otherwise file databases use workers (#3339). */
 export type GatewayReaderBackendMode = "in-process" | "worker";
 
-export function parseGatewayReaderBackend(value: string | undefined): GatewayReaderBackendMode {
-  return value === "worker" ? "worker" : "in-process";
+export function parseGatewayReaderBackend(value: string | undefined): GatewayReaderBackendMode | undefined {
+  return value === "worker" || value === "in-process" ? value : undefined;
 }
 
-export function gatewayReaderBackendFromEnv(): GatewayReaderBackendMode {
+export function gatewayReaderBackendFromEnv(): GatewayReaderBackendMode | undefined {
   return parseGatewayReaderBackend(relayEnv(process.env, "AGENT_RELAY_GATEWAY_READER_BACKEND"));
 }
 

package/src/connectors.ts

@@ -1,10 +1,12 @@
+import { framed } from "./hub-metrics";
+import { upsertAgentAsync } from "./db/agents-async";
 import { writeChildEnv } from "@humwick/sdk/env";
 import { timePostBindPhase } from "./post-bind-startup";
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import type { ConnectorAction, ConnectorActionResult, ConnectorManifest, ConnectorSummary } from "./types";
-import { upsertAgent, ValidationError } from "./db";
+import { ValidationError } from "./db";
 import { CHANNELS_HOST_SECRETS } from "@humwick/sdk/channels-host-service";
 import { fireAndForget, guardedInterval, isRecord } from "@humwick/sdk";
 import { registerConnectorConfigSetting, validateConnectorConfig } from "./settings/modules";
@@ -274,11 +276,11 @@ export function startConnectorStatusPoller(): void {
   //    deploy that took down the relay/orchestrator tree) BEFORE the first status
   //    poll overwrites their persisted "running" flag with the now-dead reality.
   void fireAndForget("[connectors] boot reconcile", async () => {
-    await fireAndForget("[connectors] ensure channels host", () => timePostBindPhase("connectors.ensureChannelsHostConnector", () => ensureChannelsHostOnBoot()));
+    await fireAndForget("[connectors] ensure channels host", () => timePostBindPhase("connectors.ensureChannelsHostConnector", async () => (await ensureChannelsHostOnBoot())));
     await fireAndForget("[connectors] reconcile on boot", () => timePostBindPhase("connectors.reconcileConnectorsOnBoot", reconcileConnectorsOnBoot));
     await timePostBindPhase("connectors.refreshAllConnectorStatuses", refreshAllConnectorStatuses);
   });
-  guardedInterval("[connectors] status poll", STATUS_POLL_INTERVAL_MS, () => timePostBindPhase("connectors.refreshAllConnectorStatuses", refreshAllConnectorStatuses));
+  guardedInterval("[connectors] status poll", STATUS_POLL_INTERVAL_MS, framed("timer connector-status", () => timePostBindPhase("connectors.refreshAllConnectorStatuses", refreshAllConnectorStatuses)));
 }
 
 const CHANNELS_HOST_ID = "channels-host";
@@ -386,14 +388,14 @@ function configuredNtfyTopic(): string | null {
  * adapter's own gate — an unconfigured relay genuinely has no escalation target and must
  * still warn. Returns true when the row was (re)registered.
  */
-export function ensureEscalationChannelRegistered(): boolean {
+export async function ensureEscalationChannelRegistered(): Promise<boolean> {
   if (isEphemeralMode()) return false;
   const topic = configuredNtfyTopic();
   if (!topic) return false;
   // Shape matches the channels-host adapter's registration (channels-host/src/relay.ts
   // registerChannel + adapters/ntfy.ts channels()), so its later re-registration updates
   // the same row in place rather than churning it.
-  upsertAgent({
+  (await upsertAgentAsync({
     id: ESCALATION_NTFY_CHANNEL_ID,
     name: "ntfy",
     kind: "channel",
@@ -411,7 +413,7 @@ export function ensureEscalationChannelRegistered(): boolean {
       displayName: "ntfy",
       topicChannels: [topic],
     },
-  });
+  }));
   return true;
 }
 
@@ -429,7 +431,7 @@ export async function ensureChannelsHostConnector(entry = resolveChannelsHostEnt
   // Register the escalation channel row now that config (incl. any legacy-migrated topic)
   // is persisted, so the escalation-target check passes without waiting for the async
   // channels-host SSE connect (#1510).
-  ensureEscalationChannelRegistered();
+  (await ensureEscalationChannelRegistered());
 
 
 }
@@ -437,7 +439,7 @@ export async function ensureChannelsHostConnector(entry = resolveChannelsHostEnt
 /** Boot wrapper: a failed bring-up is logged with its stack and raised to /api/health, never swallowed (#3393). */
 export async function ensureChannelsHostOnBoot(entry?: string | null): Promise<void> {
   try {
-    await (entry === undefined ? ensureChannelsHostConnector() : ensureChannelsHostConnector(entry));
+    await (entry === undefined ? (await ensureChannelsHostConnector()) : (await ensureChannelsHostConnector(entry)));
     clearChannelsHostEnsureFailure();
   } catch (error) {
     console.error("[connectors] ensureChannelsHostConnector failed:", error instanceof Error ? (error.stack ?? error.message) : error);

package/src/context-advisory.ts

@@ -1,5 +1,6 @@
+import { getGateway } from "./db/gateway";
 import { deriveContextThresholdFromWindowTokens, findProviderCatalogModel, resolveProviderContextThreshold, type ProviderModelCatalogEntry, type ResolvedProviderContextThreshold } from "@humwick/sdk/provider-catalog";
-import { isRecord, isSpawnProvider } from "@humwick/sdk";
+import { fireAndForget, isRecord, isSpawnProvider } from "@humwick/sdk";
 import { HARD_BACKSTOP_BUSY_GRACE_MS } from "./config";
 import { getConfig } from "./config-store";
 import { getToken } from "./token-db";
@@ -39,7 +40,7 @@ interface EffectiveContextThreshold extends ResolvedProviderContextThreshold {
  * #315 — context pressure is a relay-native signal: durable event for observers,
  * plus an agent-facing system push when lifecycle notifications are enabled.
  */
-function notifyContextAdvisory(input: ContextAdvisoryInput): void {
+async function notifyContextAdvisory(input: ContextAdvisoryInput): Promise<void> {
   const payload = {
     kind: "agent.context_threshold",
     agentId: input.agentId,
@@ -63,20 +64,20 @@ function notifyContextAdvisory(input: ContextAdvisoryInput): void {
 
   // Short default TTL (per-type): a stale context advisory is misleading — the band may have moved
   // by the time the agent next polls, so old advice shouldn't wake it.
-  routeNotification({
+  await routeNotification({
     type: "agent.context_threshold",
     scope: { agentId: input.agentId },
     recipients: [input.agentId],
     message: {
       subject: input.stage === "warn" ? "Context threshold warning" : "Context self-compact threshold reached",
-      body: contextAdvisoryBody(input),
+      body: (await contextAdvisoryBody(input)),
       payload,
       replyExpected: false,
     },
   });
 }
 
-function contextAdvisoryBody(input: ContextAdvisoryInput): string {
+async function contextAdvisoryBody(input: ContextAdvisoryInput): Promise<string> {
   const tokens = `${formatTokens(input.tokens)} / ${formatTokens(input.windowTokens)} tokens used`;
   const percent = `${input.percent}% of window, ${input.band}% band`;
   const threshold = `resolved self-compact threshold ${input.selfCompactPercent}% (${input.thresholdSource})`;
@@ -96,7 +97,7 @@ function contextAdvisoryBody(input: ContextAdvisoryInput): string {
       threshold,
       hardBackstop: `${input.hardBackstopPercent}%`,
     });
-  return withPreBoundaryCapture(advisory, input.agentId);
+  return (await withPreBoundaryCapture(advisory, input.agentId));
 }
 
 /**
@@ -110,8 +111,8 @@ function contextAdvisoryBody(input: ContextAdvisoryInput): string {
  * Appended rather than woven into the advisory templates so a blank slug leaves the advisory body
  * BYTE-IDENTICAL to the pre-P5 one.
  */
-function withPreBoundaryCapture(advisory: string, agentId: string): string {
-  const capture = boundaryCaptureClause({ seam: "pre", agentId });
+async function withPreBoundaryCapture(advisory: string, agentId: string): Promise<string> {
+  const capture = (await boundaryCaptureClause({ seam: "pre", agentId }));
   return capture ? `${advisory}\n\n${capture}` : advisory;
 }
 
@@ -123,12 +124,12 @@ function contextAdvisoryBand(utilization: number, threshold: EffectiveContextThr
   return { band: utilizationPercent(threshold.warnUtilization), stage: "warn" };
 }
 
-export function handleContextPressure(input: {
+export async function handleContextPressure(input: {
   agent: AgentCard;
   now: () => number;
   hasActiveCommand: (target: string, type: string) => boolean;
-  compact: (reason: string) => Command | null;
-}): boolean {
+  compact: (reason: string) => Command | null | Promise<Command | null>;
+}): Promise<boolean> {
   const { agent, now } = input;
   const context = agent.context;
   if (!context) return false;
@@ -138,7 +139,7 @@ export function handleContextPressure(input: {
   const advisory = contextAdvisoryBand(context.utilization, threshold);
   if (advisory === null) {
     if (context.lastContextAdvisoryBand !== undefined || context.lastContextAdvisoryAt !== undefined || context.hardBackstopDeferredAt !== undefined) {
-      persistContextState(agent.id, clearContextAdvisory(context));
+      (await persistContextState(agent.id, clearContextAdvisory(context)));
     }
     return false;
   }
@@ -160,8 +161,8 @@ export function handleContextPressure(input: {
     // mid-turn (the runner waits for the live turn to clear before submitting the keystrokes).
     const graceElapsed = deferredAt !== undefined && now() - deferredAt >= HARD_BACKSTOP_BUSY_GRACE_MS;
     if (!busy || graceElapsed) {
-      input.compact(busy ? "context-hard-backstop-busy" : "context-hard-backstop");
-      if (deferredAt !== undefined) persistContextState(agent.id, clearHardBackstopDefer(context));
+      await input.compact(busy ? "context-hard-backstop-busy" : "context-hard-backstop");
+      if (deferredAt !== undefined) (await persistContextState(agent.id, clearHardBackstopDefer(context)));
       return true;
     }
     // Busy and within grace: start the bounded defer clock (once), then fall through so the
@@ -169,19 +170,19 @@ export function handleContextPressure(input: {
     // the forced backstop.
     if (deferredAt === undefined) {
       state = { ...context, hardBackstopDeferredAt: now() };
-      persistContextState(agent.id, state);
+      (await persistContextState(agent.id, state));
     }
   } else if (context.hardBackstopDeferredAt !== undefined) {
     // Dropped below the hard backstop (or a forced compaction is already in flight): reset the clock
     // so a later re-crossing starts a fresh grace window rather than firing immediately.
     state = clearHardBackstopDefer(context);
-    persistContextState(agent.id, state);
+    (await persistContextState(agent.id, state));
   }
   if (state.lastContextAdvisoryBand === advisory.band) return false;
   const tokens = finiteNumber(context.tokensUsed);
   const windowTokens = finiteNumber(context.tokensMax);
   if (tokens === undefined || windowTokens === undefined) return false;
-  notifyContextAdvisory({
+  await fireAndForget(`[context] advisory ${input.agent.id}`, async () => (await notifyContextAdvisory({
     agentId: agent.id,
     agent,
     tokens,
@@ -193,8 +194,8 @@ export function handleContextPressure(input: {
     selfCompactPercent: utilizationPercent(threshold.selfCompactUtilization),
     hardBackstopPercent: utilizationPercent(threshold.hardBackstopUtilization),
     thresholdSource: threshold.source,
-  });
-  persistContextState(agent.id, { ...state, lastContextAdvisoryBand: advisory.band, lastContextAdvisoryAt: now() });
+  })));
+  (await persistContextState(agent.id, { ...state, lastContextAdvisoryBand: advisory.band, lastContextAdvisoryAt: now() }));
   return true;
 }
 
@@ -258,8 +259,8 @@ function clearHardBackstopDefer(context: ContextState): ContextState {
   return rest;
 }
 
-function persistContextState(agentId: string, context: ContextState): void {
-  getDb().query("UPDATE agents SET context_state = ? WHERE id = ?").run(JSON.stringify(context), agentId);
+async function persistContextState(agentId: string, context: ContextState): Promise<void> {
+  await getGateway().write("agents.persistAdvisoryContext", [agentId, context]);
 }
 
 function finiteNumber(value: unknown): number | undefined {

package/src/db/activity-async.ts

@@ -4,7 +4,7 @@
 import { activityWriteIdempotencyKey } from "./activity-write-ops.ts";
 import { getGateway } from "./gateway.ts";
 import type { ActivityEvent, ActivityEventInput } from "../types";
-import type { AgentIssueActivitySummary, AgentTimelineEntry, IssueActivityAction, IssueActivityAgentSummary, RecordIssueActivityInput } from "./activity.ts";
+import type { AgentIssueActivitySummary, CreateActivityEventResult, AgentTimelineEntry, IssueActivityAction, IssueActivityAgentSummary, RecordIssueActivityInput } from "./activity.ts";
 
 export async function listActivityEventsAsync(input: {
   operatorId?: string;
@@ -43,6 +43,11 @@ export async function createActivityEventAsync(input: ActivityEventInput, idempo
   return (await getGateway().write("activity.create", { input }, { idempotencyKey: key })) as unknown as ActivityEvent;
 }
 
+/** Creates by `clientId` and reports whether this call created the row (false: the id already existed). */
+export async function createActivityEventByClientIdAsync(input: ActivityEventInput & { clientId: string }): Promise<CreateActivityEventResult> {
+  return (await getGateway().write("activity.createByClientId", { input })) as unknown as CreateActivityEventResult;
+}
+
 /** See `createActivityEventAsync` — same `idempotent: false` / key-derivation contract. */
 export async function recordIssueActivityAsync(input: RecordIssueActivityInput, idempotencyKey?: string): Promise<ActivityEvent> {
   const key = activityWriteIdempotencyKey(idempotencyKey, input.clientId);

package/src/db/activity-write-ops.ts

@@ -14,7 +14,8 @@
 // "do not blindly retry").
 
 import { randomUUID } from "node:crypto";
-import { createActivityEvent, recordIssueActivity } from "./activity.ts";
+import { createActivityEvent, createActivityEventWithResult, recordIssueActivity } from "./activity.ts";
+import type { CreateActivityEventResult } from "./activity.ts";
 import type { ActivityEvent, ActivityEventInput } from "../types";
 import type { RecordIssueActivityInput } from "./activity.ts";
 import type { WriterOpContext, WriterOpSpec } from "./write-ops.ts";
@@ -28,6 +29,16 @@ export const ACTIVITY_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object
     idempotent: false,
     fn: (args: ActivityCreateOpArgs, ctx: WriterOpContext): ActivityEvent => createActivityEvent(args.input, ctx.now),
   },
+  // Dedups on `clientId` inside the body, so a replay reports `created: false` truthfully; the idempotency
+  // ledger would instead replay the first `created: true` (#1870 S7, operator alarms).
+  "activity.createByClientId": {
+    offLoop: true,
+    idempotent: true,
+    fn: (args: ActivityCreateOpArgs, ctx: WriterOpContext): CreateActivityEventResult => {
+      if (!args.input.clientId) throw new Error("activity.createByClientId requires input.clientId");
+      return createActivityEventWithResult(args.input, ctx.now);
+    },
+  },
   "activity.recordIssueActivity": {
     offLoop: true,
     idempotent: false,

package/src/db/activity.ts

@@ -1,18 +1,5 @@
-import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "@humwick/sdk";
-import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
+import { isRecord, stringValue } from "@humwick/sdk";
 import { parseJson } from "../utils";
-import { isLiveIsolatedWorkspace } from "../workspace-phase";
-import {
-  CONTRACT_REQUIREMENTS,
-  contractCompatibility,
-  parseRuntimeCapabilities,
-  parseRuntimeContracts,
-  parseRuntimePackage,
-  type RuntimeContracts,
-} from "../contracts";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
-import { matchAgents } from "../agent-ref";
 import { getDb, ValidationError } from "./connection.ts";
 import { rowToActivityEvent } from "./mappers.ts";
 import { getIssueRef, resolveIssueRefFromString } from "./issue-refs.ts";

package/src/db/agent-action-write.ts

@@ -0,0 +1,36 @@
+import { ValidationError } from "@humwick/sdk";
+import { createCommandInternal, getCommand } from "../commands-db";
+import { assertSelfEffortAllowed } from "../services/self-effort";
+import { admitDesiredEffortInternal, getAgentEffortState } from "./agent-effort-state";
+import { getAgent } from "./agents";
+import { sendMessageWithResultInternal } from "./messages";
+import type { AgentCard, CreateCommandInput, SendMessageInput } from "../types";
+import type { EffortChangeActorRole } from "@humwick/sdk";
+
+export interface AgentActionWrite {
+  agent: AgentCard;
+  commandId: string;
+  commandInput: Omit<CreateCommandInput, "params"> & { params: Record<string, unknown> };
+  requestId?: string;
+  effort?: string;
+  role: EffortChangeActorRole;
+  selfEffort?: { level: string; efforts?: readonly string[] };
+  message?: SendMessageInput;
+}
+
+export function admitAgentActionBody(input: AgentActionWrite, now: number) {
+  const prior = input.requestId ? getCommand(input.requestId) : null;
+  if (prior) {
+    if (prior.type !== "agent.setEffort" || prior.target !== input.agent.id) throw new ValidationError("requestId belongs to another request");
+    return { command: prior, raced: true, effortState: getAgentEffortState(input.agent.id) };
+  }
+  const current = getAgent(input.agent.id);
+  if (!current || current.instanceId !== input.agent.instanceId || current.epoch !== input.agent.epoch) throw new ValidationError("agent instance changed while the action audit was committing");
+  if (input.selfEffort) assertSelfEffortAllowed(current, input.selfEffort.level, input.selfEffort.efforts);
+  const sent = input.message ? sendMessageWithResultInternal(input.message, false, {}, now) : undefined;
+  if (sent) Object.assign(input.commandInput.params, { messageId: sent.message.id, from: sent.message.from });
+  const admitted = input.effort ? admitDesiredEffortInternal({ agentId: current.id, effort: input.effort, role: input.role, commandId: input.commandId, now }) : undefined;
+  if (admitted) input.commandInput.params.effortVersion = admitted.state.desiredVersion;
+  const command = createCommandInternal({ input: input.commandInput, id: input.commandId }, now);
+  return { command, raced: false, admitted, sessionMessage: sent?.message };
+}

package/src/db/agent-control-async.ts

@@ -0,0 +1,9 @@
+import { getGateway } from "./gateway";
+import type { AgentControlWrite, SelfEffortGrantWrite, createAgentControlBody, grantSelfEffortBody } from "./agent-control-write";
+
+export function createAgentControlAsync(input: AgentControlWrite): Promise<ReturnType<typeof createAgentControlBody>> {
+  return getGateway().write("agents.createControl", input, { idempotencyKey: input.commandId, critical: true }) as unknown as Promise<ReturnType<typeof createAgentControlBody>>;
+}
+export function grantSelfEffortAsync(input: SelfEffortGrantWrite): Promise<ReturnType<typeof grantSelfEffortBody>> {
+  return getGateway().write("agents.grantSelfEffort", input, { idempotencyKey: input.commandId }) as unknown as Promise<ReturnType<typeof grantSelfEffortBody>>;
+}

package/src/db/agent-control-write.ts

@@ -0,0 +1,49 @@
+import { ValidationError } from "@humwick/sdk";
+import { createCommandInternal, updateCommandInternal } from "../commands-db";
+import { agentProviderState } from "../provider-state";
+import { stopRefusal, type SafeCandidate } from "../services/idle-agent-digest";
+import { selfEffortIdentity, type SelfEffortGrant, type SelfEffortPolicy } from "../services/self-effort";
+import { getAgent } from "./agents";
+import { SELF_EFFORT_BAND, setSelfEffortCeilingInternal } from "./self-effort-permissions";
+import type { AgentCard, Command, CreateCommandInput } from "../types";
+
+export interface AgentControlWrite {
+  agent?: AgentCard | null;
+  commandId: string;
+  commandInput: CreateCommandInput;
+  approvalId?: string;
+  idleCandidate?: SafeCandidate;
+}
+export function createAgentControlBody(input: AgentControlWrite, now: number): { command?: Command; refused?: string } {
+  if (input.agent) {
+    const current = getAgent(input.agent.id);
+    if (!current || current.instanceId !== input.agent.instanceId || current.epoch !== input.agent.epoch) throw new ValidationError("agent instance changed while the action audit was committing");
+    if (input.approvalId) {
+      const state = agentProviderState(current);
+      if (state?.state !== "blocked" || state.pendingApproval?.id !== input.approvalId) throw new ValidationError("approval request is no longer current");
+    }
+    if (input.idleCandidate) {
+      const refusal = stopRefusal(input.idleCandidate, current, now);
+      if (refusal) return { refused: refusal.reason };
+    }
+  }
+  return { command: createCommandInternal({ input: input.commandInput, id: input.commandId }, now) };
+}
+
+export const SELF_EFFORT_GRANT_COMMAND = "agent.grantSelfEffort";
+export interface SelfEffortGrantWrite {
+  agent: AgentCard; grant?: SelfEffortGrant; requestedBy: string; commandId: string; spawnRequestId?: string;
+  input: { requestedVia: "mcp" | "http"; requestedByUser?: string };
+  selfEffort: SelfEffortPolicy | null; previous: SelfEffortPolicy | null;
+}
+export function grantSelfEffortBody({ agent, grant, requestedBy, commandId, spawnRequestId, input, selfEffort, previous }: SelfEffortGrantWrite, now: number): Command {
+  const current = getAgent(agent.id);
+  if (!current || current.instanceId !== agent.instanceId || current.epoch !== agent.epoch) throw new ValidationError("agent instance changed while the action audit was committing");
+  const identity = selfEffortIdentity(current);
+  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!;
+}

package/src/db/agent-effort-observe.ts

@@ -0,0 +1,22 @@
+import { validateAgentSession } from "./agents";
+import { recordEffortObservedInternal } from "./agent-effort-state";
+import { findMessageByIdempotencyKey, sendMessageWithResultInternal } from "./messages";
+export class EffortReportFenced extends Error {}
+/** #2984 — the prompt that resumes an agent once its own effort change applied. */
+export function selfEffortContinuation(effort: string): string {
+  return `Effort is now ${effort}. Continue your work.`;
+}
+
+
+export function observeEffortBody(input: Parameters<typeof recordEffortObservedInternal>[0]) {
+  const session = validateAgentSession(input.agentId, { instanceId: input.instanceId });
+  if (!session.ok) throw new EffortReportFenced(session.error ?? "stale agent instance");
+  const observed = recordEffortObservedInternal(input);
+  const version = observed.outcome !== "stale" ? observed.resumeVersion : undefined;
+  const key = `effort-continuation:${input.agentId}:${version}`;
+  const continuation = version !== undefined && !findMessageByIdempotencyKey("system", key)
+    ? sendMessageWithResultInternal({ from: "system", to: input.agentId, kind: "system", subject: "Effort changed",
+      body: selfEffortContinuation(input.effort), replyExpected: false, idempotencyKey: key,
+      payload: { kind: "agent.effort_continuation", agentId: input.agentId, effortVersion: version, effort: input.effort } }, false, {}, input.now).message : null;
+  return { observed, continuation };
+}

package/src/db/agent-meta.ts

@@ -5,6 +5,8 @@
 import { isRecord } from "@humwick/sdk";
 
 export const AGENT_META_WARN_BYTES = 64 * 1024;
+export const PROFILE_PROJECTION_WARN_BYTES = 192 * 1024;
+export const COMMAND_PROFILE_WARN_BYTES = 1024 * 1024;
 
 // Log dedupe only, so a per-thread copy is correct: the writer thread warns once itself (#1870 S6c).
 const warnedOversizeMeta = new Set<string>();
@@ -62,13 +64,22 @@ export function jsonBytes(value: string): number {
 
 /** Runtime tripwire: one warning per agent/source until the payload returns below the ceiling. */
 export function warnIfAgentMetaOversized(agentId: string, json: string, source: string): void {
-  const key = `${agentId}:${source}`;
+  warnIfOversized(`${agentId}:${source}`, json, AGENT_META_WARN_BYTES, `[agent-meta] ${agentId} ${source}`);
+}
+
+export function warnIfOversized(key: string, json: string, threshold: number, label: string): void {
   const bytes = jsonBytes(json);
-  if (bytes <= AGENT_META_WARN_BYTES) {
+  if (bytes <= threshold) {
     warnedOversizeMeta.delete(key);
     return;
   }
   if (warnedOversizeMeta.has(key)) return;
   warnedOversizeMeta.add(key);
-  console.warn(`[agent-meta] ${agentId} ${source} is ${bytes} bytes (alarm threshold ${AGENT_META_WARN_BYTES})`);
+  console.warn(`${label} is ${bytes} bytes (alarm threshold ${threshold})`);
+}
+
+export function serializeProfileProjection(agentId: string, projection: unknown): string | null {
+  const json = projection == null ? null : JSON.stringify(projection);
+  warnIfOversized(`projection:${agentId}`, json ?? "", PROFILE_PROJECTION_WARN_BYTES, `[agent-profile] ${agentId} profile_projection`);
+  return json;
 }

package/src/db/agent-search.ts

@@ -1,18 +1,4 @@
-import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "@humwick/sdk";
-import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
-import { parseJson } from "../utils";
-import { isLiveIsolatedWorkspace } from "../workspace-phase";
-import {
-  CONTRACT_REQUIREMENTS,
-  contractCompatibility,
-  parseRuntimeCapabilities,
-  parseRuntimeContracts,
-  parseRuntimePackage,
-  type RuntimeContracts,
-} from "../contracts";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
-import { matchAgents } from "../agent-ref";
+import { STALE_TTL_MS } from "../config";
 import { ROSTER_AGENT_COLUMNS } from "./agent-card-read.ts";
 import { getDb } from "./connection.ts";
 import { rowToAgent } from "./mappers.ts";