@open-everywhere/core 0.1.0

package/dist/agent/routines/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../agent/routines/events.ts"],"names":[],"mappings":"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"}

package/dist/agent/routines/fire-audit.d.ts

@@ -0,0 +1,409 @@
+import { type AuditInput } from "../audit/audit.js";
+import type { TeamsMembershipUnresolved } from "../channels/teams-bridge.js";
+import { type Routine } from "./routine.js";
+/** The routine-forensics audit actions. Values are the stable dotted keys readers join on. */
+export declare const ROUTINE_AUDIT: {
+    /** A fired session ended — carries routineId + sessionId + outcome (THE forensic join). */
+    readonly fire: "routine.fire";
+    /** Due/matched but NOT dispatched, with a reason. Throttled. */
+    readonly skip: "routine.skip";
+    /** Dispatch attempted, delivery rejected — no session started, so no sessionId exists. */
+    readonly fireLost: "routine.fire_lost";
+    /** Self-disabled after the consecutive-failure threshold. */
+    readonly disabled: "routine.disabled";
+    /**
+     * OPE-253: this fire was BLOCKED — a configured session cost checkpoint refused it a consequential
+     * tool (spend/checkpoint.ts requireSessionContinuation). One row per stalled FIRE, written the
+     * moment it happens rather than folded onto that fire's `routine.fire` row at session end, for two
+     * reasons: a job that cannot act is exactly the one whose session may not end cleanly, and the row
+     * is the only immediate signal in a story whose whole defect is silence.
+     *
+     * NOT throttled, unlike {@link ROUTINE_AUDIT.skip}: it is already at most once per fire (the
+     * dispatcher clears `lastStallAt` at fire, and the recorder writes only on the first refusal of a
+     * fire), and fires are at least DISPATCH_TICK_MINUTES apart — so the natural rate is already the
+     * one a throttle would impose, and one row per blocked run is exactly the resolution a reader
+     * asking "how long has this been stuck?" needs.
+     */
+    readonly stalled: "routine.stalled";
+    /**
+     * OPE-147: a human asked for an OFF-SCHEDULE run (`run_routine_now`). Written at REQUEST time,
+     * by the requesting turn, so it is the one row that carries the REQUESTER — `routine.fire` is
+     * stamped with the synthetic {@link ROUTINE_DISPATCHER_PRINCIPAL} and structurally cannot say
+     * who asked. The run itself still produces its ordinary `routine.fire` row (carrying
+     * `manual: true`) when the fired session ends, so `fires7d` counts runs, not requests, and a
+     * request that never becomes a run — cancelled, over budget, target unresolvable — is visibly a
+     * request with no fire rather than a silently-missing one.
+     */
+    readonly runNow: "routine.run_now";
+    /**
+     * OPE-151: one or more of this fire's declared PRE-RUN COLLECTORS did not collect — refused for a
+     * permission the routine does not hold, unknown to this deployment's config, or broken at the read
+     * (routines/collector.ts). The fire STILL HAPPENED, with the failure named in its own message, so
+     * this row is what makes "the run saw nothing" and "the run could not look" different facts after
+     * the event as well as during it.
+     *
+     * THROTTLED, exactly like {@link ROUTINE_AUDIT.skip} and for the same reason. It is at most once
+     * per FIRE, and on the CLOCK leg fires are at least DISPATCH_TICK_MINUTES apart — but the pre-fire
+     * step runs on the EVENT fan-out too (routines/pre-fire.ts), once per matched delivery, and a
+     * delivery stream has no such spacing. A routine whose collector is permanently refused would
+     * otherwise turn a 200-delivery push burst into 200 chained audit inserts.
+     *
+     * The detail carries collector NAMES and closed-set REASONS, plus the recorded CAUSE of a read
+     * that threw — external text, capped by routines/collector.ts COLLECTOR_DETAIL_MAX_CHARS, which
+     * reaches this row and no model. Never a byte of a collected BODY.
+     */
+    readonly collectFailed: "routine.collect_failed";
+    /**
+     * OPE-1810: this fire's CREATOR-ELIGIBILITY room check could not answer, so the fire proceeded on
+     * the ruled fail-open. The row names which check and why it could not answer.
+     *
+     * 🔴 IT EXISTS BECAUSE A FAIL-OPEN AND A PASS OTHERWISE LEAVE THE SAME TRACE — none. The Teams
+     * room check addressed Graph with an id Graph does not take, so every fire took the fail-open arm
+     * silently and the leg read as a healthy, enforcing check for its whole life. An operator asking
+     * "is the creator check working?" now gets an answer from the rows THEMSELVES: a row means that
+     * fire was NOT checked, and its `suppressed` and `windowMs` fields say how many further fires in
+     * the window it stands for.
+     *
+     * 🔴 READ THE PRESENCE, NEVER THE ABSENCE. A fire with no row was not necessarily checked, and
+     * three arms make that so: this row is THROTTLED (below), so a standing unresolvable check writes
+     * one row an hour and the fires between it write none; the write is `.catch`-ed at the call site,
+     * so a store failure drops the row and keeps the fire; and schedules/dispatch.ts resolves a
+     * throwing eligibility probe to `{ eligible: true }`, which fires with no row at all.
+     * `docs/deploy/surfaces/teams.md` states the same direction for the operator.
+     *
+     * THROTTLED, exactly like {@link ROUTINE_AUDIT.skip} and for the same reason: the honest shape of
+     * this row is a standing condition — a missing Graph consent, a team whose group id will not
+     * resolve — which would otherwise write one row per fire, forever, saying the same thing.
+     */
+    readonly eligibilityUnresolved: "routine.eligibility_unresolved";
+};
+/** Why a due/matched routine was not dispatched. Closed set — readers switch on it. */
+export type RoutineSkipReason = 
+/** Event fan-out only: past the per-delivery fan-out cap, and an event has no "later". */
+"fanout_cap"
+/**
+ * Either leg (OPE-275): the scope's spend cap is reached (spend/check.ts scopeOverBudget).
+ * On the clock leg the schedule still advances, so the routine retries at its own cadence; on
+ * the event fan-out the delivery is simply skipped — an event has no "later" — and the routine
+ * fires again the moment its scope is back under budget. A skip, never a strike: being over
+ * budget is the deployment's state, not the routine's mistake.
+ */
+ | "over_budget"
+/** Either leg: no wired channel/target for the routine's surface (dry-run, fail-closed). */
+ | "unresolved_target"
+/**
+ * Event fan-out only (OPE-163): the STORED filter no longer validates against its source's live
+ * normalizer — the honest case is a `matchKeys` shrink across a deploy. Treated as NO MATCH, and
+ * deliberately NOT as a routine failure: config drift is not the routine's fault, and a strike
+ * here would let one config change 3-strike-disable a whole fleet via lifecycle.ts.
+ */
+ | "filter_invalid"
+/**
+ * Event fan-out only (OPE-163): the filter matched but the READ GRANT said no — this partition's
+ * effective access does not grant read on the scope the delivery proved (routines/event-authz.ts).
+ * Also covers the fail-closed cases: no grant adapter for the source, an empty scope path, and an
+ * unresolvable config. Audited rather than silent because "matches but never fires" is otherwise
+ * indistinguishable from "never matches", and both look like a dead routine.
+ */
+ | "grant_refused"
+/**
+ * Event fan-out only (OPE-178): OUR grant said yes and the VENDOR said no — a 401/403 hydrating
+ * the entity the delivery pointed at. That is GRANT DRIFT: access changed after the grant was
+ * written, so the two authorities now disagree and only the vendor's answer is authoritative.
+ *
+ * 🔴 IT IS A SKIP, NOT A FAILURE, AND THAT IS LOAD-BEARING. Routed here rather than through
+ * {@link auditRoutineFireLost} precisely because a skip can never fold onto the routine: if a
+ * hydration 403 counted toward lifecycle.ts's three-strike self-disable, a repo the agent lost
+ * access to would silently disable every routine watching it — a permissions change becoming
+ * permanent, invisible loss of automation, blamed on the routine. Losing access is the
+ * DEPLOYMENT's state change, not the routine's mistake, so the routine stays armed and starts
+ * working again by itself the moment access returns.
+ */
+ | "grant_drift"
+/**
+ * Event fan-out only (OPE-166): the read grant said yes, and the ROOM said no — the routine's own
+ * channel resolved to an OBSERVED `guest` audience floor, so org-internal trigger-sourced content
+ * may not be disclosed into it (routines/fire-disclosure.ts). "May the domain read this" and "is
+ * this room a fit audience for it" are different questions; this row is the second one's answer.
+ *
+ * A SKIP, not a failure, for the same load-bearing reason as `grant_drift` above: a channel
+ * becoming externally shared is the DEPLOYMENT's state change, not the routine's mistake, and
+ * folding it onto the routine would let one Slack Connect invite three-strike-disable every
+ * routine in the room. The routine stays armed and resumes by itself when the room is internal
+ * again.
+ *
+ * Uniquely among these reasons it is ALSO announced in the room (a content-free, host-composed
+ * line), because a silent withhold on an UNATTENDED path is exactly the "why didn't it tell me"
+ * failure the audit wedge exists to prevent. The announcement rides THIS row's throttle — it is
+ * posted only when {@link auditRoutineSkip} actually emitted — so there is one visibility
+ * mechanism with one rate limit, not two.
+ */
+ | "audience_floor"
+/**
+ * Clock leg only (OPE-506, routines/fire-eligibility.ts): the routine's CREATOR is no longer a
+ * member of the room the fire posts into — Tag's own policy, adopted verbatim ("stop firing if
+ * the creator is removed from the channel"). A SKIP, never a failure, and deliberately different
+ * from the creator LEAVING THE ORG (which does not stop the routine at all — it fires on the
+ * room's own authority): this is the narrower, room-scoped removal.
+ */
+ | "creator_removed_from_room"
+/**
+ * Clock leg only (OPE-506): the routine's CREATOR's account is deactivated/deleted outright
+ * (Slack `users.info.deleted`) — a stronger signal than losing internal-member standing, checked
+ * independently of room membership. A SKIP: the room itself is untouched, so a later fire (once
+ * a different creator's standing question no longer applies, or the account is restored) can
+ * still succeed.
+ */
+ | "creator_account_inactive"
+/**
+ * Either leg (OPE-1602): a BREAK-GLASS HALT covers this routine's address, so the fire is skipped
+ * (routines/fire-halt.ts). A SKIP, never a failure, for the same load-bearing reason `over_budget`
+ * is one: a halt is the DEPLOYMENT's posture, not the routine's mistake, and folding it onto the
+ * routine would let one incident three-strike-disable every routine in the org. The routine stays
+ * armed and fires again by itself once an admin runs `resume`.
+ */
+ | "halted"
+/**
+ * Either leg (OPE-151): the routine's declared CONDITION GATE said no — the predicate read this
+ * run's pre-run collection and the condition it guards is not true, so no session was created and
+ * nothing was spent (routines/gate.ts). The row carries the gate's name and the one line the
+ * predicate gave, which is the only place a human learns WHY a routine that looks healthy has not
+ * run.
+ *
+ * A SKIP, never a failure, and here that is the mechanism rather than a mercy: a gate exists
+ * precisely so a routine can decline to run, so folding a decline onto `consecutiveFailures` would
+ * three-strike-disable every routine that uses one correctly. It is also the reason an
+ * UNRESOLVABLE gate lands here — the failing-closed arms (an unknown name, a throwing predicate)
+ * write this same row, so a broken gate reports itself hourly instead of stopping a routine in
+ * silence.
+ *
+ * Throttled with every other skip reason ({@link SKIP_WINDOW_MS}): a routine whose condition is
+ * false all day writes one row an hour carrying a `suppressed` count, not one per tick.
+ */
+ | "condition_gate";
+/** At most ~one skip row per (routine, reason) per window. An hour: long enough that a standing
+ *  misconfiguration reports hourly rather than every tick/delivery, short enough that the count
+ *  stays legible. */
+export declare const SKIP_WINDOW_MS: number;
+/**
+ * The routine's own partition segments, for an audit row about it. A routine's surfaceKey is
+ * `platform/workspace/surface` — the same split schedules/dispatch.ts partitionOf uses. (This
+ * replaces the local copy github-fanout.ts carried: one shape, one place.)
+ */
+export declare function routineAuditScope(r: Pick<Routine, "surfaceKey">): {
+    platform: string;
+    workspace: string;
+    surface: string;
+};
+/** Principal stamped on a routine-lifecycle row. A fire has NO acting human — the dispatcher is
+ *  the actor — so this is a synthetic, low-cardinality service identity, never the creator (who
+ *  did not act at fire time). The event leg passes its own (`github:webhook`). */
+export declare const ROUTINE_DISPATCHER_PRINCIPAL = "routine:dispatcher";
+/** Injectable edges — live defaults are appendAudit + the operational store's markEventSeen. */
+export interface RoutineAuditDeps {
+    readonly audit?: (entry: AuditInput) => Promise<void>;
+    readonly markSeen?: (org: string, key: string, atIso: string, ttlMs: number) => Promise<boolean>;
+    readonly now?: () => Date;
+    /** Overrides the synthetic dispatcher principal (the event leg stamps `github:webhook`). */
+    readonly principalId?: string;
+}
+/** Test seam — drop all in-process suppression counters. */
+export declare function resetRoutineSkipThrottle(): void;
+/** The throttle identity. Both parts are OE-minted (`r-xxxxxxxx` from routines/store.ts
+ *  newRoutineId, and a closed reason set) — never a caller-supplied string, so a hostile delivery
+ *  stream cannot mint fresh keys to defeat the throttle (webhooks/reject-audit.ts §"THE THROTTLE
+ *  KEY MUST NOT CONTAIN AN ATTACKER-CHOSEN STRING"). */
+export declare function skipThrottleKey(routineId: string, reason: RoutineSkipReason): string;
+/** The throttle identity for {@link auditCollectorFailures} (OPE-151). Same construction and the
+ *  same reason: the only variable part is an OE-minted routine id, so a hostile delivery stream
+ *  cannot mint fresh keys to defeat the throttle. */
+export declare function collectFailedThrottleKey(routineId: string): string;
+/**
+ * A due/matched routine was NOT dispatched. THROTTLED: returns true when a row was emitted, false
+ * when it was suppressed (counted onto the next emitted row's `suppressed` field, so the throttle
+ * never hides its own existence).
+ *
+ * FAIL-OPEN on a throttle-store error — emit the row. The throttle and the audit write hit the
+ * SAME store, so a markEventSeen failure means the append is about to fail harmlessly anyway;
+ * failing closed would instead silence genuine skip auditing on any transient blip.
+ */
+export declare function auditRoutineSkip(r: Routine, reason: RoutineSkipReason, extra?: Readonly<Record<string, unknown>>, deps?: RoutineAuditDeps): Promise<boolean>;
+/** Which creator-eligibility check could not answer. A closed set — readers switch on it, and it is
+ *  what keeps one platform's fail-open distinguishable from another's. */
+export type EligibilityCheckName = "teams_room_membership";
+/** Why it could not answer. Typed as the PROBE's own closed set rather than as `string`, so the
+ *  vocabulary the docs promise a reader is the vocabulary the seam actually admits — a later
+ *  platform leg adds its causes to a union here, never free text at the call site. */
+export type EligibilityUnresolvedCause = TeamsMembershipUnresolved;
+/**
+ * THE CREATOR CHECK DID NOT BLOCK THIS FIRE (OPE-1810): a creator-eligibility check could not
+ * answer, and the ruling is that eligibility does not stop the fire on that arm. The row says the
+ * fire was not really CHECKED, never that it ran — a later gate on the same tick (the spend cap)
+ * can still decline it, and that decline writes its own `routine.skip`. `cause` is the probe's own closed-set reason (the Teams
+ * leg's `TeamsMembershipUnresolved`), so an operator reads WHY from the row — a missing Graph
+ * consent and a roster too large to finish are different problems with different remedies.
+ *
+ * Written only when a check was actually ATTEMPTED and came back unresolved. A fire whose creator
+ * was confirmed present writes nothing, and neither does a platform with no check at all, so the
+ * row's presence means "this fire was not really checked" rather than "this fire ran".
+ *
+ * Fail-soft and throttled like every other row here: recording that a check went unanswered must
+ * never break the fire it is recording, and a standing misconfiguration must not write a row a tick.
+ */
+export declare function auditRoutineEligibilityUnresolved(r: Routine, detail: {
+    readonly check: EligibilityCheckName;
+    readonly cause: EligibilityUnresolvedCause;
+}, deps?: RoutineAuditDeps): Promise<boolean>;
+/**
+ * A fire's PRE-RUN COLLECTORS did not all collect (OPE-151). Written once per fire, before the
+ * delivery, and only when at least one collector failed — a fire whose reads all worked writes
+ * nothing, so this row's existence is the signal.
+ *
+ * 🔴 NAMES AND REASONS ONLY, NEVER A BODY. A collected body is external content; the failure reason
+ * is host-composed prose about a read that did not happen (routines/collector.ts
+ * describeCollectorFailure), so it carries and the body never could. The same names/ids-only
+ * discipline `routine.fire_attrs_sent` and `turn.tool_gated` keep.
+ *
+ * Fail-soft like every other row here: recording that a read broke must never break the fire.
+ */
+export declare function auditCollectorFailures(r: Routine, failures: readonly {
+    readonly name: string;
+    readonly failure: string;
+    readonly detail?: string;
+}[], deps?: RoutineAuditDeps): Promise<boolean>;
+/** THE JOIN. A fired session ended: this row names the routine AND the session, so a human (or the
+ *  agent itself, via list_routines) can go from "r-1a2b3c4d" to that fire's transcript.
+ *
+ *  `silent` (OPE-149) is stamped for a `report:{kind:"silent"}` routine, and it is what makes this
+ *  row LOAD-BEARING rather than merely useful. A silent routine posts nothing by design, so it can
+ *  never appear in the `lastPostedAt` join below — without the flag, a healthy silent fire and a
+ *  posting routine that has gone quiet look identical in the forensics, and "did the nightly job
+ *  run this week?" has no answer at all. Positive-only, so a posting routine's row is unchanged. */
+export declare function auditRoutineFire(r: Routine, sessionId: string, outcome: string, extra?: Readonly<Record<string, unknown>>, deps?: RoutineAuditDeps): Promise<void>;
+/** A fire whose `receive()` was REJECTED. No session started, so there is no session id — the row
+ *  says so explicitly rather than omitting the field and reading as "we forgot to record it". */
+export declare function auditRoutineFireLost(r: Routine, error: string, deps?: RoutineAuditDeps): Promise<void>;
+/**
+ * THIS FIRE WAS BLOCKED (OPE-253) — a configured session cost checkpoint refused it a consequential
+ * tool. `tool` is the OE tool name the guard was called with (host-supplied, from a closed set of
+ * authored tool slugs — never model text); `reason` is the checkpoint's own host-composed line
+ * ("this session reached its cost checkpoint (…tokens)"), and `stalledFires` is the run this fire
+ * extends, so the row answers "is this the first time, or the third?" without a second read.
+ *
+ * There is no `sessionId` argument on purpose. The guard runs at a tool execute, which is inside
+ * `turnStep` — the same process that has `ctx.session.id` — but wiring it in would make the recorder's
+ * signature depend on the guard's ctx shape, and the `routine.fire` join row written at session end
+ * already carries the (routineId, sessionId) pair for this same fire. One join, one row that owns it.
+ */
+export declare function auditRoutineStalled(r: Routine, detail: {
+    readonly tool: string;
+    readonly reason: string;
+    readonly stalledFires: number;
+}, deps?: RoutineAuditDeps): Promise<void>;
+/**
+ * A human asked for an off-schedule run (OPE-147). `requestedBy` is a REAL principal — the whole
+ * reason this row exists separately from `routine.fire`, which can only ever name the dispatcher.
+ * `nextRunAt` is the instant the request moved the routine to, so the row also answers "when will
+ * it actually happen" without a second lookup.
+ */
+export declare function auditRoutineRunNow(r: Routine, requestedBy: string, nextRunAt: string, deps?: RoutineAuditDeps): Promise<void>;
+/** The routine self-disabled (consecutive-failure threshold). At most once per routine, ever.
+ *
+ *  `reason` is the HOST-composed `disabledReason` ("auto-disabled after 3 consecutive failures") —
+ *  it says the routine hit the threshold, not what was wrong. `extra` is where the answer to the
+ *  second question goes: OPE-177 passes `declaredFailure`, the final run's own words for why the
+ *  work did not happen, so the one row a human reads after "why did this stop?" carries a diagnosis
+ *  rather than only a count. Kept as a separate field, never merged into `reason`, because `reason`
+ *  is also what routines/disable-notice.ts POSTS INTO THE ROOM and it must stay host-composed. */
+export declare function auditRoutineDisabled(r: Routine, reason: string, consecutiveFailures: number, sessionId: string | undefined, extra?: Readonly<Record<string, unknown>>, deps?: RoutineAuditDeps): Promise<void>;
+/** The seven-day forensic window every routine-history read uses. Long enough to cover a daily
+ *  routine's week and a weekly routine's last run; short enough that the underlying scans stay
+ *  cheap and well inside the usage_events retention floor (90 days). */
+export declare const FORENSIC_WINDOW_MS: number;
+/** Row ceiling on each audit scan behind {@link readRoutineForensics}. Counts are therefore "over
+ *  at most the newest N rows in the window" — stated, not silently approximated. Generous enough
+ *  that a realistic surface never reaches it (a 15-minute routine fires 672 times a week). */
+export declare const FORENSIC_SCAN_LIMIT = 5000;
+/** What the durable rows can now say about one routine. Every field is null/0 when the routine
+ *  simply has not run in the window — which is itself the answer to "did it run?". */
+export interface RoutineForensics {
+    /** Session id of the most recent COMPLETED fire — the handle for
+     *  `GET /control/v1/session/:id/transcript`. Null if none in the window. */
+    readonly lastSessionId: string | null;
+    /** When that fire's session ended (ISO). */
+    readonly lastFireAt: string | null;
+    /** When a fire of this routine most recently POSTED anything (ISO). Distinguishes "ran and had
+     *  nothing to say" from "ran and told you" — joined through `reply.post`'s sessionId, which is
+     *  the only link that row carries. */
+    readonly lastPostedAt: string | null;
+    /** Completed fires in the window. Zero, with a nextRunAt already in the past, is the shape of
+     *  "it never ran" — the question that had no answer before this ticket. */
+    readonly fires7d: number;
+    /** Every token attributed to this routine in the window (input + output + both cache legs) —
+     *  the full model cost, not a billable subset. */
+    readonly tokens7d: number;
+}
+/** The zero reading — a routine with no durable trace in the window. */
+export declare function emptyRoutineForensics(): RoutineForensics;
+/**
+ * Read the durable trace for every routine on ONE surface, keyed by routine id.
+ *
+ * SCOPING: every read is pinned to the caller's own (org, platform, workspace, surface) — the
+ * partition the caller already resolved. This function never widens, so it cannot be used to see
+ * another surface's or another org's routines. That is why extending list_routines with it does not
+ * touch the cross-org exposure OPE-146 item 3 tracks: that one is `routines_list` in
+ * control/server.ts over `listAllRoutines()`, a different code path with a different reader.
+ *
+ * FAIL-SOFT: any store error degrades to an EMPTY map rather than throwing — a forensics read must
+ * never break the tool that is merely decorating its output with it.
+ */
+export declare function readRoutineForensics(scope: {
+    readonly org: string;
+    readonly platform: string;
+    readonly workspace: string;
+    readonly surface: string;
+    readonly surfaceKey: string;
+}, now?: Date): Promise<Map<string, RoutineForensics>>;
+/** One `routine.fire` row, flattened — the per-fire view {@link readRoutineForensics} collapses into
+ *  a single "latest" slot. `sessionId` is non-null by construction: a fire row without one is a
+ *  malformed row and is dropped by the reader rather than surfaced as an unreadable fire. */
+export interface RoutineFireRow {
+    readonly routineId: string;
+    readonly sessionId: string;
+    /** When the fired session ENDED (the row's own timestamp). */
+    readonly at: string;
+    readonly outcome: string | null;
+    /** A `report:{kind:"silent"}` routine's fire — it posted nothing BY DESIGN. */
+    readonly silent: boolean;
+}
+/**
+ * The fires of ONE routine on ONE surface, newest-first — the resolver behind OPE-153's
+ * same-channel transcript read.
+ *
+ * 🔴 THIS FUNCTION IS AN AUTHORIZATION ORACLE, not a convenience reader, and two properties make it
+ * one:
+ *
+ *  1. IT IS PARTITION-PINNED, LIKE {@link readRoutineForensics}. Every fire row was written with the
+ *     firing routine's own (org, platform, workspace, surface) — so a routineId belonging to another
+ *     channel simply RESOLVES TO NOTHING here. The same-channel boundary is therefore the SCOPE OF
+ *     THE LOOKUP, not a comparison a caller could forget to make. That is deliberate: a check that
+ *     can be skipped eventually is, and a caller cannot skip the shape of a query.
+ *
+ *  2. IT FAILS CLOSED, WHERE ITS SIBLING FAILS SOFT. readRoutineForensics swallows store errors and
+ *     degrades to an empty map, because it only DECORATES a listing. This one gates a read, so a
+ *     store error must not be indistinguishable from "that routine never fired here" — it throws,
+ *     and the caller refuses. Returning `[]` on an error would be fail-closed in effect but would
+ *     tell the operator the wrong story about why.
+ *
+ * Window + scan ceiling are the shared forensic ones ({@link FORENSIC_WINDOW_MS} /
+ * {@link FORENSIC_SCAN_LIMIT}), so "what a transcript read can reach" is exactly "what the run
+ * history in `list_routines` already showed" — the tool can never see further back than the listing
+ * that told the model the routine exists.
+ */
+export declare function listRoutineFires(scope: {
+    readonly org: string;
+    readonly platform: string;
+    readonly workspace: string;
+    readonly surface: string;
+}, routineId: string, now?: Date): Promise<RoutineFireRow[]>;
+//# sourceMappingURL=fire-audit.d.ts.map

package/dist/agent/routines/fire-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fire-audit.d.ts","sourceRoot":"","sources":["../../../agent/routines/fire-audit.ts"],"names":[],"mappings":"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"}