opencode-herdr-orchestration 0.2.1 → 0.3.1

package/src/agents.js

@@ -38,6 +38,12 @@ const safeGitInspection = {
   "git ls-files": "allow",
 };
 
+// 20-M1 responsive wait: bounded `herdr agent get` polling uses only the
+// already-permitted prompt plus wait plus get plus read plus list surfaces.
+// No event stream command is evidenced, so no new Herdr command is invented;
+// `herdr agent wait` stays a bounded sleep between `get` state checks and the
+// safety timeout stays the final bound only. Sheepdog owns routine flock waits
+// with no per-transition Shepherd wakeups; governor leaf bans stay untouched.
 const herdrInspection = {
   "Get-Item Env:HERDR_ENV": "allow",
   "herdr --help": "allow",
@@ -96,6 +102,81 @@ function stateToolPermissions(allowedTools) {
   );
 }
 
+// Developer steering submission (M2, Option A, trusted Developer only).
+// The explicit non-flock `developer` context is the sole submitter; all
+// seven orchestration roles are denied as defense in depth. The runtime
+// context-agent check in src/index.js plus the /steer hook in src/steer.js
+// stays authoritative over these static entries: even a user override
+// flipping one to "allow" must not bypass the allowlist. No flock role may
+// present as Developer: the developer profile below holds only the submit
+// tool and no spawn matrix entry creates or targets it.
+export const DEVELOPER_AGENT = "developer";
+export const DEVELOPER_PROMPT = String.raw`
+You are developer, the trusted steering submitter. Submit bounded steering via /steer as <content> or <planId> :: <content>; omit planId only when exactly one active steering target exists. You hold only herdr_steering_submit; you never implement flock work, never spawn workers, and never read raw steering.
+`.trim();
+export const ORCHESTRATION_ROLES = Object.freeze([
+  "shepherd",
+  "shepherd-governor",
+  "sheepdog",
+  "grazer",
+  "sheep",
+  "shearer-low",
+  "shearer-medium",
+]);
+export const STEERING_TOOLS = Object.freeze({
+  submit: "herdr_steering_submit",
+});
+export const STEERING_TOOL_ACCESS = Object.freeze(
+  new Map([[STEERING_TOOLS.submit, new Set([DEVELOPER_AGENT])]]),
+);
+const ALL_STEERING_TOOLS = Object.freeze(Object.values(STEERING_TOOLS));
+
+function steeringToolPermissions(allowedTools) {
+  return Object.fromEntries(
+    ALL_STEERING_TOOLS.map((name) => [name, allowedTools.includes(name) ? "allow" : "deny"]),
+  );
+}
+
+// Shepherd ownership raw steering plus lifecycle tools (M3). Only the two
+// Shepherd phases may check, read, or consume raw steering and only the
+// recorded owner phase plus session plus generation passes the state-level
+// fencing (NOT AUTHORITATIVE PHASE otherwise). Sheepdog and every leaf are
+// explicitly denied in code, not only in prompts; the runtime check in
+// src/index.js stays authoritative over static overrides.
+export const SHEPHERD_PHASES = Object.freeze(["shepherd", "shepherd-governor"]);
+export const RAW_STEERING_TOOLS = Object.freeze({
+  check: "herdr_steering_check",
+  read: "herdr_steering_read",
+  consume: "herdr_steering_consume",
+});
+export const OWNERSHIP_TOOLS = Object.freeze({
+  claim: "herdr_ownership_claim",
+  read: "herdr_ownership_read",
+  sync: "herdr_ownership_sync",
+  snapshot: "herdr_ownership_snapshot",
+  correct: "herdr_ownership_correct",
+});
+export const RAW_STEERING_TOOL_ACCESS = Object.freeze(
+  new Map(Object.values(RAW_STEERING_TOOLS).map((name) => [name, new Set(SHEPHERD_PHASES)])),
+);
+export const OWNERSHIP_TOOL_ACCESS = Object.freeze(
+  new Map(Object.values(OWNERSHIP_TOOLS).map((name) => [name, new Set(SHEPHERD_PHASES)])),
+);
+const ALL_RAW_STEERING_TOOLS = Object.freeze(Object.values(RAW_STEERING_TOOLS));
+const ALL_OWNERSHIP_TOOLS = Object.freeze(Object.values(OWNERSHIP_TOOLS));
+
+function rawSteeringToolPermissions(allowedTools) {
+  return Object.fromEntries(
+    ALL_RAW_STEERING_TOOLS.map((name) => [name, allowedTools.includes(name) ? "allow" : "deny"]),
+  );
+}
+
+function ownershipToolPermissions(allowedTools) {
+  return Object.fromEntries(
+    ALL_OWNERSHIP_TOOLS.map((name) => [name, allowedTools.includes(name) ? "allow" : "deny"]),
+  );
+}
+
 const SHEPHERD_STATE_TOOLS = [STATE_TOOLS.planWrite, STATE_TOOLS.planRead];
 const GOVERNOR_STATE_TOOLS = [STATE_TOOLS.planRead];
 const SHEEPDOG_STATE_TOOLS = [
@@ -103,6 +184,8 @@ const SHEEPDOG_STATE_TOOLS = [
   STATE_TOOLS.executionWrite,
   STATE_TOOLS.executionRead,
 ];
+const SHEPHERD_RAW_STEERING_TOOLS = Object.values(RAW_STEERING_TOOLS);
+const SHEPHERD_OWNERSHIP_TOOLS = Object.values(OWNERSHIP_TOOLS);
 
 const SHEPHERD_SPAWNABLE_AGENTS = ["grazer"];
 const GOVERNOR_SPAWNABLE_AGENTS = ["grazer", "sheepdog"];
@@ -122,6 +205,148 @@ const SHEEPDOG_LIFECYCLE_ALLOWS = {
   "git commit*": "allow",
 };
 
+// Sheepdog Herdr lifecycle (21-M1): explicit prompt plus wait plus get plus
+// read allows. These re-assert the shared herdrInspection entries so the four
+// lifecycle operations stay evaluation-effective under OpenCode last-match
+// glob semantics: "*" deny is the fallback first, these allows sit in the
+// middle, separator denies stay global last. A prompt whose task text carries
+// raw "; && || | > <" matches a separator deny after the prompt allow and
+// fails closed to deny even inside quotes, so task text must avoid raw
+// separators (see SHEEPDOG_PROMPT safe rule).
+const SHEEPDOG_HERDR_LIFECYCLE_ALLOWS = {
+  "herdr agent prompt*": "allow",
+  "herdr agent wait*": "allow",
+  "herdr agent get*": "allow",
+  "herdr agent read*": "allow",
+};
+
+// Sheepdog interrupt bound (21-M1): replacement for the broad
+// "herdr agent send-keys*" allow in shared herdrInspection. The broad pattern
+// is explicitly denied first so only the narrow Ctrl-C spellings below are
+// evaluation-effective. Matchers are string globs and cannot prove semantic
+// intent, so the prompt inspect-first plus never-type rule stays primary; see
+// SHEEPDOG_PROMPT and README Worker interruption residual.
+const SHEEPDOG_SEND_KEYS_DENY = {
+  "herdr agent send-keys*": "deny",
+};
+const SHEEPDOG_SEND_KEYS_CTRL_C_ALLOWS = {
+  "herdr agent send-keys * --keys C-c*": "allow",
+  "herdr agent send-keys * --keys c-c*": "allow",
+  "herdr agent send-keys * --keys ctrl+c*": "allow",
+  "herdr agent send-keys * --keys Ctrl+C*": "allow",
+  "herdr agent send-keys * C-c*": "allow",
+  "herdr agent send-keys * ctrl+c*": "allow",
+};
+
+// Governor Herdr prompt residual (21-M2): `herdr agent prompt` plus wait plus
+// get plus read patterns are name-based and cannot encode worker role, so they
+// stay broad as far as text matchers permit. Prompt bans plus start denial
+// (spawn matrix allows only grazer and sheepdog) plus the response matrix
+// (retrieval allows only grazer and sheepdog) are the load-bearing layers;
+// see SHEPHERD_GOVERNOR_PROMPT and README Governor prompt scoping residual.
+// Governor interrupt bound (21-M2): replacement for the broad
+// "herdr agent send-keys*" allow in shared herdrInspection, mirroring the
+// sheepdog M1 bound. The broad pattern is explicitly denied first so only the
+// narrow Ctrl-C spellings below are evaluation-effective. Matchers are string
+// globs and cannot prove semantic intent, so the prompt inspect-first plus
+// never-type plus never-bypass rule stays primary.
+const GOVERNOR_SEND_KEYS_DENY = {
+  "herdr agent send-keys*": "deny",
+};
+const GOVERNOR_SEND_KEYS_CTRL_C_ALLOWS = {
+  "herdr agent send-keys * --keys C-c*": "allow",
+  "herdr agent send-keys * --keys c-c*": "allow",
+  "herdr agent send-keys * --keys ctrl+c*": "allow",
+  "herdr agent send-keys * --keys Ctrl+C*": "allow",
+  "herdr agent send-keys * C-c*": "allow",
+  "herdr agent send-keys * ctrl+c*": "allow",
+};
+
+// Pane layout (14-18-M1): live discovery on installed 0.8.2 via full-path
+// `herdr --help` plus `herdr --skill` plus scoped read-only queries
+// (`pane list --workspace w1K`, `tab list --workspace w1K`,
+// `pane current --current`, `pane layout --current`, `agent get <name>`,
+// `pane get w1K:p999` error sampling). Direct `herdr ...` spelling stays
+// denied for leaves; discovery used only read-only help plus list plus get
+// plus current plus layout, never split plus rename plus close plus start.
+// Tab evidenced as list plus create plus get plus focus plus rename plus
+// close; list takes `--workspace <ID>`, create takes
+// `--workspace/--cwd/--label/--env/--focus/--no-focus`, rename takes
+// `<TAB_ID> <LABEL>...`, close plus get plus focus take `<tab_id>`.
+// Pane placement evidenced as split plus move plus focus plus resize plus
+// swap plus layout plus get plus list plus current plus read plus rename plus
+// close; split is `[PANE_ID] --pane/--current --direction right/down --ratio
+// --cwd --env --focus/--no-focus`, move is `<PANE_ID>
+// --tab/--split/--target-pane/--ratio/--new-tab/--workspace/--new-workspace/--label/--tab-label/--focus/--no-focus`,
+// focus and neighbor take `--direction left/right/up/down --pane/--current`,
+// resize takes `--direction --amount --pane/--current`, swap takes
+// `--direction/--pane/--current/--source-pane/--target-pane`, layout takes
+// `--pane/--current`, get takes `<pane_id>`, list takes
+// `--workspace <ID>`, current takes `--pane/--current`, read takes
+// `<PANE_ID> --source visible/recent/recent-unwrapped/detection
+// --lines/--format/--ansi/--raw`, rename takes `<PANE_ID> [LABEL]...
+// --clear`, close takes `<pane_id>`.
+// Agent rename evidenced as `herdr agent rename <TARGET> <NAME>|--clear`
+// (live `agent list` shows `name` such as `issue1418m1sheep` and `agent get`
+// shows `name` plus `pane_id`); pane rename plus tab rename helps evidenced
+// but only pane plus agent rename are enabled, tab rename stays denied to
+// keep the single-tab 4-pane cap.
+// Count queries evidenced as `herdr tab list --workspace <ID>` returning
+// `{"id":"cli:tab:list","result":{"tabs":[{"pane_count":1,"tab_id":"w1K:t1",...}]},"type":"tab_list"}`,
+// `herdr pane list --workspace <ID>` returning
+// `{"id":"cli:pane:list","result":{"panes":[{...,"pane_id":"w1K:p1","tab_id":"w1K:t1","workspace_id":"w1K",...}]},"type":"pane_list"}`
+// (count is length filtered by workspace plus tab), `herdr pane layout
+// --current` returning
+// `{"id":"cli:pane:layout","result":{"layout":{"panes":[...],"splits":[],"focused_pane_id":"w1K:p1",...}},"type":"pane_layout"}`,
+// `herdr pane current --current` returning
+// `{"id":"cli:pane:current","result":{"pane":{...}},"type":"pane_current"}`.
+// Creation JSON per `herdr --skill`: `tab create` returns
+// `.result.tab` plus `.result.root_pane`, `pane split` returns the new pane
+// as `.result.pane` (skill geometry is `pane split --current --direction
+// right/down --cwd "$PWD" --no-focus`, wide to the right and narrow or tall
+// down, reading `.result.pane.pane_id` and never deriving from sidebar
+// order), `pane move` would return
+// `.result.move_result.pane.pane_id` plus `.result.move_result.previous_pane_id`
+// but move stays denied and is documented only.
+// Exits per `herdr --skill` plus live sampling: most controls return JSON on
+// stdout with `id` plus `result` plus `type`; server errors are JSON such as
+// `{"error":{"code":"pane_not_found","message":"pane w1K:p999 not found"},"id":"cli:pane:get"}`
+// on stderr with exit 1; syntax plus validation such as `pane split
+// --direction invalid` returning `invalid split direction` exits with 2.
+// IDs are opaque stable handles (`w1K`, `w1K:t1`, `w1K:p1` from
+// `HERDR_WORKSPACE_ID` plus `HERDR_TAB_ID` plus `HERDR_PANE_ID`); closed IDs
+// are not reused; prefer `--current` and never rely on the UI-focused pane.
+// Fallback if any of tab list plus pane get plus rename plus close plus
+// split are missing: reuse the current pane via `--pane` plus `--current`,
+// report STOP naming the missing capability, never invent `herdr pane
+// create*` plus `herdr tab split*` plus `herdr agent events*` plus
+// `herdr pane move*` plus `herdr pane resize*` plus `herdr workspace
+// create*` behavior.
+// Protected Dev Developer Terminal exclusion cannot be matcher-enforced:
+// pane IDs are opaque and labels are absent from scan plus split plus close
+// command strings, while a `*Dev*` glob would overmatch legitimate
+// `--cwd C:\Dev\...` values, so no such glob is added; the prompt plus
+// README Pane layout policy exclusion stays primary; see README residual.
+const SHEPHERD_PANE_ALLOWS = {
+  "herdr tab list*": "allow",
+  "herdr pane get*": "allow",
+  "herdr pane rename*": "allow",
+  "herdr agent rename*": "allow",
+};
+const GOVERNOR_PANE_ALLOWS = {
+  "herdr tab list*": "allow",
+  "herdr pane get*": "allow",
+  "herdr pane rename*": "allow",
+  "herdr agent rename*": "allow",
+};
+const SHEEPDOG_PANE_ALLOWS = {
+  "herdr tab list*": "allow",
+  "herdr pane get*": "allow",
+  "herdr pane rename*": "allow",
+  "herdr agent rename*": "allow",
+  "herdr pane close*": "allow",
+};
+
 const SHEEPDOG_DENIALS = {
   "git push*": "deny",
   "git pull*": "deny",
@@ -202,7 +427,9 @@ export function createAgents(options = {}) {
   const sheepdogVariant = options.sheepdogVariant;
   const reviewerModel = options.reviewerModel ?? "litellm-responses/gpt-5.6-terra";
   const shepherdPermissions = options.shepherdPermissions ?? {};
-  const shepherdPrompt = appendPrompt(SHEPHERD_PROMPT, options.shepherdPromptAppend);
+  const shepherdPrompt = appendPrompt(SHEPHERD_PROMPT, options.shepherdPromptAppend, "shepherdPromptAppend");
+  const sheepdogPermissions = options.sheepdogPermissions ?? {};
+  const sheepdogPrompt = appendPrompt(SHEEPDOG_PROMPT, options.sheepdogPromptAppend, "sheepdogPromptAppend");
 
   return {
     shepherd: {
@@ -218,9 +445,13 @@ export function createAgents(options = {}) {
         apply_patch: markdownOnly,
         herdr_agent_response: "allow",
         ...stateToolPermissions(SHEPHERD_STATE_TOOLS),
+        ...steeringToolPermissions([]),
+        ...rawSteeringToolPermissions(SHEPHERD_RAW_STEERING_TOOLS),
+        ...ownershipToolPermissions(SHEPHERD_OWNERSHIP_TOOLS),
         bash: {
           "*": "deny",
           ...herdrInspection,
+          ...SHEPHERD_PANE_ALLOWS,
           ...spawnMatrix(SHEPHERD_SPAWNABLE_AGENTS),
           "git status*": "allow",
           "git diff*": "allow",
@@ -261,9 +492,13 @@ export function createAgents(options = {}) {
         apply_patch: markdownOnly,
         herdr_agent_response: "allow",
         ...stateToolPermissions(GOVERNOR_STATE_TOOLS),
+        ...steeringToolPermissions([]),
+        ...rawSteeringToolPermissions(SHEPHERD_RAW_STEERING_TOOLS),
+        ...ownershipToolPermissions(SHEPHERD_OWNERSHIP_TOOLS),
         bash: {
           "*": "deny",
           ...herdrInspection,
+          ...GOVERNOR_PANE_ALLOWS,
           ...spawnMatrix(GOVERNOR_SPAWNABLE_AGENTS),
           "git status*": "allow",
           "git diff*": "allow",
@@ -303,6 +538,8 @@ export function createAgents(options = {}) {
           "gh pr create*": "allow",
           "gh pr view*": "allow",
           "gh pr checks*": "allow",
+          ...GOVERNOR_SEND_KEYS_DENY,
+          ...GOVERNOR_SEND_KEYS_CTRL_C_ALLOWS,
           ...separatorDenials,
         },
         task: "deny",
@@ -315,7 +552,7 @@ export function createAgents(options = {}) {
       ...(sheepdogVariant ? { variant: sheepdogVariant } : {}),
       description:
         "Leads execution squads of grazer, sheep, and shearers, prepares worker branches and worktrees, owns validation, review tiers, retries, and conflict recovery, and performs clean local integration with merge and cherry-pick lifecycle commands only.",
-      prompt: SHEEPDOG_PROMPT,
+      prompt: sheepdogPrompt,
       permission: {
         read: "allow",
         glob: "allow",
@@ -326,16 +563,24 @@ export function createAgents(options = {}) {
         apply_patch: "deny",
         herdr_agent_response: "allow",
         ...stateToolPermissions(SHEEPDOG_STATE_TOOLS),
+        ...steeringToolPermissions([]),
+        ...rawSteeringToolPermissions([]),
+        ...ownershipToolPermissions([]),
         bash: {
           "*": "deny",
           ...safeGitInspection,
           ...herdrInspection,
+          ...SHEEPDOG_PANE_ALLOWS,
           ...spawnMatrix(SHEEPDOG_SPAWNABLE_AGENTS),
+          ...SHEEPDOG_HERDR_LIFECYCLE_ALLOWS,
           ...SHEEPDOG_LIFECYCLE_ALLOWS,
           ...SHEEPDOG_DENIALS,
+          ...SHEEPDOG_SEND_KEYS_DENY,
+          ...SHEEPDOG_SEND_KEYS_CTRL_C_ALLOWS,
           ...separatorDenials,
         },
         task: "deny",
+        ...sheepdogPermissions,
       },
     },
 
@@ -355,6 +600,9 @@ export function createAgents(options = {}) {
         apply_patch: "deny",
         herdr_agent_response: "deny",
         ...stateToolPermissions([]),
+        ...steeringToolPermissions([]),
+        ...rawSteeringToolPermissions([]),
+        ...ownershipToolPermissions([]),
         bash: { "*": "deny", ...safeGitInspection, ...separatorDenials },
         task: "deny",
       },
@@ -371,6 +619,9 @@ export function createAgents(options = {}) {
         grep: "allow",
         herdr_agent_response: "deny",
         ...stateToolPermissions([]),
+        ...steeringToolPermissions([]),
+        ...rawSteeringToolPermissions([]),
+        ...ownershipToolPermissions([]),
         bash: {
           "*": "allow",
           ...SHEEP_DENIALS,
@@ -382,13 +633,30 @@ export function createAgents(options = {}) {
 
     "shearer-low": reviewerAgent(reviewerModel, "low"),
     "shearer-medium": reviewerAgent(reviewerModel, "medium"),
+
+    developer: {
+      mode: "primary",
+      description: "Trusted Developer steering submitter; submits bounded steering via /steer; never implements flock work.",
+      prompt: DEVELOPER_PROMPT,
+      permission: {
+        ...stateToolPermissions([]),
+        ...steeringToolPermissions([STEERING_TOOLS.submit]),
+        ...rawSteeringToolPermissions([]),
+        ...ownershipToolPermissions([]),
+        herdr_agent_response: "deny",
+        task: "deny",
+        edit: "deny",
+        apply_patch: "deny",
+        bash: { "*": "deny", ...separatorDenials },
+      },
+    },
   };
 }
 
-function appendPrompt(prompt, addition) {
+function appendPrompt(prompt, addition, optionName = "shepherdPromptAppend") {
   if (addition === undefined || addition === "") return prompt;
   if (typeof addition !== "string") {
-    throw new TypeError("shepherdPromptAppend must be a string.");
+    throw new TypeError(`${optionName} must be a string.`);
   }
   return `${prompt.trimEnd()}\n\n${addition.trim()}`;
 }
@@ -410,6 +678,9 @@ function reviewerAgent(model, variant) {
       todowrite: "deny",
       herdr_agent_response: "deny",
       ...stateToolPermissions([]),
+      ...steeringToolPermissions([]),
+      ...rawSteeringToolPermissions([]),
+      ...ownershipToolPermissions([]),
       bash: { "*": "deny", ...safeGitInspection, ...separatorDenials },
       task: "deny",
     },

package/src/diagnostics.js

@@ -0,0 +1,117 @@
+// 20-M2 operational diagnostics log (diagnostics only, never results).
+// Strategy: process-local bounded in-memory ring buffer with no filesystem,
+// no Git, no Herdr commands, no plugin tools, and no persistence. Entries are
+// ephemeral like SHEPHERD_MODE and response cursors: they do not survive a
+// plugin restart and must never substitute for authoritative retrieval via
+// herdr_agent_response until complete is true.
+// Guardrails: no chain of thought, no transcripts, no scrollback, bounded
+// size per field, bounded retention per log, never read as results.
+export const DIAGNOSTIC_EVENT_TYPES = Object.freeze([
+  "worker-started",
+  "prompt-submitted",
+  "state-changed",
+  "command-failed",
+  "settled",
+  "disappeared",
+  "timed-out",
+  "recovery-started",
+]);
+const DIAGNOSTIC_EVENT_SET = new Set(DIAGNOSTIC_EVENT_TYPES);
+export const MAX_DIAGNOSTIC_EVENTS_DEFAULT = 100;
+export const MAX_DIAGNOSTIC_EVENTS_LIMIT = 1000;
+export const MAX_DIAGNOSTIC_TARGET_CHARS = 64;
+export const MAX_DIAGNOSTIC_CODE_CHARS = 64;
+export const MAX_DIAGNOSTIC_DETAIL_CHARS = 512;
+const SENSITIVE_DIAGNOSTIC_PATTERN = /(transcript|scrollback|chain\s*of\s*thought)/i;
+function diagnosticError(code, message) {
+  return { ok: false, error: { code, message, retryable: false } };
+}
+function validateDiagnosticType(type) {
+  if (typeof type !== "string" || !DIAGNOSTIC_EVENT_SET.has(type)) {
+    return diagnosticError(
+      "INVALID_DIAGNOSTIC_TYPE",
+      `Diagnostic type must be one of: ${DIAGNOSTIC_EVENT_TYPES.join(", ")}.`,
+    );
+  }
+  return null;
+}
+function validateDiagnosticTarget(target) {
+  if (typeof target !== "string" || target.length === 0 || target.length > MAX_DIAGNOSTIC_TARGET_CHARS) {
+    return diagnosticError(
+      "INVALID_DIAGNOSTIC_TARGET",
+      `Diagnostic target must be a non-empty string of at most ${MAX_DIAGNOSTIC_TARGET_CHARS} characters.`,
+    );
+  }
+  return null;
+}
+function validateDiagnosticCode(code) {
+  if (code === undefined) return null;
+  if (typeof code !== "string" || code.length === 0 || code.length > MAX_DIAGNOSTIC_CODE_CHARS) {
+    return diagnosticError(
+      "INVALID_DIAGNOSTIC_CODE",
+      `Diagnostic code must be a non-empty string of at most ${MAX_DIAGNOSTIC_CODE_CHARS} characters.`,
+    );
+  }
+  if (SENSITIVE_DIAGNOSTIC_PATTERN.test(code)) {
+    return diagnosticError(
+      "SENSITIVE_CONTENT_EXCLUDED",
+      "Diagnostic code must not contain transcript, scrollback, or chain of thought content.",
+    );
+  }
+  return null;
+}
+function validateDiagnosticDetail(detail) {
+  if (detail === undefined) return null;
+  if (typeof detail !== "string" || detail.length > MAX_DIAGNOSTIC_DETAIL_CHARS) {
+    return diagnosticError(
+      "INVALID_DIAGNOSTIC_DETAIL",
+      `Diagnostic detail must be a string of at most ${MAX_DIAGNOSTIC_DETAIL_CHARS} characters; response text is never stored.`,
+    );
+  }
+  if (SENSITIVE_DIAGNOSTIC_PATTERN.test(detail)) {
+    return diagnosticError(
+      "SENSITIVE_CONTENT_EXCLUDED",
+      "Diagnostic detail must not contain transcript, scrollback, or chain of thought content; store only bounded operational summaries.",
+    );
+  }
+  return null;
+}
+export function createDiagnosticsLog(options = {}) {
+  const maxEvents = options.maxEvents ?? MAX_DIAGNOSTIC_EVENTS_DEFAULT;
+  if (!Number.isSafeInteger(maxEvents) || maxEvents < 1 || maxEvents > MAX_DIAGNOSTIC_EVENTS_LIMIT) {
+    throw new TypeError(`maxEvents must be an integer from 1 through ${MAX_DIAGNOSTIC_EVENTS_LIMIT}.`);
+  }
+  const now = options.now ?? Date.now;
+  let sequence = 0;
+  const events = [];
+  function record(type, fields = {}) {
+    const typeFailure = validateDiagnosticType(type);
+    if (typeFailure) return typeFailure;
+    const targetFailure = validateDiagnosticTarget(fields.target);
+    if (targetFailure) return targetFailure;
+    const codeFailure = validateDiagnosticCode(fields.code);
+    if (codeFailure) return codeFailure;
+    const detailFailure = validateDiagnosticDetail(fields.detail);
+    if (detailFailure) return detailFailure;
+    sequence += 1;
+    const event = {
+      sequence,
+      type,
+      target: fields.target,
+      ...(fields.code === undefined ? {} : { code: fields.code }),
+      ...(fields.detail === undefined ? {} : { detail: fields.detail }),
+      at: new Date(now()).toISOString(),
+    };
+    events.push(event);
+    while (events.length > maxEvents) events.shift();
+    return { ok: true, event: { ...event } };
+  }
+  function list() {
+    return { ok: true, events: events.map((event) => ({ ...event })), dropped: sequence - events.length, maxEvents };
+  }
+  function clear() {
+    events.length = 0;
+    return { ok: true, dropped: sequence, maxEvents };
+  }
+  return { record, list, clear, maxEvents };
+}