@nightowlsdev/agent-diagnostics

@nightowlsdev/agent-diagnostics is the pre-built diagnostics crew, and the split into two agents is the point (the same FR-049 precedent as agent-seo): audiences and `delegateSlugs` gate AGENTS, never tools within one, so the agent boundary is the only mechanism that keeps a write/egress capability away from a caller's LLM. The `inspector` is danger 0 all the way down (`run_timeline`, `run_failure`, and the read-only `check_issue`), holds zero write and zero egress capability, and is safe to delegate to freely; everything that writes lives on the `bug-reporter` (`report_issue`, danger 2 — mutating, irreversible, egress). The read-only claim is ENFORCED, not merely stated: `createInspector()` declares `builtinTools: { exclude: ["report_issue"] }` (core's per-agent built-in scope, harvested by `defineSwarm` keyed by the agent's own slug), and `diagnosticsSwarmOptions()` emits the SAME scope as deployment configuration so the boundary survives agents rehydrated from the store, where no in-memory `AgentDef` exists to read a declaration off; the two fold most-restrictive-wins, so carrying both can only narrow. The four tools are ENGINE BUILT-INS, not package-authored handles: they read the calling run's tenant/user/run identity off the RequestContext (which is what makes their authorization gate and per-run cap un-forgeable), so the package DECLARES them (`DIAGNOSTICS_TOOL_NAMES`, each manifest's `requiredTools`) and hands the host the exact switches that register them, and `diagnosticsSwarmOptions()` THROWS when no `bugCapture` sink is wired rather than assembling a bug-reporter that looks configured, apologizes to every request, and files nothing. `report_issue` carries INTRINSIC approval (built `intrinsicApproval: true`, attributed `"explicit"`, which no approval mode may downgrade and no permissive host hook can relax), so a human approves every filing — `reporterApprovalRule()` is exported for defence-in-depth at the swarm seam but deliberately NOT attached, because a bundle-attached rule referencing the absent `report_issue` handle makes `createDiagnosticsCrew()` throw and an `AgentSpec.rules` entry would not survive rehydration anyway. Guidance ships as two versioned, tool-less `defineSkill` singletons (`diagnostic-investigation`, the protocol, and `bug-report-writing`, the write-up contract), rendered as non-callable skill instructions and overridable per deployment by name. `run_timeline` is a bounded, redacted projection — the last 200 steps, texts clipped, tool calls reduced to name/id/normalized-outcome, no argument or result values — and the investigation skill requires an indeterminate verdict when the truncated window could hold the deciding evidence.

agent-diagnostics is a pre-built crew — a read-only run inspector and an approval-gated bug-reporter — that turns a stalled lane and a vague apology into which call failed, whether it recovered, what class of failure ended the run, and (when it's a real defect) a report a developer can act on. The split into two agents is the security boundary: audiences and delegateSlugs gate AGENTS, never tools within one, so the agent boundary is the only mechanism that keeps the write/egress capability away from a caller's LLM.

createDiagnosticsCrew() returns a closure-validated BundleDef with the inspector and bug-reporter, the reporter's delegation to the inspector closing inside the bundle. The inspector holds run_timeline / run_failure / check_issue (all danger-0 reads) and excludes report_issue via its per-agent built-in scope; the bug-reporter holds report_issue (danger-2: mutating, irreversible, egress). diagnosticsSwarmOptions({ bugCapture, release? }) registers the four engine built-ins, re-asserts the read-only scope for rehydrated agents, and throws when no bugCapture sink is wired. Because the four are engine built-ins that read identity off the RequestContext, the package can only DECLARE them (DIAGNOSTICS_TOOL_NAMES) and must never define a same-named handle — which would shadow the real gated built-in.