opencode-swarm 7.136.4 → 7.137.0

package/dist/observability/ids.d.ts

@@ -0,0 +1,97 @@
+/** Hex width of a W3C `trace-id`. */
+export declare const TRACE_ID_HEX_LENGTH: number;
+/** Hex width of a W3C span id. */
+export declare const SPAN_ID_HEX_LENGTH: number;
+/**
+ * Environment variable that overrides the lineage salt.
+ *
+ * Deliberately NOT read at module scope: reading `process.env` during module
+ * evaluation would make the salt depend on import order and would defeat any
+ * test that sets it after import. `resolveLineageSalt()` reads it per call.
+ */
+export declare const LINEAGE_SALT_ENV = "SWARM_OBSERVABILITY_LINEAGE_SALT";
+/**
+ * Salt used when {@link LINEAGE_SALT_ENV} is unset.
+ *
+ * A constant default is intentional: lineage refs must be stable for a given
+ * path across processes and restarts, otherwise `projectRef` could not correlate
+ * two runs of the same project. Operators who want cross-install unlinkability
+ * set {@link LINEAGE_SALT_ENV} to a private value.
+ */
+export declare const DEFAULT_LINEAGE_SALT = "opencode-swarm/observability/lineage/v1";
+/** Hex characters retained from the SHA-256 digest for a lineage ref. */
+export declare const PSEUDONYMOUS_REF_LENGTH = 16;
+/** A correlated `traceId` + `spanId` pair produced from one CSPRNG call. */
+export interface TraceAndSpanId {
+    readonly traceId: string;
+    readonly spanId: string;
+}
+/**
+ * Generate a W3C-compatible trace id: 32 lowercase hex characters, never
+ * all-zero.
+ *
+ * NAME COLLISION, deliberate to record rather than rename: `newTraceId` in
+ * `src/hooks/knowledge-events.ts` has the identical `(): string` signature but
+ * a DIFFERENT on-wire shape — a 36-character RFC 4122 UUID, not 32 hex
+ * characters. Nothing outside this directory imports this one, and it is no
+ * longer re-exported from `src/observability/index.ts`, so the two cannot be
+ * confused through the barrel. (`newEventId` is unaffected: both return
+ * `randomUUID()`.)
+ */
+export declare function newTraceId(): string;
+/**
+ * Generate a W3C-compatible span id: 16 lowercase hex characters, never
+ * all-zero.
+ */
+export declare function newSpanId(): string;
+/** Generate an event id (RFC 4122 UUID v4). */
+export declare function newEventId(): string;
+/**
+ * Derive a correlated trace/span pair, consuming 24 bytes from the pool above.
+ *
+ * This exists for the hot path: `createObservation` runs on every `emit()`, and
+ * src/telemetry.ts:315-317 documents that path as deliberately frugal.
+ */
+export declare function newTraceAndSpanId(): TraceAndSpanId;
+/**
+ * Resolve the lineage salt.
+ *
+ * Reads {@link LINEAGE_SALT_ENV} at call time (never at module scope) and falls
+ * back to {@link DEFAULT_LINEAGE_SALT}. Reading an environment variable is not
+ * I/O — no file, socket, or subprocess is touched.
+ */
+export declare function resolveLineageSalt(): string;
+/**
+ * Produce a pseudonymous reference for an absolute path.
+ *
+ * `sha256(salt + NUL + absolutePath)`, truncated to 16 hex characters.
+ *
+ * Properties this guarantees, and why each matters (issue #2029 item 2 / AC3):
+ *   - The result never CONTAINS or ENCODES the input path. It is a one-way
+ *     digest, not an encoding.
+ *   - Two different project paths carrying the SAME cohort label produce
+ *     DIFFERENT refs, because the path is part of the digest input.
+ *   - The result is stable for a given (salt, path) pair, so the same project
+ *     correlates across processes and restarts.
+ *
+ * What it does NOT guarantee, stated plainly rather than overclaimed: this is a
+ * PSEUDONYM, not an anonymous value, and it is not "irreversible" in the sense
+ * that matters. With the PUBLIC {@link DEFAULT_LINEAGE_SALT} the digest input is
+ * fully known except for the path, and real paths are low entropy, so a holder
+ * of an export can CONFIRM a guessed path by re-hashing candidates and matching
+ * the ref. Setting {@link LINEAGE_SALT_ENV} to a private per-install value
+ * restores guess-resistance and makes refs unlinkable across installs. The
+ * algorithm is deliberately left alone here: deriving and persisting a
+ * per-install salt needs init-path I/O, which AGENTS.md invariant 1 forbids, so
+ * it belongs with #2047.
+ *
+ * SCOPE of the AC3 claim: `cohortRef` and `worktreeRef` are computed only when a
+ * caller supplies `cohortLabel` / `worktreeId` to `initObservability`. The sole
+ * production caller (`src/index.ts:732-744`) supplies neither, so both are
+ * `undefined` in every real run today; AC3 is asserted at unit level against
+ * this API, not against a production emission path.
+ *
+ * @param absolutePath - Value to pseudonymize. Never stored or echoed.
+ * @param salt - Salt from {@link resolveLineageSalt}.
+ */
+export declare function pseudonymousRef(absolutePath: string, salt: string): string;

