@ours.network/fleet 1.2.0-nightly.68 → 1.2.0-nightly.69

package/dist/session/arbiter.js

@@ -1,4 +1,14 @@
 import { ACP_CANCEL_DEADLINE_EXCEEDED, SessionControlError, interruptOutcome, } from './types.js';
+/**
+ * Turn sources an urgent reminder may cancel. Owner-channel requests and the
+ * owner console are owner commands: cancelling one finalizes the request and
+ * its reply route (owner-channel/channel.ts), which is an owner-visible
+ * effect. Startup is the readiness gate, stall-watchdog is mid-recovery, and
+ * another self-reminder's turn must not be cancelled by a sibling.
+ */
+const URGENT_INTERRUPTIBLE = new Set(['fleet-monitor', 'scheduled-loop', 'local-console']);
+/** How long a settled cancellation may take to surface the target's own terminal result. */
+const URGENT_CORRELATION_MS = 2_000;
 /**
  * Raised for admissions that were still waiting on a generation which had to be
  * retired. It carries `ACP_CANCEL_DEADLINE_EXCEEDED` because that is the only
@@ -28,6 +38,10 @@ export class RoleTurnArbiter {
     capabilities;
     tail = Promise.resolve();
     unsettled = 0;
+    /** Admissions waiting for the boundary; an urgent interruption yields to them. */
+    waiting = 0;
+    /** Terminal results of prompts this arbiter admitted and that have not settled yet. */
+    live = new Map();
     stopping = false;
     retiring = false;
     /** Bumped by `retireStalledAdmission`; every claim carries the one it was made under. */
@@ -49,11 +63,18 @@ export class RoleTurnArbiter {
      */
     exclusive(operation) {
         const generation = this.generation;
+        this.waiting++;
+        let counted = true;
+        const uncount = () => { if (counted) {
+            counted = false;
+            this.waiting = Math.max(0, this.waiting - 1);
+        } };
         const run = Promise.race([this.tail, this.retirement.promise]).then(() => {
+            uncount();
             if (generation !== this.generation)
                 throw new AdmissionRetiredError();
             return operation();
-        });
+        }, error => { uncount(); throw error; });
         this.tail = run.then(() => undefined, () => undefined);
         return run;
     }
@@ -61,10 +82,12 @@ export class RoleTurnArbiter {
         const generation = this.generation;
         this.unsettled++;
         const completion = queued.completion.finally(() => {
+            this.live.delete(queued.promptId);
             // A retired generation's claims were released in one step already.
             if (generation === this.generation)
                 this.unsettled = Math.max(0, this.unsettled - 1);
         });
+        this.live.set(queued.promptId, completion);
         return { ...queued, completion };
     }
     /**
@@ -87,6 +110,7 @@ export class RoleTurnArbiter {
         this.retirement = retirementSignal();
         this.tail = Promise.resolve();
         this.unsettled = 0;
+        this.waiting = 0;
         retired.retire();
     }
     queuePrompt(text, options = {}) {
@@ -101,8 +125,13 @@ export class RoleTurnArbiter {
      * Other origins retain their configured monitor policy.
      */
     monitorAdmissionOptions(options) {
-        return options.origin?.kind === 'fleet-monitor'
-            && this.session.snapshot().activePromptSource === 'owner-admin-console'
+        if (options.origin?.kind !== 'fleet-monitor')
+            return options;
+        const active = this.session.snapshot().activePromptSource;
+        // A self-reminder turn is protected the same way: a retried wake (say the
+        // one an urgent reminder just interrupted) queues behind it instead of
+        // cancelling it before the agent could inspect and acknowledge.
+        return active === 'owner-admin-console' || active === 'self-reminder'
             ? { ...options, interrupt: false, steer: false } : options;
     }
     async submitPrompt(text, options = {}) {
@@ -187,6 +216,132 @@ export class RoleTurnArbiter {
             throw error;
         });
     }
