@wrongstack/core 0.298.0 → 0.298.2

package/dist/coordination/index.js

@@ -13220,8 +13220,16 @@ function resolveSubagentModelTarget(config, role, opts = {}) {
   const resolution = resolveModelMatrixResolution(config.modelMatrix, role);
   const matrixTarget = resolveModelTargetFromEntry(config, resolution?.entry);
   const implementationTarget = opts.implementationTarget ?? resolveImplementationModelTarget(config);
+  const isAvailable = (providerId, model) => {
+    if (!opts.statusTracker) return true;
+    if (!providerId || !model) return true;
+    return opts.statusTracker.isAvailable(providerId, model);
+  };
+  const matrixEffective = materializeTarget(config, matrixTarget);
+  const matrixIsAvailable = !matrixEffective || isAvailable(matrixEffective.provider, matrixEffective.model);
   if (!roleNeedsIndependentReviewModel(role)) {
     if (!matrixTarget) return void 0;
+    if (!matrixIsAvailable) return void 0;
     return {
       ...matrixTarget,
       source: "matrix",
@@ -13230,16 +13238,27 @@ function resolveSubagentModelTarget(config, role, opts = {}) {
   }
   const matrixRef = materializeTarget(config, matrixTarget);
   if (resolution?.source === "role" || resolution?.source === "phase") {
-    return matrixTarget ? { ...matrixTarget, source: "matrix", matrixSource: resolution.source } : void 0;
+    if (!matrixTarget) return void 0;
+    if (!matrixIsAvailable) return void 0;
+    return {
+      ...matrixTarget,
+      source: "matrix",
+      matrixSource: resolution.source
+    };
   }
   if (matrixRef && !sameModelReference(matrixRef, implementationTarget)) {
+    if (!matrixIsAvailable) return void 0;
     return {
       ...matrixTarget ?? {},
       source: "matrix",
       matrixSource: resolution?.source
     };
   }
-  const diverse = chooseDiverseModelTarget(config, implementationTarget);
+  const diverse = chooseDiverseModelTargetWithTracker(
+    config,
+    implementationTarget,
+    opts.statusTracker
+  );
   if (diverse) {
     return {
       provider: diverse.provider,
@@ -13253,6 +13272,7 @@ function resolveSubagentModelTarget(config, role, opts = {}) {
     };
   }
   if (!matrixTarget) return void 0;
+  if (!matrixIsAvailable) return void 0;
   return {
     ...matrixTarget,
     source: "matrix",
@@ -13289,6 +13309,14 @@ function chooseDiverseModelTarget(config, avoid) {
   candidates.sort((a, b) => modelDiversityScore(b, avoid) - modelDiversityScore(a, avoid));
   return candidates[0];
 }
+function chooseDiverseModelTargetWithTracker(config, avoid, tracker) {
+  if (!tracker) return chooseDiverseModelTarget(config, avoid);
+  const ranked = collectConfiguredModelTargets(config).filter((candidate) => !sameModelReference(candidate, avoid)).sort((a, b) => modelDiversityScore(b, avoid) - modelDiversityScore(a, avoid));
+  for (const candidate of ranked) {
+    if (tracker.isAvailable(candidate.provider, candidate.model)) return candidate;
+  }
+  return void 0;
+}
 function collectConfiguredModelTargets(config) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
@@ -20402,6 +20430,36 @@ function isMailboxLeader(agentId, role) {
 function isMailboxMessageVisibleTo(message, agentId, role) {
   return message.audience !== "leaders" || isMailboxLeader(agentId, role);
 }
+function isAffectedBySessionAffinity(message) {
+  return message.sessionAffinity !== void 0;
+}
+async function acceptMailboxMessageForSession(message, currentSessionId, ctx) {
+  if (!isAffectedBySessionAffinity(message)) return true;
+  const affinity = message.sessionAffinity;
+  if (affinity === null || typeof affinity !== "object" || Array.isArray(affinity)) {
+    return false;
+  }
+  if (affinity.sessionId !== void 0 && typeof affinity.sessionId !== "string" || affinity.reportId !== void 0 && typeof affinity.reportId !== "string") {
+    return false;
+  }
+  if (!currentSessionId) {
+    return ctx?.allowUnscoped === true;
+  }
+  if (typeof affinity.sessionId === "string" && affinity.sessionId.length > 0) {
+    if (affinity.sessionId !== currentSessionId) return false;
+    return true;
+  }
+  if (affinity.reportId && ctx?.resolveChimeraReportSessionId) {
+    try {
+      const resolved = await ctx.resolveChimeraReportSessionId(affinity.reportId);
+      if (resolved === currentSessionId) return true;
+      if (resolved !== void 0) return false;
+    } catch {
+    }
+  }
+  if (ctx?.allowUnscoped === true) return true;
+  return false;
+}
 function validateSendType(type, to) {
   if (type === "control") {
     throw new TypeError(
@@ -21025,7 +21083,7 @@ function makeMailboxTool(opts = {}) {
         case "ack":
           return executeAck(mb, callerId, i);
         case "query":
-          return executeQuery(mb, callerId, identity.role, i);
+          return executeQuery(mb, callerId, callerSessionId, identity.role, i);
         case "status":
           return executeStatus(mb);
         case "online":
@@ -21054,12 +21112,18 @@ async function executeCheck(mb, agentId, sessionId, aliases, role, i) {
     )
   );
   const seen = /* @__PURE__ */ new Set();
-  const messages = batches.flat().filter((m) => {
+  const candidates = batches.flat().filter((m) => {
     if (seen.has(m.id)) return false;
     if (!isMailboxMessageVisibleTo(m, agentId, role)) return false;
     seen.add(m.id);
     return true;
   });
+  const messages = [];
+  for (const m of candidates) {
+    if (await acceptMailboxMessageForSession(m, sessionId)) {
+      messages.push(m);
+    }
+  }
   const acked = markRead || completed ? await mb.ackMany({
     acks: messages.map((m) => ({
       messageId: m.id,
@@ -21140,7 +21204,7 @@ async function executeAck(mb, agentId, i) {
     summary: `Message ${messageId} acknowledged. Read by ${Object.keys(updated.readBy).length} agent(s), Completed: ${updated.completed}.`
   };
 }
-async function executeQuery(mb, agentId, role, i) {
+async function executeQuery(mb, agentId, sessionId, role, i) {
   const limit = i.limit ?? 50;
   const messages = await mb.query({
     to: i.to,
@@ -21153,7 +21217,12 @@ async function executeQuery(mb, agentId, role, i) {
     sessionId: i.sessionId,
     limit
   });
-  const visible = messages.filter((message) => isMailboxMessageVisibleTo(message, agentId, role));
+  const visible = [];
+  for (const message of messages) {
+    if (isMailboxMessageVisibleTo(message, agentId, role) && await acceptMailboxMessageForSession(message, sessionId)) {
+      visible.push(message);
+    }
+  }
   return { ok: true, count: visible.length, messages: visible, summary: `${visible.length} message(s).` };
 }
 async function executeStatus(mb) {
@@ -21944,6 +22013,14 @@ var SEND_ALLOWED_FIELDS = /* @__PURE__ */ new Set([
   "senderSessionId",
   "ttlMs",
   "taskContext"
+  // 'sessionAffinity' is NOT in the allow-list. The trust-line contract:
+  // session-affinity tokens are stamped ONLY by trusted internal callers
+  // (chimera/auto-review pipelines) that call `mailbox.send()` directly
+  // and never go through this boundary codec. Allowing the field at the
+  // boundary would let any actor with `mail.send.informational` stamp
+  // another session's id and bypass the receiver-side filter. The
+  // receiver trusts the sender-asserted `sessionId`; the boundary must
+  // refuse the field entirely.
 ]);
 var ACK_ALLOWED_FIELDS = /* @__PURE__ */ new Set([
   "messageId",
@@ -21980,7 +22057,15 @@ function parseMailboxSendInput(payload, actor) {
   const priority = validatePriority(rawPriority);
   const audience = validateAudience(payload["audience"]);
   const replyTo = optionalString2(payload, "replyTo", "send");
-  return { to, type: typeResult.type, subject, body, priority, audience, replyTo };
+  return {
+    to,
+    type: typeResult.type,
+    subject,
+    body,
+    priority,
+    audience,
+    replyTo
+  };
 }
 function parseMailboxQueryInput(payload, actor) {
   assertCapability(actor, "mail.read.self", "query");

package/dist/coordination/mail-tools.d.ts

@@ -75,12 +75,12 @@ export declare function makeMailSendTool(opts?: MailToolsOptions): {
         required: string[];
     };
     execute(input: unknown, ctx: Context): Promise<{
-        messageId?: never;
-        to?: never;
-        summary?: never;
         ok: boolean;
         error: string;
+        messageId?: never;
         from?: never;
+        to?: never;
+        summary?: never;
     } | {
         error?: never;
         ok: boolean;

package/dist/coordination/mailbox-codecs.d.ts

@@ -56,7 +56,7 @@ export declare function parseMailboxSendInput(payload: Record<string, unknown>,
  * Queries tolerate unknown fields (forward compatibility for read-only clients).
  * Actor-derived recipient forms are NOT overridden by body-supplied `readerRole`.
  *
- * @throws {MailboxValidationError} on validation failure.
+ * @throws {MailboxValidationError} on any validation failure.
  */
 export declare function parseMailboxQueryInput(payload: Record<string, unknown>, actor: MailboxActorContext): MailboxQuery;
 /**

package/dist/coordination/mailbox-project-server.js

@@ -1520,6 +1520,34 @@ function parseTaskContext(value) {
     ...status === void 0 ? {} : { status }
   };
 }
+function parseSessionAffinity(value) {
+  if (value === void 0) return void 0;
+  if (!isRecord2(value)) {
+    throw new TypeError('mailbox message field "sessionAffinity" must be an object');
+  }
+  const sessionId = value["sessionId"];
+  const reportId = value["reportId"];
+  const kind = optionalString(value, "kind");
+  if (sessionId !== void 0) {
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+      throw new TypeError("mailbox message sessionAffinity.sessionId must be a non-empty string");
+    }
+    return {
+      sessionId,
+      ...optionalString(value, "reportId"),
+      ...kind
+    };
+  }
+  if (typeof reportId !== "string" || reportId.length === 0) {
+    throw new TypeError(
+      "mailbox message sessionAffinity.reportId must be a non-empty string when sessionId is absent"
+    );
+  }
+  return {
+    reportId,
+    ...kind
+  };
+}
 function parseMailboxMessage(value) {
   if (!isRecord2(value)) throw new TypeError("mailbox message must be an object");
   const to = value["to"] === void 0 ? "" : requiredString(value, "to");
@@ -1529,6 +1557,7 @@ function parseMailboxMessage(value) {
   }
   const taskContext = parseTaskContext(value["taskContext"]);
   const audience = parseAudience(value["audience"]);
+  const sessionAffinity = parseSessionAffinity(value["sessionAffinity"]);
   return {
     id: requiredString(value, "id"),
     from: requiredString(value, "from"),
@@ -1549,7 +1578,8 @@ function parseMailboxMessage(value) {
     ...optionalString(value, "replyTo"),
     ...optionalString(value, "senderSessionId"),
     ...optionalString(value, "expiresAt"),
-    ...taskContext === void 0 ? {} : { taskContext }
+    ...taskContext === void 0 ? {} : { taskContext },
+    ...sessionAffinity === void 0 ? {} : { sessionAffinity }
   };
 }
 function isAckRecord(value) {
@@ -2620,6 +2650,7 @@ var SqliteMailbox = class {
       ...input.replyTo !== void 0 ? { replyTo: input.replyTo } : {},
       ...input.taskContext !== void 0 ? { taskContext: input.taskContext } : {},
       ...input.senderSessionId !== void 0 ? { senderSessionId: input.senderSessionId } : {},
+      ...input.sessionAffinity !== void 0 ? { sessionAffinity: input.sessionAffinity } : {},
       ...input.ttlMs !== void 0 ? { expiresAt: new Date(Date.now() + input.ttlMs).toISOString() } : {}
     };
     this.persistMessage(message);

package/dist/coordination/mailbox-types.d.ts

@@ -88,7 +88,7 @@ export { MAILBOX_TYPE_PROPERTIES, type MailboxMessageType, type MailboxTypeCateg
  * The mailbox system enforces these dispatch rules:
  *
  * 1. **Send-side**: `mail_send` auto-defaults the type: `broadcast` when
- *    `to` is `"*"` or `"@session::..."`, otherwise `note`.
+ *    `to` is `"*"` or `"@session:..."`, otherwise `note`.
  * 2. **Send-side validation**: `assign` always requires a specific `to`
  *    (not `"*"`). `control` is reserved for runtime use — agents passing it
  *    via the tool surface will be rejected.
@@ -98,8 +98,8 @@ export { MAILBOX_TYPE_PROPERTIES, type MailboxMessageType, type MailboxTypeCateg
  * 4. **Control isolation**: `control`-type messages are filtered by
  *    `injectPendingMailboxMessages()` and NEVER enter the folded
  *    conversation block — they are out-of-band signals only.
- * 5. **Background routing**: in `background` delivery mode, only
- *    `ACTIONABLE_BACKGROUND_TYPES` (`steer`, `ask`, `assign`, `result`,
+ * 5. **Background routing**: in `background` delivery mode, only the
+ *    actionable message types (`steer`, `ask`, `assign`, `result`,
  *    `review`) are escalated; `note`, `btw`, `status`, and `broadcast`
  *    are suppressed to minimise disruption during tool work.
  * 6. **Awareness polling**: `btw` messages intercepted by background
@@ -134,6 +134,100 @@ export declare function mailboxIdentityBase(agentId: string): string;
 export declare function isMailboxLeader(agentId: string, role?: string): boolean;
 /** Whether a message may be consumed by the supplied agent identity. */
 export declare function isMailboxMessageVisibleTo(message: Pick<MailboxMessage, 'audience'>, agentId: string, role?: string): boolean;
+/**
+ * Shape of the optional secondary lookup the leader filter performs when a
+ * message arrives without an affinity token (legacy sender / older build).
+ *
+ * `resolveChimeraReportSessionId(reportId)` returns the persisted
+ * `ReviewReport.sessionId` for that report id, or `undefined` when the
+ * report is unknown. May be sync or async — the filter awaits the result.
+ */
+export interface MailboxSessionAffinityContext {
+    /**
+     * Look up the originating session id of a chimera report by its report id.
+     * Return `undefined` for unknown reports. Sync or async.
+     */
+    resolveChimeraReportSessionId?: ((reportId: string) => string | undefined | Promise<string | undefined>) | undefined;
+    /**
+     * Legacy / one-shot opt-in. The flag has TWO consultation points inside
+     * {@link acceptMailboxMessageForSession}:
+     *
+     *   1. When the recipient does not pass a `currentSessionId` (rule 2),
+     *      a token-bearing message is accepted iff this is `true`.
+     *   2. When a token-bearing message lacks a resolvable `sessionId` AND
+     *      the persisted-report resolver returns no match (rule 5), the
+     *      message is accepted iff this is `true`.
+     *
+     * Token-LESS messages are NOT gated by this flag — they are accepted
+     * unconditionally by rule 1 as the discriminator for legitimate
+     * subagent `result` / `review` traffic that does not stamp an affinity
+     * token (task-auctioneer, cascade handlers, legacy senders).
+     *
+     * This flag does NOT override an explicit mismatch: a message that
+     * carries `sessionAffinity.sessionId !== currentSessionId` is dropped
+     * regardless of this flag, because the sender explicitly claimed a
+     * different session — honoring it would re-open the leak.
+     *
+     * Default `false`.
+     */
+    allowUnscoped?: boolean | undefined;
+}
+/**
+ * Decide whether a mailbox message belongs to the recipient's current session
+ * and should therefore be delivered to the leader's inbox.
+ *
+ * The actual code path is:
+ *
+ * 1. {@link isAffectedBySessionAffinity} check. If the message has no
+ *    affinity token, the filter does NOT apply and the message is accepted.
+ *    This is the **discriminator** that protects legitimate subagent
+ *    `result` / `review` traffic (task-auctioneer, cascade handlers) from
+ *    collateral drops — they do not stamp an affinity token, so they fall
+ *    through here. When a token is present, every token is enforced regardless
+ *    of its optional `kind`; malformed or unrecognized kinds must not bypass
+ *    a mismatched `sessionAffinity.sessionId`.
+ * 2. No-session-id branch. If the recipient did not pass a `currentSessionId`,
+ *    accept only when `ctx.allowUnscoped === true`. Default: **fail-closed**
+ *    (drop) — the safe behavior, not a silent fail-open.
+ * 3. Explicit `sessionAffinity.sessionId` match. If the sender stamped a
+ *    session id and it does not match the recipient's current session id,
+ *    drop immediately. The sender claimed a different session; honoring it
+ *    would re-open the cross-session leak. This drop happens even when
+ *    `allowUnscoped` is set — a wrong session is misconfiguration, not a
+ *    legacy case.
+ * 4. Persisted-report fallback. If the token lacks a `sessionId` but carries
+ *    a `reportId`, await `ctx.resolveChimeraReportSessionId(reportId)` and
+ *    accept if the persisted `ReviewReport.sessionId` matches. Accepts
+ *    sync or async resolvers.
+ * 5. `allowUnscoped` opt-in. If the previous steps did not accept and
+ *    `ctx.allowUnscoped === true`, accept (legacy / one-shot tool
+ *    compatibility).
+ * 6. Otherwise drop (`false`).
+ *
+ * Trust note: the filter accepts the sender-asserted `sessionAffinity.sessionId`
+ * without store cross-check (rule 3). The persisted-report fallback (rule 4)
+ * is the only server-side check. A sender that fabricates both an affinity
+ * token and a persisted report could impersonate another session — guard
+ * chimera's send path so only the actual originating session can stamp the
+ * token, and do not relax rule 3.
+ *
+ * The helper is side-effect-free except for awaiting the optional resolver.
+ * It lives next to {@link isMailboxMessageVisibleTo} so mailbox consumers
+ * can compose both filters without taking a dependency on the persistence
+ * layer.
+ */
+export declare function acceptMailboxMessageForSession(message: Pick<MailboxMessage, 'type' | 'sessionAffinity'>, currentSessionId: string | undefined, ctx?: MailboxSessionAffinityContext): Promise<boolean>;
+/**
+ * Synchronous wrapper for callers that cannot await the resolver
+ * (e.g. legacy event handlers). If `ctx.resolveChimeraReportSessionId` is
+ * async, it is called without awaiting and the result is ignored — the
+ * rule degrades to "match affinity.sessionId, otherwise drop unless
+ * allowUnscoped".
+ *
+ * Prefer {@link acceptMailboxMessageForSession} whenever the caller can
+ * await.
+ */
+export declare function acceptMailboxMessageForSessionSync(message: Pick<MailboxMessage, 'type' | 'sessionAffinity'>, currentSessionId: string | undefined, ctx?: MailboxSessionAffinityContext): boolean;
 /** Category + expectsReply are provided by MAILBOX_TYPE_PROPERTIES directly. */
 /**
  * Validate that a given (type, to) pair is internally consistent.
@@ -196,6 +290,13 @@ export interface MailboxMessage {
     taskContext?: MailboxTaskContext | undefined;
     /** Session id of the sender. Enables cross-session communication. */
     senderSessionId?: string | undefined;
+    /**
+     * Session-affinity token persisted on the message. When set, the
+     * recipient's leader filter uses it to drop the message if the
+     * recipient's current session id does not match. See
+     * {@link MailboxSessionAffinity} for the contract.
+     */
+    sessionAffinity?: MailboxSessionAffinity | undefined;
     /**
      * ISO8601 — when the message expires. Set at send time from `ttlMs`
      * (default: 24h via AUTO_COMPACT_DEFAULT_TTL_MS). The auto-compaction
@@ -352,6 +453,25 @@ export interface MailboxSendInput {
     taskContext?: MailboxTaskContext | undefined;
     /** Sender session id. Required when `to` is the `"@session"` alias. */
     senderSessionId?: string | undefined;
+    /**
+     * Session-affinity token. When set, the recipient's mailbox filter uses it
+     * to drop the message if the recipient's current session id does not match.
+     *
+     * Why two fields instead of one: a chimera report is generated by a reviewer
+     * subagent that runs inside the originating session (so `senderSessionId`
+     * is correct), but a mailbox envelope may also be relayed by an outer
+     * pipeline (auto-review cascade, broadcast wrapper) where the recipient
+     * needs to know which session the report *belongs to*, not who *physically
+     * called send()*. `sessionId` carries the originating session;
+     * `reportId` carries the chimera report id so the leader's filter
+     * can also look the report up in the persisted review-report store.
+     *
+     * A session-affinity token is **required** for any `chimera.*` review
+     * delivery wrapper — this is the trust boundary that prevents a leader
+     * from acting on reports emitted by another session, even when those
+     * reports land in its mailbox.
+     */
+    sessionAffinity?: MailboxSessionAffinity | undefined;
     /**
      * Time-to-live in milliseconds. When set, the message's `expiresAt` is
      * computed as `now + ttlMs` at send time. The auto-compaction sweep
@@ -359,6 +479,41 @@ export interface MailboxSendInput {
      */
     ttlMs?: number | undefined;
 }
+/**
+ * Session-affinity token carried on a mailbox message.
+ *
+ * The token is the *only* signal a recipient's leader filter uses to decide
+ * whether a chimera report belongs to the recipient's own session. Without
+ * it, any leader that polls the project-wide mailbox would see — and feel
+ * compelled to act on — chimera reports emitted by every other session in
+ * the project.
+ */
+export type MailboxSessionAffinity = MailboxScopedSessionAffinity | MailboxLegacyReportSessionAffinity;
+export interface MailboxScopedSessionAffinity {
+    /**
+     * The originating session id. The recipient's leader filter compares this
+     * against its own current session id and drops the message on mismatch.
+     */
+    sessionId: string;
+    /**
+     * Originating chimera report id (UUID). Used as a secondary lookup only
+     * when the message is a legacy report token without `sessionId`.
+     */
+    reportId?: string | undefined;
+    /** Free-form tag for filtering / metrics, e.g. `'chimera.review'`. */
+    kind?: string | undefined;
+}
+export interface MailboxLegacyReportSessionAffinity {
+    /**
+     * Legacy report-only tokens deliberately omit `sessionId`; any present
+     * session id is authoritative and must be checked before report lookup.
+     */
+    sessionId?: undefined;
+    /** Originating chimera report id (UUID) used for persisted-session lookup. */
+    reportId: string;
+    /** Free-form tag for filtering / metrics, e.g. `'chimera.review'`. */
+    kind?: string | undefined;
+}
 /**
  * Append-only ack record stored in the JSONL alongside messages.
  *

package/dist/coordination/model-matrix.d.ts

@@ -17,6 +17,7 @@
  * truth both that command and the spawn path use to validate + resolve keys.
  */
 import type { Config, ModelMatrixEntry } from '../types/config.js';
+import type { ProviderModelStatusTracker } from './provider-status-tracker.js';
 /** Either a static matrix or a live getter (re-read on every spawn). */
 export type ModelMatrixSource = Record<string, ModelMatrixEntry> | (() => Record<string, ModelMatrixEntry> | undefined);
 /** All valid phase keys, in catalog order. */
@@ -81,9 +82,24 @@ export declare function roleNeedsIndependentReviewModel(role: string | undefined
  *      implementation model.
  *   3. A different configured provider/model for review roles.
  *   4. The matrix/leader fallback.
+ *
+ * When a {@link ProviderModelStatusTracker} is supplied, resolved candidates
+ * currently in the waiting room (`state: 'blocked'`) are dropped so the
+ * subagent never spawns on a model the leader just 429-stricken. The
+ * fallback extension inside the subagent will also re-check `isAvailable`
+ * before invoking the provider, but filtering here saves the spawn
+ * round-trip on doomed picks.
+ *
+ * The tracker check uses the EFFECTIVE (provider, model) pair — i.e. the
+ * pair that {@link materializeTarget} would render — not the raw
+ * `matrixTarget.provider` field. A model-only matrix entry falls back to
+ * `config.provider` for the wire call, so the waiting-room entry sits on
+ * the same effective identity. Checking the raw field would silently
+ * bypass the quarantine and respawn on a 429-stricken model.
  */
 export declare function resolveSubagentModelTarget(config: Config, role: string | undefined, opts?: {
     implementationTarget?: ModelReference | undefined;
+    statusTracker?: ProviderModelStatusTracker | undefined;
 }): ResolvedSubagentModelTarget | undefined;
 /**
  * Resolve the default implementation lane. The generic Executor is the closest