package/dist/observability/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The observability event contract (issue #2029).
+ *
+ * Reference documentation: `docs/observability-event-contract.md`.
+ *
+ * ## What this module is
+ *
+ * A versioned, discriminated, catalogued envelope for every observability record
+ * this plugin produces, plus the adapter that projects the existing untyped
+ * telemetry payloads onto it. The defect class it closes: *a production
+ * telemetry record is written without a versioned, discriminated, catalogued
+ * envelope — so a consumer cannot determine producer, schema generation, or
+ * unknown-versus-absent, and a new event kind can enter the stream without any
+ * registration.*
+ *
+ * ## The guarantees callers can rely on
+ *
+ * - **Zero I/O.** No filesystem, network, subprocess, dynamic import, or
+ *   OpenTelemetry SDK anywhere in this directory. `node:crypto` and `zod` are
+ *   the only imports. That is what keeps `initObservability` safe on the plugin
+ *   init path (AGENTS.md invariant 1) and the bundle Node-ESM-portable
+ *   (invariant 2).
+ * - **`createObservation` never throws** — not on a circular object, a
+ *   function/`Symbol`/`BigInt` payload, an unknown kind, or `null` data. It
+ *   never serializes, clones, or deep-traverses the payload.
+ * - **`legacy.raw` is an ALIAS** to the caller's payload, never a copy. Key
+ *   order, key collisions and `undefined`-key elision in the written line depend
+ *   on it.
+ * - **Nothing is synthesized.** An identifier the producer does not hold stays
+ *   `undefined`; an unversioned store records `sourceSchemaVersion: null`
+ *   (unknown, not zero); an absent field is listed in `legacy.unknown` rather
+ *   than defaulted.
+ * - **Validation returns, never throws.** `validateEventRelationships` and
+ *   `assertBoundedCardinality` both yield verdicts.
+ *
+ * ## What it is NOT, stated plainly
+ *
+ * The envelope is not yet authoritative. `toLegacyTelemetryLine` is a
+ * deliberately lossy, legacy-pinned projection: the non-legacy fields
+ * (`eventId`, `trace`, `lineage`, `provenance`, `policy`, `writerSequence`,
+ * `relationshipViolations`) are currently discarded, and their consumer lands in
+ * **#2047**. Consequently `validateEventRelationships` does not bite at runtime
+ * today — it bites in unit tests and in the static contract check.
+ */
+export type { CatalogEntry, OtelMappingKind } from './catalog.js';
+export { CATALOG_KINDS, EVENT_CATALOG, getCatalogEntry, } from './catalog.js';
+export type { Lineage, ObservabilityEvent, Outcome, Policy, Provenance, } from './envelope.js';
+export { OBSERVABILITY_SCHEMA_VERSION, ObservabilityEventSchema, } from './envelope.js';
+export type { TraceAndSpanId } from './ids.js';
+export { newEventId, newSpanId, pseudonymousRef, SPAN_ID_HEX_LENGTH, TRACE_ID_HEX_LENGTH, } from './ids.js';
+export { adaptLegacyTelemetryPayload, extractOutcome, extractWorkflowIds, KNOWN_TELEMETRY_KEYS, LEGACY_ADAPTER_RULES, NON_OBJECT_PAYLOAD_MARKER, } from './legacy.js';
+export type { InitObservabilityInput } from './observe.js';
+export { createObservation, initObservability, resetObservabilityForTesting, toLegacyTelemetryLine, } from './observe.js';
+export { mappingForEntry, OPENINFERENCE_ATTRIBUTES, OPENINFERENCE_MAPPING_VERSION, OTEL_GENAI_ATTRIBUTES, OTEL_GENAI_MAPPING_VERSION, } from './otel-mapping.js';
+export type { RelationshipValidationResult } from './relationships.js';
+export { RELATIONSHIP_VIOLATION_CODES, validateEventRelationships, } from './relationships.js';
+export type { CardinalityResult } from './sampling.js';
+export { assertBoundedCardinality, METRIC_LABEL_ALLOWLIST, shouldSample, } from './sampling.js';

package/dist/observability/legacy.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Legacy telemetry adapter (issue #2029 item 4 / AC2).
+ *
+ * Its real production input is the untyped `data: Record<string, unknown>` that
+ * `src/telemetry.ts:emit()` receives from 40+ call sites: caller-ordered,
+ * unversioned, with extra and missing fields. That is legacy-shaped input by
+ * definition, and adapting it is this module's genuine job.
+ *
+ * Two hard constraints govern every function here:
+ *   1. **Never throw.** `emit()` documents a never-throw guarantee
+ *      (`src/telemetry.ts:266,294`) and `src/telemetry.test.ts:137-162`
+ *      exercises circular objects, functions, `Symbol`s and `BigInt`s.
+ *   2. **Never deep-traverse, clone, or serialize the payload.** Only
+ *      `Object.keys` (shallow) and own-key reads. See `LegacyProjectionSchema`
+ *      for why `raw` must stay an alias.
+ *
+ * Import rules: no filesystem, network, subprocess, or OTel SDK.
+ */
+import type { LegacyProjection, Outcome, WorkflowIds } from './envelope.js';
+/** The store these payloads are written to. */
+export declare const LEGACY_TELEMETRY_SOURCE_STORE = ".swarm/telemetry.jsonl";
+/** Marker recorded in `legacy.unknown` when the payload is not an object. */
+export declare const NON_OBJECT_PAYLOAD_MARKER = "<non-object-payload>";
+/**
+ * Marker recorded when the payload resisted shallow introspection — a Proxy
+ * whose `ownKeys` trap throws, or a throwing getter. The payload is still kept
+ * by reference; only our description of it is degraded.
+ */
+export declare const INTROSPECTION_FAILED_MARKER = "<payload-introspection-failed>";
+/**
+ * The adapter rules, stated as a checkable list.
+ *
+ * These are the item-4 rules of issue #2029. They are exported as data (not
+ * prose in a doc file) so the static contract check and the unit tests can
+ * assert against the same statement of intent the implementation follows.
+ */
+export declare const LEGACY_ADAPTER_RULES: readonly string[];
+/**
+ * Payload keys each producer is known to emit.
+ *
+ * Derived from the emit call sites in source, NOT from captured output: a key
+ * whose value is `undefined` is elided by `JSON.stringify`, so a captured line
+ * under-reports the producer's key set. Listing those keys here is precisely
+ * what makes `legacy.unknown` non-vacuous — `delegation_end` naming `model`,
+ * `gate` and `retry_index` lets the adapter say "the producer did not know
+ * these" instead of silently omitting them.
+ */
+export declare const KNOWN_TELEMETRY_KEYS: Readonly<Record<string, readonly string[]>>;
+export declare function adaptLegacyTelemetryPayload(kind: string, data: unknown, knownKeys: readonly string[]): LegacyProjection;
+/**
+ * Extract recognized correlation IDs from a legacy payload.
+ *
+ * Shallow, never throws, and NEVER synthesizes: an ID that is absent, empty, or
+ * of the wrong type stays `undefined`. Only the mappings a producer actually
+ * populates are implemented — `sessionId` to `hostSessionId`, `taskId`, `phase`
+ * to `phaseId`, `laneId`, `batchId`. The remaining eight recognized IDs have no
+ * current producer, and inventing an extraction for them would manufacture
+ * exactly the joins issue #2029 item 2 forbids.
+ */
+export declare function extractWorkflowIds(data: unknown): WorkflowIds;
+/**
+ * Extract terminal disposition from a legacy payload.
+ *
+ * Shallow and never throws. `durationMs` is deliberately never populated: no
+ * current producer reports a duration, and deriving one would fabricate a
+ * measurement.
+ */
+export declare function extractOutcome(data: unknown): Outcome;

package/dist/observability/observe.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Observation construction and the legacy line projection (issue #2029).
+ *
+ * Import rules: no filesystem, network, subprocess, or OTel SDK. Everything here
+ * is synchronous and allocation-only.
+ *
+ * ## Module state
+ *
+ * Four process-scoped variables. None is session-keyed, so AGENTS.md invariant 8
+ * (session-scoped state must be keyed by `sessionID` and bounded) does not
+ * apply: `_provenance` and `_lineage` are single small frozen-by-convention
+ * records describing THIS process, `_sampleRate` is a scalar, and
+ * `_writerSequence` is a scalar counter. None of them grows with session count,
+ * so there is nothing to evict. All four have a reset seam
+ * ({@link resetObservabilityForTesting}) so no test's assertions become order
+ * dependent.
+ */
+import { type ObservabilityEvent, type Provenance } from './envelope.js';
+/** Violation code stamped on a fallback event. */
+export declare const OBSERVATION_BUILD_FAILED = "observation_build_failed";
+/** Input to {@link initObservability}. */
+export interface InitObservabilityInput {
+    /** Absolute project root. Pseudonymized, never stored. */
+    directory?: string;
+    /** Cohort label (e.g. a swarm id). Pseudonymized together with `directory`. */
+    cohortLabel?: string;
+    /** Worktree identity. Pseudonymized, never stored. */
+    worktreeId?: string;
+    provenance?: Provenance;
+    sampleRate?: number;
+}
+/**
+ * Install process provenance and lineage.
+ *
+ * Performs ZERO I/O — it hashes strings the caller already holds. That matters
+ * for AGENTS.md invariant 1: this runs on the plugin init path, and init-path
+ * work must be fast, bounded and side-effect-minimal.
+ *
+ * Lineage refs are computed ONCE here and reused by every subsequent
+ * observation. Computing them per-emit would put three SHA-256 digests on the
+ * hot path for values that never change within a process.
+ *
+ * NEVER THROWS. The whole body is guarded: a failure here must not prevent the
+ * plugin manifest from being returned (invariant 1, fail-open).
+ */
+export declare function initObservability(input: InitObservabilityInput): void;
+/**
+ * Build the canonical observation for one emit.
+ *
+ * **NEVER THROWS.** Not on a circular object, not on a function / `Symbol` /
+ * `BigInt` payload, not on an unknown kind, not on `null` or `undefined` data.
+ * It never calls `JSON.stringify`, never clones, and never deep-traverses
+ * `data` — `src/telemetry.test.ts:137-162` emits exactly those payloads and
+ * asserts `emit()` does not throw, and `src/telemetry.ts:266` documents the
+ * never-throw guarantee. If anything inside fails, a minimal valid event is
+ * returned carrying `relationshipViolations: ['observation_build_failed']`.
+ *
+ * An UNCATALOGUED kind is classified (`category: 'unrecognized'`), never
+ * dropped. Preventing new unrecognized kinds is the static contract check's job,
+ * not a runtime drop.
+ *
+ * `occurredAt` is set equal to `observedAt`. That is a recorded finding, not an
+ * invention: no current producer supplies a distinct time at which the described
+ * thing happened, so claiming one would fabricate precision the source does not
+ * have.
+ */
+export declare function createObservation(kind: string, data: unknown): ObservabilityEvent;
+/**
+ * Project a canonical event onto the legacy `.swarm/telemetry.jsonl` record.
+ *
+ * ## This projection is LOSSY and LEGACY-PINNED
+ *
+ * The envelope's non-legacy fields — `eventId`, `trace` (`traceId`, `spanId`,
+ * `parentSpanId`, `links`), `lineage`, `provenance`, `policy`, `writerSequence`,
+ * `schemaVersion` and `relationshipViolations` — are **currently DISCARDED**.
+ * Nothing in this change consumes them; their consumer lands in **#2047**. That
+ * is stated here rather than buried: a reader of this function must not conclude
+ * the written line is the canonical record. It is not.
+ *
+ * ## Byte-for-byte preservation
+ *
+ * The caller's object is spread **LAST**, exactly as the pre-change inline line
+ * construction in `src/telemetry.ts` `emit()` did. Three properties depend on
+ * that ordering, and all three are observable in
+ * `tests/fixtures/observability/telemetry-lines-golden.json` (issue #2029 item
+ * 5 arm (a) — "preserve the existing output"):
+ *
+ *   1. **Caller key order** is preserved after `timestamp` and `event`.
+ *   2. **Caller key collisions win on value.** `conflict-resolution.ts:55-66`
+ *      supplies its own `timestamp` and `type`; the caller's `timestamp` value
+ *      overwrites the envelope's while the key keeps position 1.
+ *   3. **`undefined`-key elision** is unchanged, because the caller's own object
+ *      is spread rather than a reconstruction of it.
+ *
+ * `timestamp` is taken from `event.observedAt` — a real, load-bearing data
+ * dependency on the canonical event, which is why this composition is not the
+ * identity function on the emit path.
+ *
+ * A non-object, `null`, or array payload yields just `{ timestamp, event }`,
+ * matching what `JSON.stringify({ timestamp, event, ...data })` produces for
+ * those inputs.
+ */
+export declare function toLegacyTelemetryLine(event: ObservabilityEvent): Record<string, unknown>;
+/**
+ * Reset all four module-scoped variables.
+ *
+ * Called alongside `resetTelemetryForTesting` so no test's assertions become
+ * dependent on how many events an earlier test emitted.
+ *
+ * @internal - For testing only
+ */
+export declare function resetObservabilityForTesting(): void;

package/dist/observability/otel-mapping.d.ts

@@ -0,0 +1,48 @@
+/**
+ * External-convention attribute mappings (issue #2029 item 6).
+ *
+ * These are INERT LOOKUP TABLES. There is no OpenTelemetry SDK dependency, no
+ * exporter, and no runtime consumer in this change: the tables are consumed as
+ * data by the static contract check (which asserts every catalog entry records a
+ * mapping decision) and by `docs/observability-event-contract.md`. The runtime
+ * consumer lands in #2049.
+ *
+ * Import rules: no filesystem, network, subprocess, or OTel SDK.
+ */
+import type { OtelMappingKind } from './catalog.js';
+/**
+ * OpenTelemetry semantic-convention generation these GenAI attribute names track.
+ *
+ * Pinned SEPARATELY from `OBSERVABILITY_SCHEMA_VERSION`. That separation is the
+ * whole point of issue #2029 item 6: the GenAI conventions are an external,
+ * still-unstable vocabulary. If they were versioned together, an upstream rename
+ * would force a bump of the internal envelope version and every consumer would
+ * be told the domain shape changed when nothing about the domain changed.
+ * External convention churn must never change internal domain state.
+ */
+export declare const OTEL_GENAI_MAPPING_VERSION = "1.29.0";
+/**
+ * OpenInference specification generation these attribute names track. Pinned
+ * separately from both {@link OTEL_GENAI_MAPPING_VERSION} and
+ * `OBSERVABILITY_SCHEMA_VERSION`, for the same reason.
+ */
+export declare const OPENINFERENCE_MAPPING_VERSION = "0.1.14";
+/**
+ * Internal envelope path to OTel GenAI attribute name.
+ *
+ * Keys are dotted paths into `ObservabilityEvent`. `legacy.raw.*` paths reach
+ * into the aliased producer payload, which is where token counts and the
+ * resolved model live today.
+ */
+export declare const OTEL_GENAI_ATTRIBUTES: Readonly<Record<string, string>>;
+/** Internal envelope path to OpenInference attribute name. */
+export declare const OPENINFERENCE_ATTRIBUTES: Readonly<Record<string, string>>;
+/**
+ * Resolve the attribute table a catalog entry projects onto.
+ *
+ * `'none'` is a real, recorded decision — "this kind has no external
+ * equivalent" — not a missing value. It returns an empty table, never
+ * `undefined`, so a consumer never has to distinguish "no mapping" from "not
+ * asked".
+ */
+export declare function mappingForEntry(mapping: OtelMappingKind): Readonly<Record<string, string>>;

package/dist/observability/relationships.d.ts

@@ -0,0 +1,44 @@
+import type { ObservabilityEvent } from './envelope.js';
+/** Verdict from {@link validateEventRelationships}. */
+export type RelationshipValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    violations: string[];
+};
+/**
+ * Stable violation codes.
+ *
+ * Codes are machine-readable and must not be renamed once emitted — they are the
+ * join key a downstream consumer will group on. The suffix after `:` is the
+ * offending identifier or link index.
+ */
+export declare const RELATIONSHIP_VIOLATION_CODES: Readonly<{
+    unknownKind: "unknown_kind";
+    requiredWorkflowIdMissing: "required_workflow_id_missing";
+    forbiddenWorkflowIdPresent: "forbidden_workflow_id_present";
+    parentSpanNotAllowed: "parent_span_not_allowed";
+    parentSpanMissing: "parent_span_missing";
+    malformedParentSpanId: "malformed_parent_span_id";
+    linksNotAllowed: "links_not_allowed";
+    malformedLinkTraceId: "malformed_link_trace_id";
+    malformedLinkSpanId: "malformed_link_span_id";
+    validationFailed: "relationship_validation_failed";
+}>;
+/**
+ * Validate an event against its catalogued relationship rules.
+ *
+ * Checks, in order:
+ *   (a) the kind is catalogued;
+ *   (b) every `requiredWorkflowIds` entry is present;
+ *   (c) no `forbiddenWorkflowIds` entry is present (a present one means an ID
+ *       was manufactured upstream — issue #2029 item 2);
+ *   (d) a parent span is absent when the kind does not take one;
+ *   (e) a parent span is present when the kind requires one;
+ *   (f) a present parent span is a well-formed W3C span id;
+ *   (g) links are absent when the kind does not allow them;
+ *   (h) every link carries a well-formed trace/span id pair.
+ *
+ * @returns `{ ok: true }` or `{ ok: false, violations }`. Never throws.
+ */
+export declare function validateEventRelationships(event: ObservabilityEvent): RelationshipValidationResult;

package/dist/observability/sampling.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Sampling and metric-cardinality policy (issue #2029).
+ *
+ * Import rules: no filesystem, network, subprocess, or OTel SDK.
+ */
+/**
+ * Default sample rate.
+ *
+ * `1` = sample everything. This PR introduces no dropping: a drop that no
+ * consumer can see is exactly the silent data loss the issue names, and the
+ * consumer that would make a drop observable lands in #2047.
+ */
+export declare const DEFAULT_SAMPLE_RATE = 1;
+/**
+ * Decide whether a trace is sampled.
+ *
+ * **Deterministic by construction.** The decision is a pure function of the
+ * trace id and the rate: the LAST 8 hex characters of the trace id are read as
+ * an unsigned integer and compared against `rate * 0xffffffff`. The same trace
+ * therefore samples identically in every process, on every host, and across
+ * restarts — no shared state, no RNG, no coordination. That is what makes a
+ * sampled distributed trace complete rather than a set of disconnected
+ * fragments, and it is why the decision is not `Math.random()`.
+ *
+ * **CAVEAT — that property is currently VACUOUS in this system, and saying so
+ * is the point.** `createObservation` mints a FRESH `traceId` per event, with
+ * `links: []` and no `parentSpanId`, so every event today is its own
+ * single-span trace. At a rate below 1 the decision is therefore independent
+ * PER EVENT, not per logical trace: a "trace" never spans two events, so
+ * nothing can be kept whole or torn apart. Trace continuation — propagating one
+ * trace id across the events that belong together — is #2047's work, and only
+ * then does trace-coherent sampling become a real property rather than a
+ * latent one. Nothing is dropped today regardless: {@link DEFAULT_SAMPLE_RATE}
+ * is `1`.
+ *
+ * **Fail-open.** Every unusable input returns `true`. Dropping an event because
+ * an id was malformed would lose data silently, which is the failure mode this
+ * contract exists to prevent. A non-finite rate also fails open, for the same
+ * reason: `NaN` would otherwise fall through both bounds and make every
+ * comparison `false`, silently dropping everything.
+ *
+ * @param traceId - 32 lowercase hex characters.
+ * @param rate - `>= 1` samples everything, `<= 0` samples nothing.
+ */
+export declare function shouldSample(traceId: string, rate: number): boolean;
+/**
+ * The only labels permitted on a metric.
+ *
+ * Every member is bounded: a small, enumerable set of values that cannot grow
+ * with traffic. The rule this enforces, from issue #2029: **IDs, paths, users,
+ * tasks, and repositories belong in traces and logs, not metric labels.** A
+ * single unbounded label multiplies the time-series count by its cardinality and
+ * takes a metrics backend down; the trace already carries that detail, keyed to
+ * the same event.
+ */
+export declare const METRIC_LABEL_ALLOWLIST: readonly string[];
+/** Verdict from {@link assertBoundedCardinality}. */
+export type CardinalityResult = {
+    ok: true;
+} | {
+    ok: false;
+    violations: string[];
+};
+/** Stable violation codes, suffixed with the offending label. */
+export declare const CARDINALITY_VIOLATION_CODES: Readonly<{
+    notAllowlisted: "label_not_allowlisted";
+    highCardinalityShape: "high_cardinality_label_shape";
+}>;
+/**
+ * Check a metric's label set against the allowlist and against high-cardinality
+ * shapes.
+ *
+ * RETURNS a verdict; never throws. A label can produce both codes — the shape
+ * check runs independently of the allowlist check so that a newly-allowlisted
+ * label with an unbounded shape is still reported.
+ */
+export declare function assertBoundedCardinality(labels: readonly string[]): CardinalityResult;

package/dist/summaries/schema.d.ts

@@ -95,10 +95,10 @@ export declare const PhaseArchitectureSummarySchema: z.ZodObject<{
 export type PhaseArchitectureSummary = z.infer<typeof PhaseArchitectureSummarySchema>;
 export declare const SupervisorFindingSchema: z.ZodObject<{
     severity: z.ZodEnum<{
+        critical: "critical";
         low: "low";
         medium: "medium";
         high: "high";
-        critical: "critical";
     }>;
     category: z.ZodString;
     agents: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -135,10 +135,10 @@ export declare const ArchitectureSupervisorReportSchema: z.ZodObject<{
     }>;
     findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
         severity: z.ZodEnum<{
+            critical: "critical";
             low: "low";
             medium: "medium";
             high: "high";
-            critical: "critical";
         }>;
         category: z.ZodString;
         agents: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/telemetry.d.ts

@@ -1,3 +1,4 @@
+import { createObservation, toLegacyTelemetryLine } from './observability/index.js';
 import type { DelegationCostFields } from './services/cost-accounting.js';
 export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activated' | 'delegation_begin' | 'delegation_end' | 'task_state_changed' | 'gate_passed' | 'gate_failed' | 'gate_parse_error' | 'reviewer_gate_decision' | 'phase_changed' | 'budget_updated' | 'model_fallback' | 'hard_limit_hit' | 'revision_limit_hit' | 'loop_detected' | 'no_op_strong_warning' | 'scope_violation' | 'qa_skip_violation' | 'heartbeat' | 'turbo_mode_changed' | 'auto_oversight_escalation' | 'environment_detected' | 'evidence_lock_acquired' | 'evidence_lock_contended' | 'evidence_lock_stale_recovered' | 'plan_ledger_cas_retry' | 'plan_md_write_failed' | 'snapshot_failed' | 'gate_denial_loop'
 /**
@@ -25,7 +26,7 @@ export type TelemetryEvent = 'session_started' | 'session_ended' | 'agent_activa
  * `prm_hard_stop` TRIGGER emitted by `src/prm/escalation.ts`. A trigger with
  * no matching delivery means the containment never reached the agent.
  */
- | 'prm_hard_stop_delivered';
+ | 'prm_hard_stop_delivered' | 'agent_conflict_detected';
 /** Stable classification for how a reviewer-gate decision was established. */
 export type ReviewerGateEvidenceKind = 'genuine' | 'fallback' | 'data_quality' | 'block';
 /**
@@ -157,4 +158,6 @@ export declare const _internals: {
     emit: typeof emit;
     rotateTelemetryIfNeeded: typeof rotateTelemetryIfNeeded;
     heartbeatListenerCount: () => number;
+    createObservation: typeof createObservation;
+    toLegacyTelemetryLine: typeof toLegacyTelemetryLine;
 };

package/dist/utils/arg-hash.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared primitives for hashing tool-call arguments (issue #2060 follow-ups
+ * F-009 / F-010).
+ *
+ * # Why this exists
+ *
+ * Two subsystems hash tool arguments to detect "the agent is repeating
+ * itself": `hashArgsForSpiral` in `hooks/adversarial-detector.ts` (spiral
+ * advisory) and `hashArgs` in `hooks/guardrails/file-authority.ts` (which
+ * feeds the consecutive-repetition circuit breaker in
+ * `hooks/guardrails/tool-before.ts` — a path that THROWS, not warns).
+ *
+ * Both need the same two primitives. They live here rather than as two inline
+ * copies for the same reason `src/utils/stable-stringify.ts` was extracted: a
+ * bug class that exists at two call sites must be fixed once, in one place,
+ * and tested once. Keep them here; do not re-inline a copy at a call site.
+ *
+ * The two call sites differ only in the OUTPUT SHAPE they need — the detector
+ * wants a compact base-36 string, file-authority wants a `number` — so
+ * `boundedBunHash` returns `bigint` (matching `bunHash`) and each caller
+ * formats it.
+ */
+/**
+ * Cap on the amount of input fed into `bunHash`.
+ *
+ * Both call sites run synchronously on a per-tool-call hot path, and payloads
+ * (patch bodies, file writes) can reach ~1 MB. Node's `bunHash` fallback
+ * (djb2, see `bun-compat.ts`) is genuinely reachable in production — the
+ * OpenCode plugin host and the Desktop sidecar can run under Node — and is
+ * O(n): ~141 ms for a 2 MB input versus ~5 ms for 64 KB. The threat model is
+ * "same tool, same args, repeatedly", not adversarial collision resistance,
+ * so bounding the hashed input keeps worst-case per-call cost flat.
+ *
+ * NOTE ON UNITS: this bounds `String.prototype.length`, i.e. UTF-16 code
+ * units, not encoded bytes. It is a cost bound, not a byte-exact limit; a
+ * non-BMP-heavy string can encode to more bytes than the name suggests. That
+ * is fine — the point is a fixed ceiling, and the ceiling is fixed.
+ */
+export declare const HASH_INPUT_CAP_BYTES: number;
+/**
+ * Reduces an arbitrarily long string to a bounded, length-prefixed
+ * head-and-tail sample suitable as hash input.
+ *
+ * ## Why not a bare prefix
+ *
+ * The obvious bound — `input.slice(0, CAP)` — makes every pair of inputs that
+ * share a `CAP`-length prefix hash identically. For the circuit-breaker call
+ * site that is a false-positive engine: ten consecutive large writes that
+ * share a boilerplate header but differ in their (appended) bodies look like
+ * ten identical calls and the breaker throws. Sampling the head AND the tail
+ * removes the whole append-collision class, and sampling the head removes the
+ * prepend-collision class, at exactly the same bounded cost.
+ *
+ * ## Why the length prefix is load-bearing
+ *
+ * It is not decoration. Without it the two branches below can collide across
+ * the cap boundary: an input of exactly `CAP` characters passes through
+ * untransformed, while a longer input produces a `CAP`-character head+tail
+ * concatenation — two different inputs, one identical hash input. Prefixing
+ * the true length separates the classes. It also makes the under-cap branch
+ * injective, so this transform adds ZERO collisions for inputs at or below
+ * the cap.
+ *
+ * ## Residual, accepted lossiness
+ *
+ * Two inputs longer than the cap collide only if they have the SAME total
+ * length AND the same first `CAP/2` characters AND the same last `CAP/2`
+ * characters, differing only in the discarded middle. That is unavoidable for
+ * any fixed-cost sampler and is the deliberate trade documented on
+ * `HASH_INPUT_CAP_BYTES`.
+ *
+ * Cannot throw: `String.prototype.slice` and template interpolation of a
+ * number are total.
+ */
+export declare function sampleForHash(input: string): string;
+/**
+ * `bunHash` over a bounded head+tail sample of `input`.
+ *
+ * Returns `bigint` (the `bunHash` shape) so each caller can format it for its
+ * own storage: the detector uses `.toString(36)`, file-authority uses
+ * `Number(...)`.
+ *
+ * Cannot throw for a string input: `sampleForHash` is total and `bunHash`
+ * on a string is `TextEncoder.encode` plus BigInt arithmetic (or `Bun.hash`)
+ * — no throwing path. Callers rely on this: both use it inside a `catch`
+ * block, where a second throw would escape into a hook.
+ */
+export declare function boundedBunHash(input: string): bigint;
+/**
+ * Shallow, non-recursive structural summary of a value's own enumerable keys,
+ * used only as a fallback discriminator when `stableCanonicalStringify`
+ * throws (issue #2060 follow-up F-009).
+ *
+ * Before this existed, both call sites answered an unstringifiable argument
+ * with a CONSTANT ('h:fallback' / `0`). That made every distinct-but-
+ * unserializable argument collide, so N consecutive calls with genuinely
+ * different arguments looked identical and fired a false positive — a spiral
+ * advisory in one case, a thrown circuit breaker in the other.
+ *
+ * Deliberately shallow (no recursion into nested values) so it cannot itself
+ * throw on the very inputs that broke `stableCanonicalStringify`: recursing
+ * into a cyclic reference would revisit the cycle, and BigInt values are
+ * handled fine by `typeof` / `String()` (unlike `JSON.stringify`, which
+ * throws on them). `Object.keys` and `typeof` cannot throw for ordinary
+ * objects; the outer try/catch guards only against exotic Proxy traps, and
+ * even then identical arguments still collide, so true-positive repetition
+ * detection is preserved.
+ *
+ * This is a DISCRIMINATOR, not an identity function. It is only ever used to
+ * break up false collisions on a detection path — never as a fail-closed
+ * identity (see the caller guidance on `stableCanonicalStringify`).
+ */
+export declare function coarseObjectDiscriminator(args: unknown): string;