@staix/agent-hub 0.28.0 → 0.29.0

package/src/cli/help.ts

@@ -88,7 +88,7 @@ const SECTIONS: [string, [usage: string, description: string][]][] = [
   ["Tasks and review", [
     ["ahub board import github --label <label> [--milestone <milestone>] [--repo <owner/repo>]", "person or configured conductor: read bounded open issues into deduplicated Backlog; never writes GitHub"],
     ["ahub board [state | --ready] [--columns] [--release <name> | --release-id <id>] [--handoffs] [--json] [--full] [--color=auto|always|never]", "the task board, one line per task at a terminal width; --full: whole titles and SDLC advice; --ready: proposed tasks with nothing left to wait for; --handoffs: what this project handed to other projects and the last state each reported"],
-    ["ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--needs-network] [--needs-worktree] [--backlog] [--detail <text>]", "put a task on the board; --needs-network keeps it away from a peer whose shell has none; --needs-worktree keeps it away from a sandboxed peer, which cannot create the task worktree; a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
+    ["ahub task propose [--class <c> | <class>] <title...> [--owner <peer>] [--path <p>]... [--after <id>]... [--urgent] [--needs-network] [--needs-worktree] [--backlog] [--detail <text>]", "put a task on the board; --needs-network keeps it away from a peer whose shell has none; --needs-worktree keeps it away from a sandboxed peer unless the hub can make the task worktree for it (it makes it, commits and pushes at done); a first word that names a class is taken as the class; while a task named by --after is not approved yet, --owner reserves the task for that peer, offered to it first once it is ready; otherwise --owner assigns it now"],
     ["ahub task handoff --project <root|id> [<class>] <title...> [--path <p>]... [--issue <n>] [--task <n>] [--detail <text>] [--json] [--color=auto|always|never]", "person only: register work that belongs to ANOTHER project that runs agent-hub on that project's board (an ownerless proposal its own roles take from there); the target must be registered and running, nothing is queued; a feature or behavior change first needs a spec issue there (--issue); its state changes show in ahub board --handoffs (an agent that hands off gets them as task messages)"],
     ["ahub backlog list [--json] [--full] [--color=auto|always|never] | add <class> <title...> | plan <id> <revision> <fields-json> <reason...> | pin <id> <revision> true|false <reason...> | undo <id> <revision> [--json] [--color=auto|always|never]", "person only: plan work with a reason; {} records a note-only revision, fields.sdlc sets backlog repo/issue identity and clears old spec acceptance; preserve pins/frozen scope and refuse stale edits; list is by rank (--json: raw listing)"],
     ["ahub release new <name> <goal> <order> | list | show <name> | plan <name> <revision> <dates-json> | activate|freeze|ship|drop <name> <revision> [--json] [--color=auto|always|never]", "person only, except show (any agent, public metadata): planned UTC millisecond dates and phased scope; ship records a time after approval, never tags or publishes"],

package/src/cli/output.ts

@@ -14,6 +14,7 @@ import type { SpecsStatus } from "../hub/specs-task.ts";
 
 export interface DoctorCheck { section: "Tools" | "Hub" | "Config" | "Models" | "Memory"; level: "ok" | "warn" | "fail" | "unknown"; name: string; detail: string }
 export interface StatusOutput {
+  controlWriteTiming?: { active: number; slowRequests: number; blockedLoopSamples: number; droppedActive: number; droppedRecent: number; droppedLogs: number; droppedSpans?: number; droppedMetadata?: number; expiredRequests?: number };
   specs?: SpecsStatus & { missingBlockHint?: boolean };
   queueBackpressure?: QueueBackpressureStatus;
   pendingRestart?: readonly { key: string; reason: string }[];
@@ -213,6 +214,10 @@ export function renderStatus(data: StatusOutput, columns?: number, now = Date.no
   if (data.roleInfo) data = { ...data, peers: Object.fromEntries(Object.entries(data.peers).map(([peer, value]) => [peer, { ...value, ...data.roleInfo?.[peer] }])) };
   const out = lines(`agent-hub${data.version ? ` ${data.version}` : ""}  pid ${data.pid ?? "unknown"}  control 127.0.0.1:${data.controlPort ?? "unknown"}`, columns, "info");
   if (data.cwd) out.push(...lines(data.cwd, columns));
+  const timing = data.controlWriteTiming;
+  if (full && timing && Object.values(timing).every(value => Number.isSafeInteger(value) && value >= 0)) {
+    out.push(...lines(`control writes: active ${timing.active}, slow ${timing.slowRequests}, loop delays ${timing.blockedLoopSamples}, dropped ${timing.droppedActive + timing.droppedLogs + (timing.droppedSpans ?? 0) + (timing.droppedMetadata ?? 0)}, expired ${timing.expiredRequests ?? 0}; timings in hub.log`, columns, timing.slowRequests || timing.blockedLoopSamples ? "attention" : undefined));
+  }
   const specs = data.specs;
   if (specs && [specs.specCount, specs.documents, specs.errors, specs.stale].every(value => Number.isSafeInteger(value) && value >= 0)
     && (specs.specCount > 0 || specs.documents > 0 || specs.errors > 0)) {

package/src/cli/recovery-package.ts

@@ -127,6 +127,9 @@ export function verifyRecoveryTarget(kind: "restart" | "upgrade", root: string,
   return verifyPackage(root, version, recoveryPackageOptions(kind, root));
 }
 
+/** #1120: the documentation checker that `ahub sdlc authorize-release` and release readiness spawn. A capture without it can never record release consent. */
+export const RELEASE_CHECKER = "scripts/check-docs.mjs";
+// ponytail: the checker is copied and kept by prune, but is not in packageDigest. Widening the digest would make every release staged before this change refuse as "cached release changed". Ceiling: a tampered checker in a capture is not detected by the digest. Upgrade path: fold it into packageDigest with a digest-version bump once no pre-#1120 capture or cached release remains.
 const RUNTIME_ASSETS = ["src", "plugins", "templates", ".claude-plugin", "package.json", "README.md", "LICENSE", "CHANGELOG.md"] as const;
 function runtimeDirectory(directory: string): void {
   let info;
@@ -159,6 +162,12 @@ function preserveRuntimeAssets(sourceRoot: string, destination: string, expected
   mkdirSync(temporary, { mode: 0o700 });
   try {
     for (const name of RUNTIME_ASSETS) cpSync(join(sourceRoot, name), join(temporary, name), { recursive: true, dereference: false });
+    // Absent in a source that predates the checker (a registry package before #1120 ships it): the capture then reports the checker as unavailable, never a stale document.
+    if (existsSync(join(sourceRoot, RELEASE_CHECKER))) {
+      if (!lstatSync(join(sourceRoot, RELEASE_CHECKER)).isFile()) throw new Error(`${RELEASE_CHECKER} must be a regular file to be preserved in a runtime capture; replace it with a regular file`);
+      mkdirSync(join(temporary, dirname(RELEASE_CHECKER)), { recursive: true });
+      cpSync(join(sourceRoot, RELEASE_CHECKER), join(temporary, RELEASE_CHECKER), { dereference: false });
+    }
     preserveRuntimeDependencies(sourceRoot, temporary);
     if (digest(temporary, true) !== expectedDigest || digest(sourceRoot) !== expectedDigest)
       throw new Error("source package changed while being preserved");

package/src/hub/board.ts

@@ -11,6 +11,7 @@ import type { ReviewerPoolReason } from "./reviewer-pool.ts";
 import type { GitHubSource } from "./github-import.ts";
 import type { Database } from "./db-schema.ts";
 import { openHubDatabase, advanceHubDbSchema } from "./db-schema.ts";
+import { controlWriteSpan } from "./control-write-trace.ts";
 import { planningPatch, type PlanningFields, type Release, type ReleaseState } from "./planning.ts";
 import { HUB, USER, type PeerId } from "./envelope.ts";
 import type { SweepRecord } from "./task-sweep.ts";
@@ -431,11 +432,11 @@ export class Board {
 
   /** Keep the generation and business write atomic without changing Bun's reported row count. */
   private taskWrite<T extends { changes: number }>(write: () => T): T {
-    return this.db.transaction(() => {
+    return controlWriteSpan("board-write", () => this.db.transaction(() => {
       const result = { ...write() };
       if (result.changes) this.db.run("UPDATE board_status_revision SET revision=revision+1 WHERE id=1");
       return result;
-    })();
+    })());
   }
 
   statusRevision(): number {

package/src/hub/control-client.ts

@@ -4,6 +4,13 @@ import { projectContext } from "./project.ts";
 import { newToolRequestId, TOOL_WRITE_FEATURE, toolWriteOperation, toolWriteUnknownReply, toolWriteRefusedReply } from "./tool-request.ts";
 import { externalAdapterMetadata, externalInstanceCatalog, type ExternalInstanceCatalog, type ExternalAdapterMetadata } from "../adapters/external-metadata.ts";
 import { negotiateProtocol, protocolWindow, type ProtocolWindow } from "./protocol-window.ts";
+import { ControlWriteTelemetry, controlWriteMetadata, controlWriteSpan } from "./control-write-trace.ts";
+
+// The client has no authoritative task privacy view. Keep kind/timing only, never its args or task id.
+const clientWriteTelemetry = new ControlWriteTelemetry({ emit: line => {
+  if (process.env.AHUB_CONTROL_WRITE_TIMING === "1") console.error(`[agent-hub] ${line}`);
+} });
+const publicClientTiming = () => true;
 
 export function stateDirFor(cwd: string): string {
   return projectContext(cwd).stateDir;
@@ -221,6 +228,14 @@ export class ControlClient {
 
   /** `timeoutMs`: for calls a person waits on. The hub has its own budget; this one only makes sure the CLI never hangs. */
   request(msg: Record<string, unknown>, timeoutMs = 30_000, signal?: AbortSignal): Promise<any> {
+    if (process.env.AHUB_CONTROL_WRITE_TIMING !== "1") return this.requestBody(msg, timeoutMs, signal);
+    const metadata = controlWriteMetadata(msg);
+    if (!metadata) return this.requestBody(msg, timeoutMs, signal);
+    return clientWriteTelemetry.run({ kind: metadata.kind }, publicClientTiming, () => controlWriteSpan("client-wait", () =>
+      this.requestBody(msg, timeoutMs, signal)));
+  }
+
+  private requestBody(msg: Record<string, unknown>, timeoutMs: number, signal?: AbortSignal): Promise<any> {
     if (this.ws.readyState !== WebSocket.OPEN || this.closing && msg.t !== "request_cancel") return Promise.resolve({ ok: false, error: "hub connection is not open" });
     const invocation = msg.t === "task" && msg.op === "hub_invoke";
     const operation = toolWriteOperation(msg), write = operation !== undefined;
@@ -266,7 +281,7 @@ export class ControlClient {
       signal?.addEventListener("abort", aborted, { once: true });
       if (signal?.aborted) { aborted(); return; }
       timer = timeoutMs ? setTimeout(() => abandon(`no answer from the hub within ${Math.round(timeoutMs / 1000)} s`), timeoutMs) : undefined;
-      try { this.ws.send(JSON.stringify({ ...wire, rid })); }
+      try { controlWriteSpan("client-send", () => this.ws.send(JSON.stringify({ ...wire, rid }))); }
       catch { abandon("hub request could not be sent"); }
     });
   }

package/src/hub/control-write-trace.ts

@@ -0,0 +1,409 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+export const CONTROL_WRITE_KINDS = [
+  "hub_task_propose", "hub_review", "hub_task_accept", "hub_task_done", "hub_task_decline", "hub_task_cancel",
+  "hub_task_assign", "task_assign", "task_assign_checked", "task_unassign", "hub_delivery_done", "background",
+] as const;
+export type ControlWriteKind = typeof CONTROL_WRITE_KINDS[number];
+
+export const CONTROL_WRITE_PHASES = [
+  "client-send", "client-wait", "daemon-dispatch", "daemon-reply",
+  "board-write", "queue-hook", "status-hook", "memory", "external", "snapshot",
+] as const;
+export type ControlWritePhase = typeof CONTROL_WRITE_PHASES[number];
+
+export const CONTROL_WRITE_SLOW_MS = 1_000;
+export const CONTROL_WRITE_LOOP_DELAY_MS = 250;
+export const CONTROL_WRITE_SAMPLE_MS = 100;
+export const CONTROL_WRITE_MAX_LINE_BYTES = 2_048;
+export const CONTROL_WRITE_MAX_DURATION_MS = 86_400_000;
+export const CONTROL_WRITE_REQUEST_MAX_AGE_MS = 5 * 60_000;
+
+const MAX_ACTIVE_REQUESTS = 128;
+const MAX_ACTIVE_SPANS = 256;
+const MAX_RECENT_SPANS = 512;
+const MAX_LOOP_SPANS = 8;
+const MIN_SYNC_PREFIX_MS = 10;
+const MAX_EMITS_PER_MINUTE = 60;
+const RATE_LIMIT_MS = 1_000;
+const RATE_KEYS = ["slow", "loop"] as const;
+
+export interface ControlWriteMetadata { kind: ControlWriteKind; task?: number }
+export type ControlWritePrivacy = () => boolean;
+export type ControlWriteSink = (line: string) => void;
+export interface ControlWriteTelemetryOptions {
+  emit: ControlWriteSink;
+  now?: () => number;
+  maxActiveRequests?: number;
+  maxActiveSpans?: number;
+  maxRecentSpans?: number;
+  rateLimitMs?: number;
+}
+
+interface PhaseTotal { phase: ControlWritePhase; durationMs: number }
+interface RequestTrace {
+  telemetry: ControlWriteTelemetry;
+  metadata: ControlWriteMetadata;
+  privacyCurrent: ControlWritePrivacy;
+  logPrivacy: ControlWritePrivacy;
+  startedAt: number;
+  phases: Map<ControlWritePhase, number>;
+  phaseOrder: ControlWritePhase[];
+  settled: boolean;
+  privacySuppressed: boolean;
+}
+interface SpanTrace {
+  id?: number;
+  request: RequestTrace;
+  phase: ControlWritePhase;
+  startedAt: number;
+  async: boolean;
+  finished: boolean;
+  prefixRecorded: boolean;
+}
+interface SpanInterval {
+  kind: ControlWriteKind;
+  task?: number;
+  phase: ControlWritePhase;
+  startedAt: number;
+  endedAt?: number;
+  async: boolean;
+  privacyCurrent: ControlWritePrivacy;
+}
+
+const currentTrace = new AsyncLocalStorage<RequestTrace>();
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function validTaskId(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+function numericTaskId(value: unknown): number | undefined {
+  return validTaskId(value) ? value : undefined;
+}
+
+function ownValue(value: Record<string, unknown>, key: string): unknown {
+  const descriptor = Object.getOwnPropertyDescriptor(value, key);
+  return descriptor && Object.hasOwn(descriptor, "value") ? descriptor.value : undefined;
+}
+
+const OPERATIONS: Readonly<Record<string, ControlWriteKind>> = {
+  hub_task_propose: "hub_task_propose", hub_review: "hub_review", hub_task_accept: "hub_task_accept",
+  hub_task_done: "hub_task_done", hub_task_decline: "hub_task_decline", hub_task_cancel: "hub_task_cancel",
+  hub_task_assign: "hub_task_assign", task_assign: "task_assign", task_assign_checked: "task_assign_checked", task_unassign: "task_unassign",
+};
+
+/** The control protocol contributes only a closed operation name and, when present, a positive task id. */
+export function controlWriteMetadata(message: unknown): ControlWriteMetadata | undefined {
+  if (!isObject(message)) return undefined;
+  try {
+    let kind: ControlWriteKind | undefined;
+    let args: Record<string, unknown> | undefined;
+    const type = ownValue(message, "t"), operation = ownValue(message, "op");
+    if (type === "delivery_complete") kind = "hub_delivery_done";
+    else if (type === "task" && typeof operation === "string") {
+      kind = Object.hasOwn(OPERATIONS, operation) ? OPERATIONS[operation] : undefined;
+      const rawArgs = ownValue(message, "args");
+      args = isObject(rawArgs) ? rawArgs : undefined;
+    }
+    if (!kind) return undefined;
+    const task = numericTaskId(args ? ownValue(args, "id") : undefined);
+    return task === undefined ? { kind } : { kind, task };
+  } catch { return undefined; }
+}
+
+function isPhase(value: string): value is ControlWritePhase {
+  return (CONTROL_WRITE_PHASES as readonly string[]).includes(value);
+}
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  try { return !!value && (typeof value === "object" || typeof value === "function") && typeof (value as { then?: unknown }).then === "function"; }
+  catch { return false; }
+}
+
+/** Add a bounded phase to the current request. With no request context, this is a no-op. */
+export function controlWriteSpan<T>(phase: ControlWritePhase, fn: () => T): T {
+  const request = currentTrace.getStore();
+  if (!request || request.settled || request.privacySuppressed || !isPhase(phase)) return fn();
+  const span = request.telemetry.beginSpan(request, phase);
+  let result: T;
+  try { result = fn(); }
+  catch (error) { request.telemetry.finishSpan(span); throw error; }
+  if (!isThenable(result)) { request.telemetry.finishSpan(span); return result; }
+  span.async = true;
+  request.telemetry.recordSyncPrefix(span);
+  return Promise.resolve(result).then(
+    value => { request.telemetry.finishSpan(span); return value; },
+    error => { request.telemetry.finishSpan(span); throw error; },
+  ) as T;
+}
+
+/** Bounded per-daemon control write and event-loop timing. Logs contain metadata, never request payloads. */
+export class ControlWriteTelemetry {
+  private readonly nowFn: () => number;
+  private readonly maxActiveRequests: number;
+  private readonly maxActiveSpans: number;
+  private readonly maxRecentSpans: number;
+  private readonly rateLimitMs: number;
+  private readonly requests = new Map<number, RequestTrace>();
+  private readonly spans = new Map<number, SpanTrace>();
+  private readonly recent: SpanInterval[] = [];
+  private readonly emitted: number[] = [];
+  private readonly lastEmit = new Map<typeof RATE_KEYS[number], number>();
+  private nextRequestId = 1;
+  private nextSpanId = 1;
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private nextSampleAt: number | undefined;
+  private lastNow = 0;
+  private stopped = false;
+  private completedRequests = 0;
+  private expiredRequests = 0;
+  private slowRequests = 0;
+  private blockedLoopSamples = 0;
+  private droppedActive = 0;
+  private droppedSpans = 0;
+  private droppedRecent = 0;
+  private droppedLogs = 0;
+  private droppedMetadata = 0;
+  private clockFailures = 0;
+
+  constructor(private readonly options: ControlWriteTelemetryOptions) {
+    this.nowFn = options.now ?? (() => performance.now());
+    this.maxActiveRequests = options.maxActiveRequests ?? MAX_ACTIVE_REQUESTS;
+    this.maxActiveSpans = options.maxActiveSpans ?? MAX_ACTIVE_SPANS;
+    this.maxRecentSpans = options.maxRecentSpans ?? MAX_RECENT_SPANS;
+    this.rateLimitMs = options.rateLimitMs ?? RATE_LIMIT_MS;
+    if (![this.maxActiveRequests, this.maxActiveSpans, this.maxRecentSpans].every(value => Number.isSafeInteger(value) && value > 0)
+      || !Number.isSafeInteger(this.rateLimitMs) || this.rateLimitMs < 0 || this.rateLimitMs > RATE_LIMIT_MS
+      || this.maxActiveRequests > MAX_ACTIVE_REQUESTS || this.maxActiveSpans > MAX_ACTIVE_SPANS || this.maxRecentSpans > MAX_RECENT_SPANS) throw new Error("invalid control write trace bounds");
+  }
+
+  /** Wrap a synchronous or asynchronous operation without changing its result or exception. */
+  run<T>(metadata: ControlWriteMetadata, privacyCurrent: ControlWritePrivacy, fn: () => T, inputPublic?: ControlWritePrivacy): T {
+    if (this.stopped) return fn();
+    const safeMetadata = this.safeMetadata(metadata);
+    if (!safeMetadata || typeof privacyCurrent !== "function") {
+      this.droppedMetadata++;
+      return fn();
+    }
+    const now = this.readNow();
+    this.expireRequests(now);
+    if (this.requests.size >= this.maxActiveRequests) { this.droppedActive++; return fn(); }
+    if (!this.privateNow(privacyCurrent)) return fn();
+    const inputVisible = !inputPublic || this.privateNow(inputPublic);
+    inputPublic = undefined; // The admission-only callback may carry raw input; never retain it in a trace.
+    if (!inputVisible) return fn();
+    const request: RequestTrace = {
+      telemetry: this, metadata: safeMetadata, privacyCurrent,
+      startedAt: now, phases: new Map(), phaseOrder: [], settled: false, privacySuppressed: false,
+      logPrivacy: () => false,
+    };
+    request.logPrivacy = () => !request.privacySuppressed && this.privateNow(request.privacyCurrent);
+    const id = this.nextRequestId++;
+    this.requests.set(id, request);
+    let result: T;
+    try { result = currentTrace.run(request, fn); }
+    catch (error) { this.finishRequest(id, request, "threw"); throw error; }
+    if (!isThenable(result)) { this.finishRequest(id, request, "returned"); return result; }
+    return Promise.resolve(result).then(
+      value => { this.finishRequest(id, request, "returned"); return value; },
+      error => { this.finishRequest(id, request, "threw"); throw error; },
+    ) as T;
+  }
+
+  /** Observe a daemon boundary; work outside a control request is labelled as background. */
+  observe<T>(phase: ControlWritePhase, privacyCurrent: ControlWritePrivacy, fn: () => T, inputPublic?: ControlWritePrivacy): T {
+    if (this.stopped) return fn();
+    const current = currentTrace.getStore();
+    if (current?.telemetry === this && !current.settled) {
+      if (current.privacySuppressed) return fn();
+      const inputVisible = this.privateNow(privacyCurrent) && (!inputPublic || this.privateNow(inputPublic));
+      inputPublic = undefined;
+      if (!inputVisible) current.privacySuppressed = true;
+      return controlWriteSpan(phase, fn);
+    }
+    return this.run({ kind: "background" }, privacyCurrent, () => controlWriteSpan(phase, fn), inputPublic);
+  }
+
+  /** Start one unref'd event-loop delay probe for the daemon. */
+  start(): void {
+    if (this.stopped || this.timer) return;
+    this.nextSampleAt = this.readNow() + CONTROL_WRITE_SAMPLE_MS;
+    this.timer = setInterval(() => this.sample(), CONTROL_WRITE_SAMPLE_MS);
+    this.timer.unref?.();
+  }
+
+  /** Stop the probe and suppress later diagnostics from this daemon instance. */
+  stop(): void {
+    this.stopped = true;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    this.nextSampleAt = undefined;
+  }
+
+  /** Deterministic probe seam used by tests; a missing cause remains explicitly unknown. */
+  sample(): void {
+    if (this.stopped) return;
+    const now = this.readNow(), expected = this.nextSampleAt ?? now;
+    this.expireRequests(now);
+    this.nextSampleAt = now + CONTROL_WRITE_SAMPLE_MS;
+    const delayMs = Math.max(0, now - expected);
+    if (delayMs < CONTROL_WRITE_LOOP_DELAY_MS) return;
+    this.blockedLoopSamples++;
+    const from = expected;
+    const observed: { kind: ControlWriteKind; task?: number; phase: ControlWritePhase; durationMs: number; open?: true; privacyCurrent: ControlWritePrivacy }[] = [];
+    for (const interval of this.recent) {
+      if (interval.async || interval.endedAt === undefined || interval.startedAt >= now || interval.endedAt < from) continue;
+      observed.push({ kind: interval.kind, ...(interval.task === undefined ? {} : { task: interval.task }), phase: interval.phase, durationMs: this.roundMs(interval.endedAt - interval.startedAt), privacyCurrent: interval.privacyCurrent });
+    }
+    for (const span of this.spans.values()) {
+      if (!span.async || span.startedAt >= now) continue;
+      observed.push({ kind: span.request.metadata.kind, ...(span.request.metadata.task === undefined ? {} : { task: span.request.metadata.task }), phase: span.phase, durationMs: this.roundMs(now - span.startedAt), open: true,
+        privacyCurrent: span.request.logPrivacy });
+    }
+    const unique = new Map<string, (typeof observed)[number]>();
+    for (const row of observed.sort((a, b) => b.durationMs - a.durationMs)) {
+      const key = `${row.kind}:${row.task ?? ""}:${row.phase}:${row.open === true}`;
+      if (!unique.has(key)) unique.set(key, row);
+    }
+    const selected = [...unique.values()].slice(0, MAX_LOOP_SPANS);
+    const spans = selected.map(({ kind, task, phase, durationMs, open }) => ({ kind, ...(task === undefined ? {} : { task }), phase, durationMs, ...(open ? { open: true as const } : {}) }));
+    const guards = [...new Set(selected.map(row => row.privacyCurrent))];
+    const attribution = selected.some(row => row.open !== true) ? "sync_overlap_observed" : selected.length ? "open_async_wait" : "unknown";
+    this.emit("loop", {
+      type: "control_write_loop_delay", delayMs: this.roundMs(delayMs), attribution, spans,
+    }, () => guards.every(guard => this.privateNow(guard)));
+  }
+
+  /** Flat numeric counters for the authenticated full-status projection. */
+  status(): Record<string, number> {
+    return {
+      active: this.requests.size,
+      activeSpans: this.spans.size,
+      completedRequests: this.completedRequests,
+      expiredRequests: this.expiredRequests,
+      slowRequests: this.slowRequests,
+      blockedLoopSamples: this.blockedLoopSamples,
+      recentSpans: this.recent.length,
+      droppedActive: this.droppedActive,
+      droppedSpans: this.droppedSpans,
+      droppedRecent: this.droppedRecent,
+      droppedLogs: this.droppedLogs,
+      droppedMetadata: this.droppedMetadata,
+      clockFailures: this.clockFailures,
+    };
+  }
+
+  beginSpan(request: RequestTrace, phase: ControlWritePhase): SpanTrace {
+    const span: SpanTrace = { request, phase, startedAt: this.readNow(), async: false, finished: false, prefixRecorded: false };
+    if (this.spans.size >= this.maxActiveSpans) { this.droppedSpans++; return span; }
+    span.id = this.nextSpanId++;
+    this.spans.set(span.id, span);
+    return span;
+  }
+
+  finishSpan(span: SpanTrace): void {
+    if (span.finished) return;
+    span.finished = true;
+    if (span.request.settled) return;
+    const endedAt = this.readNow();
+    if (span.id !== undefined && this.spans.get(span.id) === span) this.spans.delete(span.id);
+    const durationMs = Math.max(0, endedAt - span.startedAt);
+    const request = span.request;
+    const prior = request.phases.get(span.phase) ?? 0;
+    if (!request.phaseOrder.includes(span.phase)) request.phaseOrder.push(span.phase);
+    request.phases.set(span.phase, prior + durationMs);
+    if (!span.async && !span.prefixRecorded) this.rememberSyncInterval(span, endedAt);
+  }
+
+  /** Preserve a long synchronous prelude inside an async function for the delayed loop probe. */
+  recordSyncPrefix(span: SpanTrace): void {
+    if (span.finished || span.prefixRecorded || span.request.settled) return;
+    const endedAt = this.readNow();
+    if (endedAt - span.startedAt < MIN_SYNC_PREFIX_MS) return;
+    span.prefixRecorded = true;
+    this.rememberSyncInterval(span, endedAt);
+  }
+
+  private rememberSyncInterval(span: SpanTrace, endedAt: number): void {
+    const request = span.request;
+    this.recent.push({ kind: request.metadata.kind, ...(request.metadata.task === undefined ? {} : { task: request.metadata.task }), phase: span.phase, startedAt: span.startedAt, endedAt, async: false, privacyCurrent: request.logPrivacy });
+    while (this.recent.length > this.maxRecentSpans) { this.recent.shift(); this.droppedRecent++; }
+  }
+
+  private finishRequest(id: number, request: RequestTrace, outcome: "returned" | "threw"): void {
+    if (!this.requests.delete(id)) return;
+    request.settled = true;
+    for (const [spanId, span] of this.spans) if (span.request === request) this.spans.delete(spanId);
+    this.completedRequests++;
+    const durationMs = this.roundMs(this.readNow() - request.startedAt);
+    if (durationMs < CONTROL_WRITE_SLOW_MS) return;
+    this.slowRequests++;
+    const phases: PhaseTotal[] = request.phaseOrder.map(phase => ({ phase, durationMs: this.roundMs(request.phases.get(phase) ?? 0) }));
+    this.emit("slow", {
+      type: "control_write_slow", kind: request.metadata.kind, ...(request.metadata.task === undefined ? {} : { task: request.metadata.task }),
+      durationMs, outcome, phases: phases.slice(0, MAX_LOOP_SPANS), ...(phases.length > MAX_LOOP_SPANS ? { truncated: true } : {}),
+    }, request.logPrivacy);
+  }
+
+  /** Retire diagnostics only; the operation and its eventual result remain owned by the caller. */
+  private expireRequests(now: number): void {
+    for (const [id, request] of this.requests) {
+      if (now - request.startedAt < CONTROL_WRITE_REQUEST_MAX_AGE_MS) continue;
+      request.settled = true;
+      request.privacySuppressed = true; // Recent intervals must not attribute an expired request either.
+      this.requests.delete(id);
+      this.expiredRequests++;
+    }
+    for (const [id, span] of this.spans) if (span.request.settled) this.spans.delete(id);
+  }
+
+  private emit(key: typeof RATE_KEYS[number], value: Record<string, unknown>, privacyCurrent: ControlWritePrivacy): void {
+    if (this.stopped || !this.privateNow(privacyCurrent)) return;
+    const now = this.readNow(), last = this.lastEmit.get(key);
+    if (last !== undefined && now - last < this.rateLimitMs) { this.droppedLogs++; return; }
+    while (this.emitted.length && now - this.emitted[0]! >= 60_000) this.emitted.shift();
+    if (this.emitted.length >= MAX_EMITS_PER_MINUTE) { this.droppedLogs++; return; }
+    let line: string;
+    try { line = JSON.stringify(value); } catch { this.droppedLogs++; return; }
+    if (Buffer.byteLength(line) > CONTROL_WRITE_MAX_LINE_BYTES) {
+      const minimal = value.type === "control_write_loop_delay"
+        ? { type: "control_write_loop_delay", delayMs: typeof value.delayMs === "number" ? value.delayMs : 0, attribution: "unknown", spans: [], truncated: true }
+        : { type: "control_write_slow", kind: value.kind, ...(value.task === undefined ? {} : { task: value.task }), durationMs: value.durationMs, outcome: value.outcome, phases: [], truncated: true };
+      line = JSON.stringify(minimal);
+      if (Buffer.byteLength(line) > CONTROL_WRITE_MAX_LINE_BYTES) { this.droppedLogs++; return; }
+    }
+    this.lastEmit.set(key, now);
+    this.emitted.push(now);
+    try { this.options.emit(line); } catch { this.droppedLogs++; }
+  }
+
+  private privateNow(guard: ControlWritePrivacy): boolean {
+    try { return guard() === true; } catch { return false; }
+  }
+
+  private safeMetadata(metadata: unknown): ControlWriteMetadata | undefined {
+    if (!isObject(metadata)) return undefined;
+    try {
+      const kind = ownValue(metadata, "kind"), task = ownValue(metadata, "task");
+      if (typeof kind !== "string" || !(CONTROL_WRITE_KINDS as readonly string[]).includes(kind) || task !== undefined && !validTaskId(task)) return undefined;
+      return { kind: kind as ControlWriteKind, ...(task === undefined ? {} : { task }) };
+    } catch { return undefined; }
+  }
+
+  private readNow(): number {
+    let value: number;
+    try { value = this.nowFn(); } catch { this.clockFailures++; return this.lastNow; }
+    if (!Number.isFinite(value) || value < this.lastNow) { this.clockFailures++; return this.lastNow; }
+    this.lastNow = value;
+    return value;
+  }
+
+  private roundMs(value: number): number {
+    const bounded = Number.isFinite(value) ? Math.min(CONTROL_WRITE_MAX_DURATION_MS, Math.max(0, value)) : CONTROL_WRITE_MAX_DURATION_MS;
+    return Math.round(bounded * 10) / 10;
+  }
+}