@humwick/runner 0.0.0-stage → 0.130.1

package/src/agent-runner/turn-report.ts

@@ -0,0 +1,269 @@
+import { isHumanAgentId, errMessage, type Message, type HumwickBusClient, type HumwickHttpClient } from "@humwick/sdk";
+import type { ProviderAdapter, ProviderConfig, ProviderDeliverContext, ProviderSessionEvent, ProviderSessionTurnContext, ProviderSessionTurnInput, ProviderUserPromptInput } from "../adapter";
+import { publishCapturedResponse } from "../response-capture-report";
+import { submittedResponseReplyRoute, type responseCaptureReplyRoute } from "../reply-obligation-cache";
+import { PRE_DESTROY_TIMEOUT_MS, reasonExitsRunner, type LifecycleAction, type SessionDestroyReason } from "../session-destroy";
+import type { SessionMirror } from "./session-mirror";
+import { TurnOpenerLedger } from "../turn-opener";
+
+type CaptureOptions = { transcriptPath?: string };
+interface TurnReportDeps {
+  agentId: string;
+  provider: string;
+  adapter: Pick<ProviderAdapter, "captureSessionTurn" | "handleUserPrompt">;
+  providerConfig: Pick<ProviderConfig, "chatCaptureMode" | "reasoningCapture">;
+  http: Pick<HumwickHttpClient, "getThread">;
+  currentTurnId(): string | undefined;
+  currentTurnStartedAt(): number | undefined;
+  setTurnId(id: string): void;
+  setTurnStartedAt(at: number): void;
+  lastTranscriptPath(): string | undefined;
+  noteTranscriptPath(path: string): void;
+  providerSessionId(): string;
+  queuedTurnFollows(): boolean;
+  setQueuedTurnFollows(queued: boolean): void;
+  settlePollIntervalMs(): number;
+  settlePollTimeoutMs(): number;
+  beginTurnCapture(): void;
+  endTurnCapture(): void;
+  flushSessionEvents(timeoutMs: number): Promise<boolean>;
+  pendingSessionEventCount(): number;
+  publishSessionEvent: SessionMirror["publishSessionEvent"];
+  reportOutbox: Parameters<typeof publishCapturedResponse>[0]["outbox"];
+  flushOutbox(timeoutMs: number): Promise<boolean>;
+  settleTerminalTokenUsage(path: string | undefined): Promise<void>;
+  noteOutput(): void;
+  notePrompt(text: string, firedAt: number | undefined): void;
+  isRunnerInjectedPrompt(text: string): boolean;
+  deliverySubmitHold(): boolean;
+  tryRecoverProviderSubmitHold(started: boolean): void;
+  lifecycleAction(): LifecycleAction | undefined;
+  isStopped(): boolean;
+  terminalStatusLatched(): boolean;
+  setLifecycleAction(action: LifecycleAction | undefined): void;
+  noteFinalizing(action: LifecycleAction, at: number): void;
+  publishRunnerStatus(update: Parameters<HumwickBusClient["status"]>[0]): boolean;
+  publishStatus(): void;
+  captureContextRatio(reason: SessionDestroyReason, opts?: CaptureOptions): Promise<void>;
+  captureContinuationArchive(reason: SessionDestroyReason, opts?: CaptureOptions): Promise<void>;
+  responseCaptureReplyRoute(startedAt: number | undefined, suppressUser: boolean): ReturnType<typeof responseCaptureReplyRoute>;
+  dirtyObligations(): void;
+  sessionLog(message: string): void;
+  sessionDebug(message: string): void;
+}
+
+// Bounded window to deliver the durable outbox before an exit-bound teardown (#183).
+const OUTBOX_FLUSH_TIMEOUT_MS = 3_000;
+
+export class TurnReport {
+  private pendingPromptMessageId?: number;
+  private readonly turnOpener = new TurnOpenerLedger(() => this.deps.agentId);
+  // Coalesces every pre-session-destroy report for one provider incarnation, including a
+  // sequential SessionEnd hook that arrives after the shutdown command's capture completed.
+  private preDestroyRun?: { providerSessionId: string; capture: Promise<void>; exitFlush?: Promise<void> };
+
+  constructor(private readonly deps: TurnReportDeps) {}
+
+  notePendingPrompt(messageId: number): void { this.pendingPromptMessageId = messageId; }
+  takePendingPrompt(): number | undefined {
+    const messageId = this.pendingPromptMessageId;
+    this.pendingPromptMessageId = undefined;
+    return messageId;
+  }
+  clearPreDestroyRun(): void { this.preDestroyRun = undefined; }
+  armTurnOpener(messages: Message[]): void { this.turnOpener.arm(messages); }
+  openTurnOpener(messages: Message[], opensTurn: boolean, ctx?: ProviderDeliverContext): ReturnType<TurnOpenerLedger["open"]> { return this.turnOpener.open(messages, opensTurn, ctx); }
+  noteTurnStarted(turnId: string): void { this.turnOpener.noteTurnStarted(turnId); }
+  takeTurnOpener(turnId: string | undefined): ReturnType<TurnOpenerLedger["take"]> { return this.turnOpener.take(turnId); }
+
+  async publishProviderResponse(event: ProviderSessionEvent, body: string, turnId: string | undefined): Promise<void> {
+    // Dashboard prompt injection is already answered by this captured App Server
+    // response. User obligations still belong to the session mirror; spawner
+    // obligations (#413) route to the spawn-parent with replyTo to clear the debt.
+    // #1083: a turn-final capture is ALWAYS mirrored, regardless of reply route — an
+    // autonomous provider turn with no pending prompt and no eligible obligation used to
+    // hit `if (!route) return` here and vanish before ever reaching publishCapturedResponse,
+    // so it was neither shown in the dashboard nor eligible for report-up. The route only
+    // decides whether an explicit reply/obligation-clear also happens; when there's none,
+    // replyToMessageId stays undefined and the capture still lands as a plain session-mirror
+    // response (enqueueCapturedResponseReport's own `!replyTo` gate then correctly skips
+    // report-up — there's no spawner obligation to report up against).
+    let replyToMessageId: number | undefined, replyTarget = "user";
+    // #2335 — the route resolved to a channel-egress bridge; publishCapturedResponse re-addresses
+    // the capture to the dashboard mirror rather than DM'ing this agent's narration to a human.
+    let channelTarget = false, answersMessageId: number | undefined; // #2840 — the delivered opener this final answers
+    // A hookless capture finishes after its idle edge, so its opener was snapshotted there (event.opener).
+    const pendingPrompt = this.pendingPromptMessageId, opener = event.opener !== undefined ? event.opener ?? undefined : this.takeTurnOpener(turnId);
+    if (event.replyRoute !== undefined) {
+      this.takePendingPrompt();
+      const route = await submittedResponseReplyRoute(event.replyRoute, id => this.deps.http.getThread(id), this.deps.agentId);
+      if (route) { replyToMessageId = answersMessageId = route.replyToMessageId; replyTarget = route.to; channelTarget = route.channelTarget === true; }
+    } else if (pendingPrompt && !this.deps.queuedTurnFollows()) { // #2919 — a prompt queued behind this turn is answered by its own turn
+      replyToMessageId = pendingPrompt;
+      this.takePendingPrompt();
+    } else {
+      // An opener already answered in its thread stays mirror-only; an obligation route (a possibly stale
+      // snapshot) passes the same thread check, so a native final never doubles an explicit reply.
+      const candidate = opener ?? this.deps.responseCaptureReplyRoute(this.deps.currentTurnStartedAt(), event.replyToUserObligation !== true);
+      const route = candidate?.replyToMessageId && !isHumanAgentId(candidate.to) ? await submittedResponseReplyRoute({ ...candidate, replyToMessageId: candidate.replyToMessageId }, id => this.deps.http.getThread(id), this.deps.agentId, !opener) : candidate;
+      answersMessageId = opener ? route?.replyToMessageId : undefined;
+      if (route) { replyToMessageId = route.replyToMessageId; replyTarget = route.to; channelTarget = route.channelTarget === true; }
+    }
+    await publishCapturedResponse({ publishSessionEvent: (sessionEvent) => this.deps.publishSessionEvent({ ...sessionEvent, ...(event.occurredAt ? { occurredAt: event.occurredAt } : {}) }), outbox: this.deps.reportOutbox, provider: this.deps.provider, from: this.deps.agentId, to: replyTarget, body, replyTo: replyToMessageId, channelTarget, session: { type: "response", origin: event.origin ?? "provider", ...(turnId ? { turnId } : {}), ...(event.confidence ? { confidence: event.confidence } : {}), ...(event.endedBy ? { endedBy: event.endedBy } : {}), ...(answersMessageId ? { answersMessageId } : {}) } });
+    if (replyToMessageId) this.deps.dirtyObligations();
+  }
+
+  async publishSessionTurn(input: ProviderSessionTurnInput): Promise<{ reasoningSettled: boolean } | void> {
+    if (input.transcriptPath) this.deps.noteTranscriptPath(input.transcriptPath);
+    // #2389 — a pre-flush capture IS a tool call in flight: independent proof the turn is doing
+    // work, and the only such proof for a tools-only turn on an agent with reasoningCapture off.
+    if (input.isPreFlush) this.deps.noteOutput();
+    this.deps.beginTurnCapture();
+    if (!input.isPreFlush) this.deps.setQueuedTurnFollows(false);
+    try {
+      const ctx = input.isPreFlush ? this.sessionTurnContext() : { ...this.sessionTurnContext(), noteQueuedTurn: () => { this.deps.setQueuedTurnFollows(true); } };
+      const result = await this.deps.adapter.captureSessionTurn?.(input, ctx);
+      return typeof result?.reasoningSettled === "boolean" ? { reasoningSettled: result.reasoningSettled } : undefined;
+    } finally {
+      this.deps.endTurnCapture();
+    }
+  }
+
+  sessionTurnContext(): ProviderSessionTurnContext {
+    return {
+      turnId: this.deps.currentTurnId(),
+      turnStartedAt: this.deps.currentTurnStartedAt(),
+      chatCaptureMode: this.deps.providerConfig.chatCaptureMode,
+      reasoningCapture: this.deps.providerConfig.reasoningCapture,
+      settlePollIntervalMs: this.deps.settlePollIntervalMs(),
+      settlePollTimeoutMs: this.deps.settlePollTimeoutMs(),
+      flushSessionEvents: (timeoutMs) => this.deps.flushSessionEvents(timeoutMs),
+      pendingSessionEventCount: () => this.deps.pendingSessionEventCount(),
+      log: (message) => this.deps.sessionLog(message),
+      debug: (message) => this.deps.sessionDebug(message),
+    };
+  }
+
+  async handleUserPrompt(input: ProviderUserPromptInput): Promise<void> {
+    if (input.transcriptPath) this.deps.noteTranscriptPath(input.transcriptPath);
+    if (!this.deps.currentTurnId()) {
+      const turnId = input.promptId ?? crypto.randomUUID();
+      this.deps.setTurnId(turnId);
+      this.turnOpener.noteTurnStarted(turnId);
+      this.deps.setTurnStartedAt(Date.now());
+    }
+    const text = input.prompt.trim();
+    this.deps.notePrompt(text, input.firedAt);
+    if (text && !this.deps.isRunnerInjectedPrompt(text)) {
+      this.deps.sessionLog(`prompt echoed from terminal (${text.length} chars)`);
+      await this.deps.publishSessionEvent({
+        from: "user",
+        to: this.deps.agentId,
+        body: text,
+        session: { type: "prompt", origin: "terminal", turnId: this.deps.currentTurnId() },
+      });
+    } else if (text) {
+      this.deps.sessionDebug("user-prompt hook: skipped echo (runner-injected)");
+    }
+    await this.deps.adapter.handleUserPrompt?.(input, this.sessionTurnContext());
+    // #2664 — a late UserPromptSubmit hook is what releases an unconfirmed Claude submit.
+    if (this.deps.deliverySubmitHold()) this.deps.tryRecoverProviderSubmitHold(false);
+  }
+
+  // A provider lifecycle hook reported a session boundary
+  // → control server). Normalize the raw provider reason to a SessionDestroyReason and run
+  // the same pre-destroy seam the bus commands use. `clear`/`compact` continue the session;
+  // anything else (logout, prompt_input_exit, other) is a real termination.
+  async handleSessionBoundary(input: { reason?: string; transcriptPath?: string }): Promise<void> {
+    // Reason mapping is fail-safe-toward-termination: only the two known session-
+    // CONTINUING reasons are special-cased; everything else (logout, prompt_input_exit,
+    // other, AND any future reason) maps to "shutdown" → full pre-destroy capture.
+    // If a provider adds a new benign/continuing boundary reason, add it here. Until
+    // then it will trigger a harmless but wasteful full context capture on a session
+    // that isn't actually ending.
+    const reason = input.reason === "compact" ? "compact"
+      : input.reason === "clear" ? "clear"
+      : "shutdown";
+    await this.runPreSessionDestroy(reason, { transcriptPath: input.transcriptPath });
+    // clear/compact CONTINUE the session — the finalizing window is transient. The bus-command
+    // path (handleCommand) restores the addressable status in its finally; the hook path has no
+    // such teardown, so without this the dashboard stays stuck on "wrapping up — messaging
+    // paused" with the composer disabled forever. Only restore if we're still in the exact
+    // finalizing state we published — a concurrent bus command (kill/restart/shutdown) may have
+    // transitioned lifecycleAction since, and that must win. "shutdown" reasons end the session,
+    // so their finalizing state is superseded by going offline; leave it be.
+    if ((reason === "clear" || reason === "compact") && this.deps.lifecycleAction() === `finalizing-${reason}` && !this.deps.isStopped()) {
+      this.deps.setLifecycleAction(undefined);
+      this.deps.publishStatus();
+    }
+  }
+
+  // The pre-session-destroy seam (#183): the single place end-of-session work runs before
+  // an invasive transition (compact/clear/restart/shutdown/kill). Best-effort and
+  // time-boxed so it never hangs teardown; concurrent calls for the same teardown coalesce
+  // (a shutdown bus command and the SessionEnd hook can both fire). During the window the
+  // agent is published non-addressable so the operator sees "wrapping up", not "busy".
+  runPreSessionDestroy(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    const providerSessionId = this.deps.providerSessionId();
+    let record = this.preDestroyRun?.providerSessionId === providerSessionId ? this.preDestroyRun : undefined;
+    if (!record) {
+      const capture = (async () => {
+        try {
+          this.publishFinalizing(reason);
+          await Promise.race([
+            Promise.all([
+              this.deps.captureContextRatio(reason, opts),
+              this.deps.captureContinuationArchive(reason, opts),
+              // #2491 review MED-2 — prefer the already-tracked lastTranscriptPath (what the
+              // capture instance's byte-offset watermark is actually keyed to) over the hook-
+              // supplied opts.transcriptPath: a mismatch resets the watermark to 0 and re-reads
+              // + re-posts the whole transcript serially (safe — dedupe-keyed — but wasteful).
+              // Fall back to the hook-supplied path only when no capture has tracked one yet.
+              this.deps.settleTerminalTokenUsage(this.deps.lastTranscriptPath() ?? opts?.transcriptPath),
+            ]).then(() => undefined),
+            new Promise<void>((resolve) => setTimeout(resolve, PRE_DESTROY_TIMEOUT_MS)),
+          ]);
+        } catch (error) {
+          this.deps.sessionLog(`pre-destroy capture failed: ${errMessage(error)}`);
+        }
+      })();
+      const createdRecord: NonNullable<typeof this.preDestroyRun> = this.preDestroyRun = { providerSessionId, capture };
+      record = createdRecord;
+      // Compact/clear continue this incarnation and delimit a fresh capture segment. Restart
+      // retains the capture until spawnProvider changes incarnation so a later SessionEnd hook
+      // coalesces instead of repeating the full transcript/archive pass.
+      if (reason === "compact" || reason === "clear") {
+        void capture.finally(() => { if (this.preDestroyRun === createdRecord && !createdRecord.exitFlush) this.preDestroyRun = undefined; });
+      }
+    }
+    if (!reasonExitsRunner(reason)) return record.capture;
+    // Exit flushing is a separate once-per-incarnation obligation from capture. A shutdown hook
+    // coalesced onto a retained restart capture must still flush both durable outboxes (#1139),
+    // without repeating the expensive capture itself.
+    record.exitFlush ??= record.capture.then(async () => {
+      try {
+        const [delivered, sessionDelivered] = await Promise.all([this.deps.flushOutbox(OUTBOX_FLUSH_TIMEOUT_MS), this.deps.flushSessionEvents(OUTBOX_FLUSH_TIMEOUT_MS)]);
+        if (!delivered || !sessionDelivered) this.deps.sessionLog(`teardown outbox flush incomplete before ${reason}`);
+      } catch (error) {
+        this.deps.sessionLog(`teardown outbox flush failed: ${errMessage(error)}`);
+      }
+    });
+    return record.exitFlush;
+  }
+
+  // Publish the transient pre-destroy state: a non-offline status with ready:false (so the
+  // agent drops out of isAgentOnline fan-out targeting without going "offline") plus a
+  // finalizing-<reason> lifecycleAction the dashboard renders as "wrapping up" with the
+  // composer disabled.
+  private publishFinalizing(reason: SessionDestroyReason): void {
+    // A SessionEnd hook may arrive while runner-owned teardown is already in flight. It still
+    // participates in the coalesced capture above, but cannot replace the runner's lifecycle pill.
+    if (this.deps.terminalStatusLatched()) return;
+    const lifecycleAction = `finalizing-${reason}` as const;
+    const lifecycleActionAt = Date.now();
+    if (this.deps.publishRunnerStatus({ agentStatus: "busy", ready: false, meta: { lifecycleAction, lifecycleActionAt } })) {
+      this.deps.noteFinalizing(lifecycleAction, lifecycleActionAt);
+    }
+  }
+
+}