+    /**
+     * Admit an URGENT self-reminder wake. Idle: exactly `tryReminder`. Busy: the
+     * reminder may ask the exact checked turn to stop — once per event — and is
+     * then admitted at the next boundary like any other reminder.
+     *
+     * The check and the cancel request happen in one synchronous step inside the
+     * admission boundary, so the turn asked to stop is the turn that was checked.
+     * Only a running, correlatable, interruptible turn with nothing queued behind
+     * it and no admission waiting is ever asked to stop; anything else is a
+     * reported deferral (`busy`). After the cancellation the boundary is given up
+     * before the wake is queued, so an owner prompt (or any producer) that
+     * arrived meanwhile is admitted first and the wake simply finds the role
+     * busy. A forced, failed or uncertain cancellation never queues the wake.
+     */
+    async tryUrgentReminder(origin, hooks) {
+        await new Promise(resolve => setImmediate(resolve));
+        const unavailable = (error) => ({ state: 'unavailable', error, admitted: false });
+        const first = await this.exclusive(async () => {
+            const snapshot = this.session.snapshot();
+            if (this.stopping || this.retiring || !snapshot.alive || snapshot.readiness === 'failed')
+                return unavailable(this.stopping ? 'role is stopping' : 'session is unavailable');
+            if (snapshot.readiness === 'idle' && this.unsettled === 0)
+                return this.queueReminder(hooks, origin);
+            const deferral = this.urgentTarget(snapshot);
+            if (typeof deferral === 'string' || !hooks.mayInterrupt()) {
+                hooks.deferred(typeof deferral === 'string' ? deferral : 'interrupt_already_used');
+                return { state: 'busy' };
+            }
+            if (!hooks.beforeQueue())
+                return unavailable('claim declined');
+            if (!hooks.markRequested(deferral))
+                return unavailable('interrupt request not recorded');
+            const terminal = this.live.get(deferral.promptId);
+            // No await between the check above and this call: the session cancels
+            // the turn that was checked, never a successor.
+            let report;
+            try {
+                const outcome = interruptOutcome(await this.session.interrupt('self-reminder'));
+                report = outcome.state === 'forced'
+                    ? { target: deferral, outcome: 'forced', ...(outcome.reasonCode ? { reason: outcome.reasonCode } : {}) }
+                    : { target: deferral, outcome: await correlate(terminal) };
+            }
+            catch (error) {
+                report = { target: deferral, outcome: 'failed', reason: controlReason(error) };
+            }
+            hooks.recordOutcome(report);
+            return report;
+        }).catch(error => {
+            if (error instanceof AdmissionRetiredError)
+                return unavailable(error.message);
+            throw error;
+        });
+        if ('state' in first)
+            return first;
+        if (first.outcome === 'forced' || first.outcome === 'failed')
+            return unavailable(`interruption ${first.outcome}; the wake was not queued`);
+        // Give up the boundary: anything that queued during the cancellation —
+        // owner input first among them — is admitted before the wake.
+        await new Promise(resolve => setImmediate(resolve));
+        return this.exclusive(async () => {
+            const snapshot = this.session.snapshot();
+            if (this.stopping || this.retiring || !snapshot.alive || snapshot.readiness === 'failed')
+                return unavailable(this.stopping ? 'role is stopping' : 'session is unavailable');
+            if (!hooks.stillAdmitting())
+                return unavailable('reminder changed during the interruption');
+            if (snapshot.readiness !== 'idle' || this.unsettled > 0 || this.waiting > 0)
+                return { state: 'busy' };
+            return this.queueReminder(hooks, origin, first, false);
+        }).catch(error => {
+            if (error instanceof AdmissionRetiredError)
+                return unavailable(error.message);
+            throw error;
+        });
+    }
+    /** The exact interruptible turn, or why there is none. Synchronous by design. */
+    urgentTarget(snapshot) {
+        if (snapshot.readiness === 'starting')
+            return 'session_starting';
+        if (snapshot.readiness === 'awaiting_permission' || snapshot.pendingPermissionId)
+            return 'permission_pending';
+        if (snapshot.readiness !== 'running')
+            return 'untracked_turn';
+        const source = snapshot.activePromptSource;
+        if (!source)
+            return 'untracked_turn';
+        if (!URGENT_INTERRUPTIBLE.has(source))
+            return 'protected_turn';
+        if (!this.session.capabilities?.interrupt)
+            return 'interrupt_unsupported';
+        if (this.waiting > 0 || this.unsettled > 1)
+            return 'queued_work';
+        if (!this.session.observeConversation)
+            return 'uncorrelatable';
+        let state;
+        try {
+            const observation = this.session.observeConversation(() => { });
+            state = observation.snapshot;
+            observation.unsubscribe();
+        }
+        catch {
+            return 'uncorrelatable';
+        }
+        if (state.pendingPermissions.length || state.pendingPermissionIds.length)
+            return 'permission_pending';
+        if (state.pendingPromptCount > 0 || state.queueDepth > 1)
+            return 'queued_work';
+        if (state.activePromptIds.length < 1)
+            return 'untracked_turn';
+        return {
+            source, generation: state.sessionGeneration, promptId: state.activePromptIds[0],
+            ...(snapshot.sessionId ? { sessionId: snapshot.sessionId } : {}),
+        };
+    }
+    async queueReminder(hooks, origin, report, claim = true) {
+        if (claim && !hooks.beforeQueue())
+            return { state: 'unavailable', error: 'claim declined', admitted: false };
+        try {
+            const queued = await this.session.queuePrompt(hooks.text(report), {
+                interrupt: false, steer: false, origin, releaseGuard: () => hooks.releaseGuard(),
+            });
+            return { state: 'admitted', queued: this.track(queued) };
+        }
+        catch (error) {
+            return { state: 'unavailable', error: error?.message ?? String(error), admitted: false };
+        }
+    }
     /** Retire only at the same admission boundary used by all prompt producers. */
     retireIfIdle(expired) {
         return this.exclusive(async () => {
@@ -267,3 +422,25 @@ export class RoleTurnArbiter {
     exitResult() { return this.session.exitResult(); }
     close() { return this.session.close(); }
 }
+/**
+ * Whether the target's own terminal result proves this request cancelled it.
+ * A settled interrupt says only that the turn (or nothing) ended; without the
+ * target's correlated result the honest answer is `ended`.
+ */
+async function correlate(terminal) {
+    if (!terminal)
+        return 'ended';
+    let timer;
+    const result = await Promise.race([
+        terminal,
+        new Promise(resolve => { timer = setTimeout(() => resolve(undefined), URGENT_CORRELATION_MS); timer.unref?.(); }),
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    return result?.outcome === 'cancelled' && result.cancellationSource === 'self-reminder' ? 'cancelled' : 'ended';
+}
+function controlReason(error) {
+    if (error instanceof SessionControlError)
+        return error.reasonCode ?? error.kind;
+    return 'control_error';
+}

package/dist/session/types.d.ts

@@ -14,7 +14,9 @@ import type { ConversationEventV1, ConversationSnapshot, PromptReceipt, SubmitPr
  */
 export type SessionReadiness = 'starting' | 'idle' | 'running' | 'awaiting_permission' | 'failed';
 export type TurnOutcome = 'completed' | 'refused' | 'cancelled' | 'failed' | 'inconclusive';
-export type TurnCancellationSource = 'owner' | 'local-console' | 'fleet-monitor' | 'scheduled-loop' | 'shutdown' | 'stall-watchdog';
+export type TurnCancellationSource = 'owner' | 'local-console' | 'fleet-monitor' | 'scheduled-loop' | 'shutdown' | 'stall-watchdog'
+/** An urgent self-reminder of the same agent asked its current turn to stop. */
+ | 'self-reminder';
 export type PromptOrigin = {
     kind: 'startup';
 } | {

package/docs/self-reminders.md

@@ -19,6 +19,7 @@ is nothing to install or enable.
   at 16:00", "follow up on the review on Monday morning".
 - Replace polling or sleeping inside a turn. A reminder costs nothing while it
   waits; a turn that sleeps or a loop that polls costs model time every tick.
+- Wait for a peer without forgetting the task: see [Waiting on a peer](#waiting-on-a-peer).
 - Not for recurring maintenance: use configured `loops` for that.
 
 ## Tools
@@ -29,11 +30,11 @@ reminders, and an id that belongs to another agent is simply not found.
 
 | Tool | Arguments | Result |
 | --- | --- | --- |
-| `fleet_reminder_create` | `request_key`, `title`, `note`?, `local_time`, `time_zone`, `fold`?, `late_window_seconds`? | the reminder (`id`, `revision`, `due_at`, `expires_at`, …) and `created` |
+| `fleet_reminder_create` | `request_key`, `title`, `note`?, `local_time`, `time_zone`, `fold`?, `late_window_seconds`?, `interrupt`? | the reminder (`id`, `revision`, `due_at`, `expires_at`, `interrupt`, …) and `created` |
 | `fleet_reminder_list` | `state`? (`open` default, `closed`, `all`), `limit`? (1–100), `after`? | a page of reminders, `more`, `after`, `uncertain_events` |
 | `fleet_reminder_update` | `id`, `expected_revision`, any of the schedule fields | the reminder at its new revision |
 | `fleet_reminder_cancel` | `id`, `expected_revision` | the cancelled reminder |
-| `fleet_reminder_inspect` | `event_id` | the event, its reminder (with `note`), `current`, `eligible` |
+| `fleet_reminder_inspect` | `event_id` | the event (with `interrupt` / `interrupt_deferred` for an urgent one), its reminder (with `note`), `current`, `eligible` |
 | `fleet_reminder_ack` | `event_id`, `expected_revision` | `acknowledged` (repeat calls return `duplicate: true`) |
 
 ### Time
@@ -58,6 +59,10 @@ Daylight-saving changes are explicit:
 arrive if the agent, Fleet or the host was down, paused or busy at the due time.
 After the window the reminder expires without a turn.
 
+`interrupt` (default `false`) marks a reminder as urgent; see
+[Urgent reminders](#urgent-reminders-interrupt-true). Leave it out for ordinary
+reminders.
+
 ### Idempotency and revisions
 
 `request_key` identifies one scheduling decision. Repeating `create` with the same
@@ -66,6 +71,11 @@ timeout never creates a second one; the same key with different input is refused
 (`request_key_conflict`). Keys are remembered while the reminder is retained (the
 200 most recent closed reminders are kept; at most 100 can be open).
 
+An urgent request differs from an ordinary one: repeating a call made without
+`interrupt` (or with `interrupt: false`) matches the original, while the same key
+with `interrupt: true` is a `request_key_conflict`. `update` can turn urgency on or
+off; it keeps its current value when not given.
+
 Every `update` and `cancel` names the revision it expects (`stale_revision`
 otherwise) and bumps it. A wake issued for an older revision is void: if it is
 still waiting it is dropped before it reaches the model, and if it was already
@@ -109,11 +119,12 @@ current wake becomes void and a new one is issued at the new time.
   directory). With no open reminders it arms no timer; otherwise it checks at the
   next due time and at least once a minute. Only a due reminder creates a model
   turn.
-- **When it arrives.** At the first idle turn boundary after the due time, and
-  only after the agent's startup turn has succeeded. A wake never interrupts the
-  agent and never waits in a queue behind other work; a busy agent receives it
-  when its current work finishes. A reminder wake always runs as its own turn and
-  is never combined with owner or mail input.
+- **When it arrives.** By default, at the first idle turn boundary after the
+  due time, and only after the agent's startup turn has succeeded. An ordinary
+  wake never interrupts the agent and never waits in a queue behind other work;
+  a busy agent receives it when its current work finishes. An urgent reminder may
+  instead stop interruptible busy work once (next section). A reminder wake always
+  runs as its own turn and is never combined with owner or mail input.
 - **Offline.** Nothing runs while the host is off or asleep, or while Fleet or the
   agent is stopped. Reminders are kept, and those still inside their late window
   are delivered when the agent is back; the rest expire without a turn. Pause and
@@ -136,6 +147,93 @@ current wake becomes void and a new one is issued at the new time.
   The wake text contains the title, not the note, and the conversation ledger
   stores only a digest of the wake. Logs carry event ids, never reminder text.
 
+## Urgent reminders (`interrupt: true`)
+
+An ordinary reminder waits for the agent to be idle, so a long busy turn delays
+it. For a return that is genuinely bound to a time — a deadline, a meeting, a
+window that closes — the agent can create the reminder with `interrupt: true`.
+When it is due and the agent is busy, the supervisor may ask the current turn to
+stop and then start the wake in the same session, instead of waiting.
+
+What happens, as separate recorded facts:
+
+1. **Due.** The reminder reaches its time (nothing happens before it).
+2. **Interruption requested.** Only if the busy turn is interruptible (below).
+   The request and its exact target (the turn's source, prompt id and session
+   generation; `inspect` shows them as `interrupt.target`) are durably recorded
+   *before* the session is asked to stop. Each reminder revision may request
+   this **once**. Urgent reminders that may still interrupt are considered
+   before ordinary ones and before urgent ones whose interruption is spent.
+3. **Terminal.** How the stop ended, shown by `inspect` as `interrupt.state`:
+   `cancelled` (the target turn's own result confirms this request cancelled it),
+   `ended` (the session reported it settled, but cancellation is not confirmed),
+   `forced` (the adapter ignored the stop and was restarted), `failed` (the
+   control call failed) or `unknown` (Fleet restarted before the outcome).
+4. **Released.** The wake is handed to the model through the same release fence
+   as every reminder. After `forced` or `failed` it is not queued; it is
+   delivered later, idle-only, within its late window.
+5. **Acknowledged**, and any **external action** the agent then takes, are the
+   agent's own and remain separate facts.
+
+The session and its context are kept: nothing is reset, no second agent and no
+parallel model turn is started. The wake tells the agent what it interrupted so
+it can re-check and resume that work. It sends nothing to anyone and grants no
+authority.
+
+An urgent reminder **never** stops, and instead waits like an ordinary one:
+
+- an owner-channel request or an owner admin-console turn (owner commands keep
+  priority, and cancelling one would end the owner's request and its reply);
+- the startup turn, a stall-recovery turn, or another reminder's wake;
+- a turn with a pending permission decision;
+- work queued behind the current turn, or another admission waiting for the role;
+- a turn Fleet cannot identify exactly (for example one started by adapter-side
+  steering, which reports the role idle).
+
+Interruptible turns are mail wakes, scheduled loops and local-console prompts.
+When the reminder defers, `inspect` shows why in `event.interrupt_deferred`, and it
+interrupts at a later boundary if one becomes interruptible. A mail wake that was
+stopped is retried by the monitor and queued behind the reminder; it cannot stop
+the reminder in turn.
+
+Limits:
+
+- Not a hard real-time alarm: the dispatcher checks at least once a minute, and
+  stopping a turn and starting a model turn both take time.
+- Nothing happens while the host is off or asleep, or Fleet or the agent is down.
+- One interruption per revision: after it (whatever its outcome) the wake is
+  idle-only. A failed or forced stop means the urgency was lost for that event,
+  and `inspect` says so; it never reports a successful interruption.
+- Use it sparingly. Ordinary coordination waits stay `interrupt: false`.
+
+## Waiting on a peer
+
+In paired work (Developer and Critic, Engineer and Critic) an agent that stops to
+wait for a review, answer, artifact or check schedules **one** idle-only reminder
+about 20 minutes out (or at the agreed time), naming the task or room and the
+exact expectation:
+
+```json
+fleet_reminder_create {
+  "request_key": "pr-412-wait-critic-final-1",
+  "title": "PR 412: Critic FINAL on head 1a2b3c",
+  "note": "Task room for PR 412: waiting for the Critic's FINAL on head 1a2b3c. If it arrived, just ack.",
+  "local_time": "2027-01-20T16:20",
+  "time_zone": "UTC"
+}
+```
+
+- The answer arrives, the state changes or the work is finished: `cancel` (or
+  `update`) the reminder with its current revision.
+- On the wake: `inspect`, re-check the task. Resolved or closed: `ack`, nothing
+  else. Still waiting: one concise follow-up in the same room, `ack`, and at most
+  one more reminder; if that one finds no progress either, report the
+  nonresponse or blocker once through the configured routes and stop reminding.
+- Never a short polling interval, a recurring chain of reminders, repeated
+  follow-ups or acknowledgements, or a "done" status because a reminder fired.
+- A deleted or finished task removes the agent's reminders, so a closed task
+  produces no wake.
+
 Operators can see an agent's reminders through the existing supervisor tool
 route, which acts as that agent's supervisor:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "1.2.0-nightly.68",
+  "version": "1.2.0-nightly.69",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, managed native/ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",

package/presets/fleet/roles/Critic.yaml

@@ -25,4 +25,17 @@ persona: |
   after a direct room attempt unless the room contract defines another window; honor any later
   absolute ETA from the peer's timestamp or stated start time. Leave recover,
   block/unblock, review/finish, deletion, replacement, and respawn decisions to Fleet Coordinator.
+
+  Waiting on a peer: before you stop to wait for a specific review, answer, artifact or check in
+  this room, schedule ONE self-reminder with `fleet_reminder_create` about 20 minutes out (or at
+  the time you agreed). Make its `request_key` and `title` name the task or room and what you are
+  waiting for, put the exact expectation in its `note`, and leave `interrupt` false. When the
+  answer arrives, the state changes or you finish, cancel or reschedule that reminder with its
+  current revision. On its wake, inspect it and re-check the task: if the wait is resolved or the
+  task is closed, just acknowledge it; if you are still waiting, post one concise follow-up in the
+  same room, acknowledge, and set at most one more reminder. If that one also finds no progress,
+  report the peer nonresponse or real blocker once through the routes above and stop reminding.
+  Never poll on a short interval, chain recurring reminders, repeat follow-ups or acknowledgements,
+  or mark work done because a reminder fired. Reserve `interrupt: true` for a return that is
+  genuinely bound to a time, never for ordinary coordination waits.
 bio: Independent reviewer; engage to challenge assumptions and observable evidence and withhold sign-off while material failures remain.

package/presets/fleet/roles/Developer.yaml

@@ -25,4 +25,17 @@ persona: |
   after a direct room attempt unless the room contract defines another window; honor any later
   absolute ETA from the peer's timestamp or stated start time. Leave recover,
   block/unblock, review/finish, deletion, replacement, and respawn decisions to Fleet Coordinator.
+
+  Waiting on a peer: before you stop to wait for a specific review, answer, artifact or check in
+  this room, schedule ONE self-reminder with `fleet_reminder_create` about 20 minutes out (or at
+  the time you agreed). Make its `request_key` and `title` name the task or room and what you are
+  waiting for, put the exact expectation in its `note`, and leave `interrupt` false. When the
+  answer arrives, the state changes or you finish, cancel or reschedule that reminder with its
+  current revision. On its wake, inspect it and re-check the task: if the wait is resolved or the
+  task is closed, just acknowledge it; if you are still waiting, post one concise follow-up in the
+  same room, acknowledge, and set at most one more reminder. If that one also finds no progress,
+  report the peer nonresponse or real blocker once through the routes above and stop reminding.
+  Never poll on a short interval, chain recurring reminders, repeat follow-ups or acknowledgements,
+  or mark work done because a reminder fired. Reserve `interrupt: true` for a return that is
+  genuinely bound to a time, never for ordinary coordination waits.
 bio: Implementation and task-execution specialist; engage to deliver a bounded change with observable verification evidence.

package/presets/fleet/roles/Engineer.yaml

@@ -37,4 +37,17 @@ persona: |
   after a direct room attempt unless the room contract defines another window; honor any later
   absolute ETA from the peer's timestamp or stated start time. Leave recover,
   block/unblock, review/finish, deletion, replacement, and respawn decisions to Fleet Coordinator.
+
+  Waiting on a peer: before you stop to wait for a specific review, answer, artifact or check in
+  this room, schedule ONE self-reminder with `fleet_reminder_create` about 20 minutes out (or at
+  the time you agreed). Make its `request_key` and `title` name the task or room and what you are
+  waiting for, put the exact expectation in its `note`, and leave `interrupt` false. When the
+  answer arrives, the state changes or you finish, cancel or reschedule that reminder with its
+  current revision. On its wake, inspect it and re-check the task: if the wait is resolved or the
+  task is closed, just acknowledge it; if you are still waiting, post one concise follow-up in the
+  same room, acknowledge, and set at most one more reminder. If that one also finds no progress,
+  report the peer nonresponse or real blocker once through the routes above and stop reminding.
+  Never poll on a short interval, chain recurring reminders, repeat follow-ups or acknowledgements,
+  or mark work done because a reminder fired. Reserve `interrupt: true` for a return that is
+  genuinely bound to a time, never for ordinary coordination waits.
 bio: Gate-pipeline implementation specialist; engage to deliver a bounded change with gate-by-gate verification evidence.