@wrongstack/core 0.308.7 → 0.309.0

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

@@ -20,7 +20,7 @@
  */
 import type { EventBus } from '../kernel/events.js';
 import type { Context } from '../core/context.js';
-import type { MailboxAudience, MailboxMessageType } from './mailbox-types.js';
+import type { MailboxMessageType } from './mailbox-types.js';
 import { type MailboxResolver } from './mailbox-tool.js';
 export interface MailToolsOptions {
     /** How to obtain a Mailbox given the execution Context (tests). */
@@ -75,12 +75,16 @@ export declare function makeMailSendTool(opts?: MailToolsOptions): {
         required: string[];
     };
     execute(input: unknown, ctx: Context): Promise<{
-        messageId?: never;
-        to?: never;
-        summary?: never;
         ok: boolean;
         error: string;
-        from?: never;
+    } | {
+        error?: never;
+        ok: boolean;
+        messageId: string;
+        from: string;
+        to: string;
+        strippedFields: string[];
+        summary: string;
     } | {
         error?: never;
         ok: boolean;
@@ -128,7 +132,7 @@ export declare function makeMailInboxTool(opts?: MailToolsOptions): {
             from: string;
             to: string;
             type: MailboxMessageType;
-            audience: MailboxAudience;
+            audience: import("./mailbox-message-types.js").MailboxAudience;
             subject: string;
             body: string;
             timestamp: string;

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

@@ -45,6 +45,37 @@ export declare class MailboxValidationError extends Error {
     readonly field: string;
     constructor(code: string, field: string, message: string);
 }
+/** Fields allowed in a send mutation payload from untrusted callers. */
+export declare const SEND_ALLOWED_FIELDS: ReadonlySet<string>;
+/** Result of {@link filterMailboxSendPayload}. */
+export interface FilteredSendPayload {
+    /** Copy of the input containing only allow-listed and trust-relevant keys. */
+    payload: Record<string, unknown>;
+    /** Keys that were removed, in input order. Empty when nothing was stripped. */
+    stripped: string[];
+}
+/**
+ * Strip fields that do not belong in a send payload before it reaches the
+ * boundary codec or the mailbox store.
+ *
+ * Senders (hosts, adapters, models) attach fields the mailbox never asked
+ * for — debug knobs, client metadata, accidental whole-context dumps. Two
+ * failure modes follow without a filter: the strict codec rejects the whole
+ * send because of one irrelevant key, or a lenient surface persists the
+ * clutter into every recipient's inbox. This function prevents both:
+ * irrelevant keys are removed from the payload and reported in `stripped`.
+ *
+ * It is pure (never mutates the input) and keyed off the same
+ * {@link SEND_ALLOWED_FIELDS} set that governs `parseMailboxSendInput`, so
+ * the filter and the validator cannot drift apart.
+ *
+ * Trust-relevant fields (`from`, `sessionAffinity`, see
+ * {@link SEND_FORBIDDEN_FIELDS}) are deliberately PASSED THROUGH, never
+ * stripped: the codec must reject them loudly as unknown fields. Dropping
+ * them here would convert a forgery attempt into a successful,
+ * differently-scoped send.
+ */
+export declare function filterMailboxSendPayload(input: Record<string, unknown>): FilteredSendPayload;
 /**
  * Result of successful send-input parsing.
  * `type` is the resolved type after default selection and validation.

package/dist/coordination/multi-agent-coordinator.d.ts

@@ -150,6 +150,20 @@ export declare class DefaultMultiAgentCoordinator extends EventEmitter implement
      * calls this itself.
      */
     completeTask(result: TaskResult): void;
+    /**
+     * Ask every RUNNING subagent that opted into `gracefulFinish` to finish its
+     * task in its own turn (see coordination/subagent-finish.ts). This is the
+     * leader-side entry point for "the leader agent has finished": it delivers
+     * an in-band notification between tool batches — never an interrupt, never
+     * an abort. Each notified subagent keeps its existing time budget and
+     * accelerates; the watchdog still bounds the maximum lifetime.
+     *
+     * Subagents without the policy opted in are deliberately untouched — their
+     * lifecycle remains the legacy watchdog contract.
+     *
+     * Returns the number of subagents actually notified.
+     */
+    requestFinish(reason: string): number;
     private tryDispatchNext;
     private canDispatch;
     private takeNextDispatchableTask;

package/dist/coordination/multi-agent-timeout.d.ts

@@ -1,5 +1,6 @@
 import type { SubagentRunContext, SubagentRunner, TaskSpec } from '../types/multi-agent.js';
 import { type SubagentBudget } from './subagent-budget.js';
+import type { GracefulFinish } from './subagent-finish.js';
 export interface ExecuteSubagentWithTimeoutOptions {
     runner: SubagentRunner;
     task: TaskSpec;
@@ -8,6 +9,15 @@ export interface ExecuteSubagentWithTimeoutOptions {
     preemptFraction?: number | undefined;
     abortSubagent: (subagentId: string) => void;
     currentSessionId: () => string | undefined;
+    /**
+     * Model-driven completion policy resolved from the subagent config. When
+     * set, crossing the wall-clock deadline does NOT abort the runner: the
+     * budget emits `subagent.finish_requested` in-band (folded into the
+     * conversation between tool batches) and extends its own ceiling by the
+     * grace window. The terminal stop applies only if that window also
+     * elapses — the subagent's bounded maximum lifetime.
+     */
+    gracefulFinish?: GracefulFinish | undefined;
 }
-export declare function executeSubagentWithTimeout({ runner, task, ctx, budget, preemptFraction, abortSubagent, currentSessionId, }: ExecuteSubagentWithTimeoutOptions): Promise<import("../types/multi-agent.js").SubagentRunOutcome>;
+export declare function executeSubagentWithTimeout({ runner, task, ctx, budget, preemptFraction, abortSubagent, currentSessionId, gracefulFinish, }: ExecuteSubagentWithTimeoutOptions): Promise<import("../types/multi-agent.js").SubagentRunOutcome>;
 //# sourceMappingURL=multi-agent-timeout.d.ts.map

package/dist/coordination/mutation-engine.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Deterministic mutation-testing engine ("Kaos Maymunu" / Chaos Monkey).
+ *
+ * Plans and applies classical boundary-condition mutations to TypeScript
+ * source — `>` ↔ `>=`, `+` ↔ `-`, boolean negation, `return x` → `return
+ * null`. The engine is deliberately regex/token based, NOT AST based: it has
+ * zero dependencies, runs synchronously, and every mutation site is
+ * re-derivable from (file, mutation id) alone. Callers (the `mutation_test`
+ * director tool) compute the plan, hand it to a chaos-monkey subagent that
+ * applies/runs/restores in an isolated worktree, and then compare per-mutant
+ * test outcomes against this plan.
+ *
+ * Safety properties the engine guarantees:
+ *  - `applyMutation` is a pure string transform: given the same source and
+ *    the same mutation id it always produces the same output.
+ *  - Mutations are single-site: exactly one token occurrence changes.
+ *  - Ids are stable across runs (position-anchored, not hash-of-content), so
+ *    a worktree-chaos agent and the director tool agree on what each id
+ *    means without exchanging anything but the id list.
+ *
+ * @module coordination/mutation-engine
+ */
+/** Mutation families this engine can plan. */
+export type MutationKind = 'relax-boundary' | 'tighten-boundary' | 'arith-plus-to-minus' | 'arith-minus-to-plus' | 'negate-boolean' | 'return-null';
+export interface MutationPlanItem {
+    /** Stable id: `<kind>#<line1based>#<col1based>`. */
+    id: string;
+    kind: MutationKind;
+    /** Project-relative file path, exactly as passed to planMutations. */
+    file: string;
+    /** 1-based line. */
+    line: number;
+    /** 1-based column of the mutated token start. */
+    column: number;
+    /** Original source text at the site. */
+    original: string;
+    /** Replacement text. */
+    replacement: string;
+}
+export interface PlanMutationsOptions {
+    /** Hard cap on planned mutants per file. Default 25. */
+    maxPerFile?: number | undefined;
+}
+/**
+ * Plan mutations for one file's source text.
+ *
+ * The scan is line-by-line with the file's own line splits preserved so ids
+ * stay (line, column) anchored. Mutations inside comments and string
+ * literals are filtered out by `isMasked` below.
+ */
+export declare function planMutations(file: string, source: string, opts?: PlanMutationsOptions): MutationPlanItem[];
+/**
+ * Apply one planned mutation to source. Pure: same input → same output.
+ * Returns the original source when the site no longer matches (the file has
+ * drifted since planning) so callers can treat that as a skipped mutant.
+ */
+export declare function applyMutation(source: string, mutation: Pick<MutationPlanItem, 'kind' | 'line' | 'column' | 'original' | 'replacement'>): string;
+/**
+ * Parse a structured mutation report emitted by the chaos-monkey subagent
+ * (either via `submit_result` or its final text). Tolerant of surrounding
+ * prose: the first JSON object containing a `mutants` array wins.
+ */
+export declare function parseMutationReport(text: string): {
+    mutants: Array<{
+        id: string;
+        file: string;
+        line: number;
+        kind: string;
+        status: 'killed' | 'survived' | 'skipped';
+        evidence?: string | undefined;
+    }>;
+    summary?: string | undefined;
+} | undefined;
+//# sourceMappingURL=mutation-engine.d.ts.map

package/dist/coordination/subagent-budget.d.ts

@@ -63,6 +63,19 @@ export type BudgetNegotiationMode = 'auto' | 'sync';
 export type BudgetSessionIdSource = string | (() => string | undefined);
 interface SubagentBudgetOptions {
     sessionId?: BudgetSessionIdSource | undefined;
+    /** Owning subagent id — used to address the graceful-finish event. */
+    subagentId?: string | undefined;
+    /**
+     * Wall-clock enforcement is owned EXCLUSIVELY by the coordinator watchdog
+     * (`executeSubagentWithTimeout`). Set for `gracefulFinish` runs: their
+     * notify-then-bound lifecycle must not be raced by `checkTimeout()` calls
+     * from `tool.progress` heartbeats, which can fire in the window between a
+     * deadline crossing and the watchdog's own tick — starting legacy
+     * negotiation that either aborts before `subagent.finish_requested` is
+     * delivered or grants an extension past the grace deadline (violating the
+     * bounded maximum lifetime). Idle-timeout checks still run.
+     */
+    wallClockWatchdogOwned?: boolean | undefined;
 }
 export interface BudgetUsage {
     iterations: number;
@@ -146,6 +159,43 @@ export declare class SubagentBudget {
      * This is the single write path for limit mutations so that future
      * validation or side-effects live in one place (M1). */
     patchLimits(ext: Partial<BudgetLimits>): void;
+    /**
+     * Graceful-finish state (see coordination/subagent-finish.ts).
+     * `_finishNotified` guards the single in-band emission; `_grace` records a
+     * granted working-time extension past the original wall-clock deadline.
+     * They are separate because the two callers want different semantics:
+     * the watchdog grants grace at the deadline crossing (notify + extend),
+     * while an explicit leader-finished request only notifies — a subagent
+     * well inside its budget keeps its full legitimate working time and simply
+     * accelerates.
+     */
+    private _finishNotified;
+    private _grace;
+    /** True once the in-band finish notification has been emitted. */
+    get finishNotified(): boolean;
+    /** True once a grace window has been granted past the original deadline. */
+    get graceGranted(): boolean;
+    /**
+     * Notify the subagent in-band to finish its task in its own turn:
+     * `subagent.finish_requested` is emitted on the wired EventBus and the
+     * agent loop folds the notice into the conversation between tool batches.
+     * Nothing aborts — this is a notification, never an interrupt.
+     *
+     * `opts.graceMs` additionally extends the wall-clock ceiling by that window
+     * (used by the watchdog at a deadline crossing, so the model gets working
+     * time instead of a kill). Omit it to notify without touching the budget —
+     * the subagent keeps its existing time budget and just accelerates.
+     *
+     * Returns `true` when this call did something (emitted the notification
+     * and/or granted grace); `false` when there was nothing to do (already
+     * notified, grace already granted, no EventBus wired, budget not started).
+     */
+    notifyFinish(reason: string, opts?: {
+        graceMs?: number | undefined;
+    }, now?: () => number): boolean;
+    /** Epoch ms by which the subagent should have produced its final output,
+     *  once a grace window was granted. Undefined before that. */
+    get finishDeadlineMs(): number | undefined;
     private iterations;
     private toolCalls;
     private tokenInput;
@@ -161,6 +211,10 @@ export declare class SubagentBudget {
     private lastActivityTime;
     private _onThreshold;
     private readonly _sessionId;
+    /** Owning subagent id — used to address the graceful-finish event. */
+    private readonly _subagentId;
+    /** True when only the coordinator watchdog may enforce wall-clock limits. */
+    private readonly _wallClockWatchdogOwned;
     /**
      * Hard cap on how long `_negotiateExtension` waits for the coordinator to
      * respond before defaulting to 'stop'. Without this fallback an absent

package/dist/coordination/subagent-finish.d.ts

@@ -0,0 +1,78 @@
+/**
+ * subagent-finish — model-driven completion for background subagents.
+ *
+ * Problem this module solves: a subagent that outlives its leader (the
+ * post-session Chimera reviewer is the canonical case) previously had only
+ * two exits — finish on its own, or be killed by the wall-clock watchdog
+ * (`executeSubagentWithTimeout` aborts the runner at the deadline). The kill
+ * is an external interrupt: it discards whatever the model was mid-way
+ * through producing and violates the "agent completes its own turn" contract.
+ *
+ * The graceful-finish path replaces the kill with a notification:
+ *
+ *   1. The subagent's config opts in via `gracefulFinish`.
+ *   2. When the finish condition fires — the wall-clock deadline is crossed,
+ *      or the leader explicitly calls `Director.requestFinish()` — the budget
+ *      records a single finish deadline and emits `subagent.finish_requested`
+ *      on the subagent's EventBus, carrying the ready-to-read notice text.
+ *   3. The agent loop folds that notice into the conversation as a `/btw`
+ *      note at the TOP of its next iteration — between tool batches,
+ *      in-band, no abort, no restart.
+ *   4. The model reads the notice and completes its task in its own turn.
+ *   5. If the grace window also elapses, the watchdog applies the existing
+ *      terminal stop. That is the documented maximum lifetime — the bound
+ *      that keeps a subagent from living forever, reached only after the
+ *      model was given legitimate working time to finish.
+ *
+ * @module subagent-finish
+ */
+/** Structural form of `SubagentConfig.gracefulFinish` (avoids a layer cycle). */
+export type GracefulFinishConfig = boolean | {
+    graceMs?: number | undefined;
+} | undefined;
+/**
+ * EventBus name for the in-band finish request. Emitted on the subagent's own
+ * EventBus (the bus the runner wired into `budget._events`), so delivery is
+ * process-local and lands at the loop's next iteration boundary.
+ */
+export declare const SUBAGENT_FINISH_REQUESTED_EVENT = "subagent.finish_requested";
+/**
+ * Default grace window granted after the finish request fires. Long enough
+ * for a model to run one or two more tool calls and write a complete final
+ * report; short enough that a session shutdown cannot stall indefinitely.
+ */
+export declare const DEFAULT_SUBAGENT_FINISH_GRACE_MS = 120000;
+/** Resolved graceful-finish policy for one subagent. */
+export interface GracefulFinish {
+    /** Milliseconds of legitimate working time granted after notification. */
+    graceMs: number;
+}
+/**
+ * Resolve the graceful-finish policy from a `SubagentConfig`.
+ *
+ * `undefined` (the default for every existing spawn) keeps the legacy
+ * behavior byte-for-byte: the watchdog preempts/negotiates/aborts exactly as
+ * it did before. Only spawns that explicitly opt in get the notify-then-bound
+ * lifecycle.
+ */
+export declare function resolveGracefulFinish(config: {
+    gracefulFinish?: GracefulFinishConfig | undefined;
+}): GracefulFinish | undefined;
+/**
+ * The in-band notice the subagent reads between tool calls. Delivered as a
+ * `/btw` note, so it arrives at the next iteration boundary — never mid-tool,
+ * never as an abort. The wording is deliberately imperative and
+ * self-contained: the model must be able to act on it without any other
+ * context about why the leader finished. Carried verbatim on the event
+ * payload so the core agent loop needs no coordination-layer import to fold
+ * it into the conversation.
+ */
+export declare function buildSubagentFinishNotice(input: {
+    /** Why the finish was requested (e.g. "leader session ended"). */
+    reason: string;
+    /** Epoch milliseconds by which the final output should be complete. */
+    deadlineMs: number;
+    /** Granted working-time window in milliseconds. */
+    graceMs: number;
+}): string;
+//# sourceMappingURL=subagent-finish.d.ts.map

package/dist/core/index.js

@@ -3649,9 +3649,17 @@ var TASK_SNIPPET_CHARS = 60;
 function fleetPulseSignature(statuses) {
   return statuses.map((s) => `${s.agentId}|${s.status}|${s.currentTask ?? ""}`).sort().join("\n");
 }
-function peerLine(s) {
+function visibleLineKey(s) {
+  const role = s.role && s.role !== s.name ? s.role : "";
+  const task = s.currentTask && s.currentTask.length > TASK_SNIPPET_CHARS ? `${s.currentTask.slice(0, TASK_SNIPPET_CHARS)}\u2026` : s.currentTask ?? "";
+  const tool = s.currentTool || "";
+  const toolCalls = s.toolCalls > 0 ? String(s.toolCalls) : "";
+  return [s.name, role, s.status, task, tool, toolCalls].join("\0");
+}
+function peerLine(s, count = 1) {
   const role = s.role && s.role !== s.name ? ` (${s.role})` : "";
-  const parts = [`\u2022 ${s.name}${role} \u2014 ${s.status}`];
+  const grouped = count > 1 ? ` \xD7${count}` : "";
+  const parts = [`\u2022 ${s.name}${role}${grouped} \u2014 ${s.status}`];
   if (s.currentTask) {
     const task = s.currentTask.length > TASK_SNIPPET_CHARS ? `${s.currentTask.slice(0, TASK_SNIPPET_CHARS)}\u2026` : s.currentTask;
     parts.push(`"${task}"`);
@@ -3667,13 +3675,20 @@ function buildFleetPulseBlock(statuses, opts) {
   if (peers.length === 0) return null;
   const order = { running: 0, streaming: 0, waiting_user: 1, idle: 2, error: 3, offline: 4 };
   const sorted = [...peers].sort(
-    (x, y) => (order[x.status] ?? 5) - (order[y.status] ?? 5) || x.name.localeCompare(y.name)
+    (x, y) => (order[x.status] ?? 5) - (order[y.status] ?? 5) || visibleLineKey(x).localeCompare(visibleLineKey(y))
   );
   const shown = sorted.slice(0, maxAgents);
   const hidden = sorted.length - shown.length;
   const parts = [];
   parts.push(`[FLEET PULSE] ${peers.length} peer${peers.length === 1 ? "" : "s"} online:`);
-  for (const s of shown) parts.push(peerLine(s));
+  for (let i = 0; i < shown.length; ) {
+    let run = 1;
+    while (i + run < shown.length && visibleLineKey(shown[i]) === visibleLineKey(shown[i + run])) {
+      run++;
+    }
+    parts.push(peerLine(shown[i], run));
+    i += run;
+  }
   if (hidden > 0) parts.push(`\u2026 +${hidden} more`);
   parts.push(
     "[END FLEET PULSE] (FYI \u2014 coordinate via mail_send; avoid duplicating peers' work)"