package/src/api-budget-accounting.ts

@@ -0,0 +1,91 @@
+import { relayEnv } from "@humwick/sdk/env";
+import { RELAY_TOKEN_HEADER, resendOnRotatedToken, type ApiBudgetId, type ApiBudgetDecision, type ApiBudgetReservation, type ApiBudgetTokenUsage } from "@humwick/sdk";
+import type { RunnerSpawnConfig } from "./adapter";
+import { ProviderSubmitFailure } from "./provider-submit-failure";
+
+/** One reservation/report/retry/settlement path for every metered adapter. */
+export class ApiBudgetAccounting {
+  reservation?: ApiBudgetReservation;
+  costMicroUsd = 0;
+  pending: Promise<void> = Promise.resolve();
+  settlement?: Promise<void>;
+  private readonly usage = new Map<string, ApiBudgetTokenUsage>();
+
+  constructor(readonly budgetId: ApiBudgetId,
+    private readonly request: (action: "reserve" | "report", body: Record<string, unknown>) => Promise<ApiBudgetDecision>,
+    private readonly adopted: (reservation: ApiBudgetReservation) => void = () => {}) {}
+
+  async reserve(sessionId: string, endedSession?: {sessionId: string; costMicroUsd: number}): Promise<ApiBudgetDecision> {
+    const decision = await this.request("reserve", { sessionId, ...(endedSession ? {endedSession} : {}) });
+    if (!decision.allowed || !decision.reservation) throw new ProviderSubmitFailure(`API admission refused: ${decision.reason ?? "invalid reservation"}`, false);
+    this.reservation = decision.reservation;
+    this.costMicroUsd = 0;
+    this.usage.clear();
+    this.pending = Promise.resolve();
+    this.settlement = undefined;
+    return decision;
+  }
+
+  observe(record: ApiBudgetTokenUsage): void {
+    const prior = this.usage.get(record.dedupeKey);
+    if (!prior || record.createdAt >= prior.createdAt) this.usage.set(record.dedupeKey, record);
+  }
+
+  async report(body: Record<string, unknown> = {}): Promise<ApiBudgetDecision> {
+    if (!this.reservation) throw new ProviderSubmitFailure("API reservation unavailable", false);
+    const records = [...this.usage.values()];
+    let decision!: ApiBudgetDecision;
+    for (let offset = 0; offset === 0 || offset < records.length; offset += 200) {
+      const batch = records.slice(offset, offset + 200);
+      decision = await this.request("report", { sessionId: this.reservation.sessionId,
+        ...(this.budgetId === "openai-api" ? { usage: batch } : { costMicroUsd: this.costMicroUsd }), ...body,
+        ...(body.settle && offset + 200 < records.length ? { settle: false } : {}) });
+      for (const record of batch) if (this.usage.get(record.dedupeKey) === record) this.usage.delete(record.dedupeKey);
+      if (decision.reservation?.sessionId === this.reservation.sessionId) {
+        this.reservation = decision.reservation;
+        this.costMicroUsd = Math.max(this.costMicroUsd, decision.reservation.costMicroUsd);
+        this.adopted(decision.reservation);
+      }
+    }
+    return decision;
+  }
+
+  queue(report: () => Promise<void>, failed: (error: unknown) => void): void {
+    this.pending = this.pending.then(report).catch(failed);
+  }
+
+  async settle(): Promise<void> {
+    await this.pending;
+    if (!this.reservation) return;
+    this.settlement ??= this.report({ settle: true }).then(() => {});
+    await this.settlement;
+  }
+
+  async transport(config: RunnerSpawnConfig, action: "reserve" | "report", body: Record<string, unknown>): Promise<ApiBudgetDecision> {
+    let status: number | undefined;
+    try {
+      const response = await resendOnRotatedToken(() => config.getRelayToken?.() ?? relayEnv(config.env, "AGENT_RELAY_TOKEN"), (token) => fetch(`${config.relayUrl}/api/agents/${encodeURIComponent(config.agentId)}/api-budget/${action}`, {
+        method: "POST", headers: { "content-type": "application/json", ...(token ? { [RELAY_TOKEN_HEADER]: token } : {}) },
+        body: JSON.stringify(this.budgetId === "claude-api" ? body : { ...body, budgetId: this.budgetId }), signal: AbortSignal.timeout(3_000),
+      })).catch(error => { throw new ProviderSubmitFailure("API budget transport unavailable", true, error); });
+      status = response.status;
+      if (!response.ok) throw new ProviderSubmitFailure(`API budget RPC failed (${status})`, status >= 500 || status === 429);
+      const result = await response.json().catch(error => {
+        throw new ProviderSubmitFailure("API budget response unreadable", !(error instanceof SyntaxError), error);
+      }) as ApiBudgetDecision;
+      if (!result || typeof result.allowed !== "boolean") throw new ProviderSubmitFailure("Invalid API budget decision", false);
+      return result;
+    } catch (error) {
+      // Never log response bodies, URLs, tokens or arbitrary transport error messages.
+      const cause = error instanceof ProviderSubmitFailure ? error.cause : error;
+      const name = cause instanceof Error && ["TimeoutError", "AbortError", "TypeError", "SyntaxError"].includes(cause.name) ? cause.name : "unknown";
+      console.error(`[api budget] ${JSON.stringify({ action, status: status ?? null, cause: name,
+        failure: error instanceof ProviderSubmitFailure ? error.message : "Invalid budget response" })}`);
+      throw error;
+    }
+  }
+}
+
+export function isTransientBudgetFailure(error: unknown): boolean {
+  return error instanceof ProviderSubmitFailure && error.retrySafe;
+}

package/src/area-memory.ts

@@ -0,0 +1,255 @@
+// #3411 — the runner's half of on-touch area memory (epic #3406). Every file a normalized tool event
+// names is matched to the repo's path areas (`.agent-relay/areas.json`); an area's first touch in a
+// context generation is reported to POST /api/agents/:id/area-entered (#3410), which selects the
+// memories. Claude returns them through PostToolUse; other providers use `agent.injectContext`.
+
+import { relative, sep } from "node:path";
+import { errMessage, PROJECT_FETCH_TIMEOUT_MS, type AreaEnteredInput, type AreaEnteredResult, type ProjectGit, type HumwickHttpClient } from "@humwick/sdk";
+import { AREAS_FILE, compileAreaMatcher, readAreasAtDefaultBranch, type AreaDefinition } from "@humwick/sdk/areas";
+import type { ProviderAdapter, ProviderSessionEvent } from "./adapter";
+import type { ControlServerOptions } from "./control-server";
+
+/** The `agent.injectContext` reason the server gives an area block. */
+export const AREA_MEMORY_REASON = "memory-area";
+/** The server refuses a longer `exclude` (AREA_EXCLUDE_MAX in src/memory-area-injection.ts). */
+const AREA_EXCLUDE_MAX = 200;
+/** One report plus two retries per area per generation. */
+const AREA_REPORT_ATTEMPTS = 3;
+/** Paths touched while the areas load; past this, later ones wait for the next touch. */
+const MAX_PENDING_PATHS = 200;
+const GIT_READ_TIMEOUT_MS = 5_000;
+
+export interface AreaMatcher {
+  repoRoot: string;
+  match(absPath: string): string[];
+  definitions?: AreaDefinition[];
+}
+
+export type AreasLookup = { matcher: AreaMatcher } | { off: string };
+
+/** Bounded git in the agent's checkout, for the SDK's default-branch reader. */
+function checkoutGit(cwd: string): ProjectGit {
+  return async (args, options) => {
+    const proc = Bun.spawn({
+      cmd: ["git", "-C", cwd, ...args],
+      stdin: options?.input === undefined ? "ignore" : new TextEncoder().encode(options.input),
+      stdout: "pipe",
+      stderr: "pipe",
+      timeout: options?.network ? PROJECT_FETCH_TIMEOUT_MS : GIT_READ_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+    });
+    const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text(), proc.exited]);
+    return { ok: proc.exitCode === 0, stdout, stderr, ...(proc.signalCode ? { unavailable: true } : {}) };
+  };
+}
+
+/** Never throws: the areas.json on the checkout's default branch, read through the same SDK reader
+ *  the relay uses (#3635), so a worktree older than the file still tracks its areas. */
+export async function loadAreas(cwd: string): Promise<AreasLookup> {
+  try {
+    const git = checkoutGit(cwd);
+    const top = await git(["rev-parse", "--show-toplevel"]);
+    if (!top.ok || !top.stdout.trim()) return { off: "not a git checkout" };
+    const read = await readAreasAtDefaultBranch(git);
+    if (read.status === "absent") return { off: `no ${AREAS_FILE} at ${read.ref}` };
+    if (read.status === "invalid") return { off: `${AREAS_FILE} at ${read.ref} is invalid: ${read.error}` };
+    const repoRoot = top.stdout.trim();
+    return { matcher: { repoRoot, definitions: read.config.areas, match: compileAreaMatcher(read.config, repoRoot) } };
+  } catch (error) {
+    return { off: `${AREAS_FILE} unreadable: ${errMessage(error)}` };
+  }
+}
+
+export interface AreaMemoryDeps {
+  agentId(): string;
+  cwd(): string;
+  providerSessionId(): string;
+  http(): Pick<HumwickHttpClient, "request">;
+  log(message: string): void;
+}
+
+export class AreaMemoryTracker {
+  private generation = 0;
+  private readonly servedAreas = new Set<string>();
+  private readonly servedEntryIds = new Set<string>();
+  private readonly failedReports = new Map<string, number>();
+  /** This generation's areas, read from the default branch (#3635); unset until loaded. */
+  private lookup?: AreasLookup;
+  /** The generation a load runs for. */
+  private loadingFor?: number;
+  private pending: string[] = [];
+  private loading?: Promise<void>;
+  private toolHook = false;
+  private hookTail: Promise<unknown> = Promise.resolve();
+
+  constructor(private readonly deps: AreaMemoryDeps) {}
+
+  /** Report the first touch of each area these events name. Synchronous; the POSTs run detached. */
+  noteToolPaths(events: readonly ProviderSessionEvent[]): void {
+    if (this.toolHook) return;
+    try {
+      for (const event of events) {
+        if (event.type !== "tool" || !event.paths?.length) continue;
+        for (const path of event.paths) this.touch(path);
+      }
+    } catch (error) {
+      this.deps.log(`area memory: tool paths not matched: ${errMessage(error)}`);
+    }
+  }
+
+  /** Claude's hook owns file touches; transcript notifications must not claim them first (#3646). */
+  enableToolHook(): void { this.toolHook = true; this.prepare(); }
+
+  /** Warm the default-branch snapshot while the provider starts, outside the hook budget. */
+  prepare(): void { if (!this.lookup) this.queue(); }
+
+  controlHooks(adapter: Pick<ProviderAdapter, "toolHookPaths">, onHookCheck: NonNullable<ControlServerOptions["onHookCheck"]>): Pick<ControlServerOptions, "onHookCheck" | "onToolUse"> {
+    this.prepare();
+    return {
+      onHookCheck: (input) => { if (adapter.toolHookPaths) this.enableToolHook(); onHookCheck(input); },
+      onToolUse: (input, signal) => { const paths = adapter.toolHookPaths?.(input); return paths?.length ? this.enterFromToolHook(paths, signal) : Promise.resolve(""); },
+    };
+  }
+
+  async enterFromToolHook(paths: readonly string[], signal: AbortSignal): Promise<string> {
+    const generation = this.generation;
+    const aborted = Promise.withResolvers<string>();
+    const onAbort = () => aborted.reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) onAbort();
+    // Parallel tool results share exclusions, so an overlapping entry appears only once.
+    const work = this.hookTail.then(async () => {
+      signal.throwIfAborted();
+      this.prepare();
+      await Promise.race([this.loading, aborted.promise]);
+      signal.throwIfAborted();
+      if (generation !== this.generation || !this.lookup || !("matcher" in this.lookup)) return "";
+      const matcher = this.lookup.matcher;
+      const blocks: string[] = [];
+      const entryIds: string[] = [];
+      const claimed: string[] = [];
+      let committed = false;
+      try {
+        for (const path of paths) for (const area of matcher.match(path)) {
+          signal.throwIfAborted();
+          if (generation !== this.generation) return "";
+          if (this.servedAreas.has(area)) continue;
+          const definition = matcher.definitions?.find((item) => item.name === area);
+          if (!definition) continue;
+          this.servedAreas.add(area);
+          claimed.push(area);
+          try {
+            const body = this.body(area, matcher, path, generation);
+            const result = await this.report({ ...body, exclude: [...this.servedEntryIds, ...entryIds].slice(-AREA_EXCLUDE_MAX), inline: definition }, signal);
+            signal.throwIfAborted();
+            if (generation !== this.generation) return "";
+            if (result?.content) {
+              blocks.push(result.content);
+              entryIds.push(...result.entryIds);
+            }
+          } catch (error) {
+            this.reportFailed(area, generation, error);
+            throw error;
+          }
+        }
+        for (const id of entryIds) this.servedEntryIds.add(id);
+        committed = true;
+        return blocks.join("\n\n");
+      } finally {
+        if (!committed && generation === this.generation) {
+          for (const area of claimed) if ((this.failedReports.get(area) ?? 0) < AREA_REPORT_ATTEMPTS) this.servedAreas.delete(area);
+        }
+      }
+    });
+    this.hookTail = work.catch(() => {});
+    try { return await Promise.race([work, aborted.promise]); }
+    catch (error) {
+      this.deps.log(`area memory: PostToolUse did not return context: ${errMessage(error)}`);
+      return "";
+    } finally { signal.removeEventListener("abort", onAbort); }
+  }
+
+  /** True (and logged) for a `memory-area` inject queued for an earlier generation: a reset happened in flight. */
+  isStaleInjection(params: Record<string, unknown>): boolean {
+    if (params.reason !== AREA_MEMORY_REASON || params.generation === this.generation) return false;
+    this.deps.log(`context injection (${AREA_MEMORY_REASON}) skipped: queued for generation ${String(params.generation)}, now ${this.generation}; the new generation reports its areas again`);
+    return true;
+  }
+
+  /** A `memory-area` inject reached (or durably parked for) the provider: later reports exclude its ids. */
+  noteInjected(params: Record<string, unknown>, memoryIds: readonly string[]): void {
+    if (params.reason !== AREA_MEMORY_REASON || params.generation !== this.generation) return;
+    for (const id of memoryIds) this.servedEntryIds.add(id);
+  }
+
+  /** A new provider context generation: every area is unentered and nothing is served. */
+  resetGeneration(): void {
+    this.generation += 1;
+    this.servedAreas.clear();
+    this.servedEntryIds.clear();
+    this.failedReports.clear();
+    // The next touch reads the areas again, so a change landed on the default branch takes effect.
+    this.lookup = undefined;
+    this.pending = [];
+  }
+
+  private touch(absPath: string): void {
+    const lookup = this.lookup;
+    if (!lookup) return this.queue(absPath);
+    if ("matcher" in lookup) for (const area of lookup.matcher.match(absPath)) this.enter(area, lookup.matcher, absPath);
+  }
+
+  /** Hold a path until this generation's areas load, starting the load once. */
+  private queue(absPath?: string): void {
+    if (absPath && this.pending.length < MAX_PENDING_PATHS) this.pending.push(absPath);
+    if (this.loadingFor === this.generation) return;
+    const generation = this.loadingFor = this.generation;
+    this.loading = loadAreas(this.deps.cwd()).then((lookup) => {
+      // A reset since then dropped these paths; its first touch loads again.
+      if (generation !== this.generation) return;
+      this.loadingFor = undefined;
+      this.lookup = lookup;
+      if ("off" in lookup) this.deps.log(`area memory off: ${lookup.off}`);
+      for (const path of this.pending.splice(0)) this.touch(path);
+    }).catch((error) => this.deps.log(`area memory: tool paths not matched: ${errMessage(error)}`));
+  }
+
+  private enter(area: string, matcher: AreaMatcher, absPath: string): void {
+    if (this.servedAreas.has(area)) return;
+    // Added before the POST so a second touch while it runs does not report again.
+    this.servedAreas.add(area);
+    const generation = this.generation;
+    const body = this.body(area, matcher, absPath, generation);
+    void this.report(body).catch((error) => this.reportFailed(area, generation, error));
+  }
+
+  private body(area: string, matcher: AreaMatcher, absPath: string, generation: number): AreaEnteredInput {
+    return {
+      area,
+      relPath: relative(matcher.repoRoot, absPath).split(sep).join("/"),
+      providerSessionId: this.deps.providerSessionId(),
+      generation,
+      exclude: [...this.servedEntryIds].slice(-AREA_EXCLUDE_MAX),
+    };
+  }
+
+  private async report(body: AreaEnteredInput, signal?: AbortSignal): Promise<AreaEnteredResult | undefined> {
+    const response = await this.deps.http().request("POST", `/api/agents/${encodeURIComponent(this.deps.agentId())}/area-entered`, body, { signal });
+    const text = await response.text().catch(() => "");
+    if (!response.ok) throw new Error(`HTTP ${response.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+    return body.inline ? JSON.parse(text) as AreaEnteredResult : undefined;
+  }
+
+  private reportFailed(area: string, generation: number, error: unknown): void {
+    // A reset since the POST started already reopened every area.
+    if (generation !== this.generation) return;
+    const failures = (this.failedReports.get(area) ?? 0) + 1;
+    this.failedReports.set(area, failures);
+    if (failures >= AREA_REPORT_ATTEMPTS) {
+      this.deps.log(`area memory: entry of ${area} not reported after ${failures} attempts; giving up until the next reset: ${errMessage(error)}`);
+      return;
+    }
+    this.servedAreas.delete(area);
+    this.deps.log(`area memory: entry of ${area} not reported (retrying on the next touch): ${errMessage(error)}`);
+  }
+}