@ours.network/fleet 0.19.0-nightly.8 → 1.0.0

package/dist/harness/codex.js

@@ -5,7 +5,7 @@ import { agentDir, home } from '../paths.js';
 import { realExec } from '../exec.js';
 import { registerAdapter } from './registry.js';
 import { harnessRuntimeDir } from '../isolation/policy.js';
-import { bundledAcpAgent, resolveBundledAcpAgent } from './acp-agent.js';
+import { resolveBundledAcpAgent, } from './acp-agent.js';
 const OPTION_KEYS = [
     'launcher', 'sandbox', 'approval', 'permission_mode', 'search', 'profile', 'config', 'add_dirs',
     'monitor',
@@ -51,9 +51,7 @@ function sandboxMode(role) {
         throw new Error(`invalid harness_options.sandbox "${s}"; allowed: ${SANDBOX_MODES.join(', ')}`);
     return s;
 }
-/** codex-acp exposes the same sandbox postures as named ACP agent modes. */
-function acpAgentMode(role) {
-    const sandbox = sandboxMode(role);
+function modeForSandbox(sandbox) {
     if (sandbox === 'read-only')
         return 'read-only';
     if (sandbox === 'workspace-write')
@@ -62,6 +60,26 @@ function acpAgentMode(role) {
         return 'agent-full-access';
     return undefined;
 }
+/**
+ * Resolve the coupled Codex ACP mode.
+ *
+ * The portable approval contract owns the default mode selection: `allow`
+ * means the adapter's fully non-interactive yolo preset and `auto` means its
+ * ordinary agent preset. This intentionally means that Codex ACP cannot retain
+ * an independent neutral filesystem posture for those two modes. An explicit
+ * native sandbox remains authoritative and selects its corresponding preset.
+ */
+function acpAgentMode(role) {
+    const explicitSandbox = role.harness_options?.sandbox;
+    if (explicitSandbox != null)
+        return modeForSandbox(sandboxMode(role));
+    if (role.permissions?.approval === 'allow')
+        return 'agent-full-access';
+    if (role.permissions?.approval === 'auto')
+        return 'agent';
+    const sandbox = sandboxMode(role);
+    return modeForSandbox(sandbox);
+}
 function acpModePermissions(mode) {
     if (mode === 'read-only')
         return { approval: 'on-request', sandbox: 'read-only' };
@@ -69,6 +87,10 @@ function acpModePermissions(mode) {
         return { approval: 'never', sandbox: 'danger-full-access' };
     return { approval: 'on-request', sandbox: 'workspace-write' };
 }
+/** The sandbox Codex will actually receive from the selected coupled ACP mode. */
+function acpRuntimeSandbox(role) {
+    return acpModePermissions(acpAgentMode(role)).sandbox;
+}
 function fleetModeForApproval(nativeMode) {
     if (nativeMode === 'never')
         return 'allow';
@@ -102,6 +124,18 @@ function launcherMode(role) {
 function bundledCodexAcp() {
     return resolveBundledAcpAgent(CODEX_ACP_PACKAGE, 'codex-acp', 'codex-acp');
 }
+/** Bind launch argv and metadata provenance to one already-completed resolution. */
+export function codexAcpLaunchForResolution(resolution) {
+    const permissionMetadataSource = resolution.bundled
+        && resolution.version === BUNDLED_CODEX_ACP_VERSION
+        && resolution.manifestPath !== undefined
+        ? 'codex-acp'
+        : undefined;
+    return {
+        argv: [...resolution.argv],
+        ...(permissionMetadataSource ? { permissionMetadataSource } : {}),
+    };
+}
 function canOverrideBundledAcpApproval() {
     const resolution = bundledCodexAcp();
     return resolution.bundled && resolution.version === BUNDLED_CODEX_ACP_VERSION
@@ -147,7 +181,7 @@ function codexAcpEnvironment(role, dirs) {
     return {
         CODEX_PATH: command,
         [CODEX_PROXY_APPROVAL_ENV]: approvalPolicy(role) ?? 'on-request',
-        [CODEX_PROXY_SANDBOX_ENV]: sandboxMode(role) ?? 'workspace-write',
+        [CODEX_PROXY_SANDBOX_ENV]: acpRuntimeSandbox(role),
         [CODEX_PROXY_MANIFEST_ENV]: resolution.manifestPath,
         ...(process.env.CODEX_PATH ? { [CODEX_PROXY_REAL_PATH_ENV]: process.env.CODEX_PATH } : {}),
     };
@@ -275,7 +309,7 @@ export function makeCodexAdapter(exec = realExec) {
             return errs;
         },
         async prepareSession(role, dirs) {
-            // Per-role harness runtime home (5.1); harmless for un-isolated roles.
+            // Per-role harness runtime home; harmless for un-isolated roles.
             // Only a role that declares `isolation:` gets a sandbox, and only a
             // sandbox needs this directory to exist before entry.
             if (role.isolation)
@@ -285,7 +319,16 @@ export function makeCodexAdapter(exec = realExec) {
             if (requested === 'ours-codex' && !hasOursCodex)
                 throw new Error('harness_options.launcher is ours-codex, but ours-codex is not on PATH; install @ours.network/codex or use launcher: auto');
             const command = requested === 'codex' ? 'codex' : hasOursCodex ? 'ours-codex' : 'codex';
-            return { argv: [], env: codexAcpEnvironment(role, dirs), command };
+            return {
+                argv: [],
+                // OURS_BIND_IDENTITY is the connector's startup bind seed — see the note in
+                // claude-code.ts's prepareSession. It belongs on EVERY harness that runs a
+                // role with an ours identity, not just claude-code: a seed that works on one
+                // harness and silently does nothing on the other is the same class of defect
+                // as a config key that only works on one session type.
+                env: { OURS_BIND_IDENTITY: role.identity, ...codexAcpEnvironment(role, dirs) },
+                command,
+            };
         },
         buildLaunch(role, mode, _s, prep) {
             const stateDir = roleStateDir(role);
@@ -299,17 +342,30 @@ export function makeCodexAdapter(exec = realExec) {
         },
         buildAcpLaunch(role, prep) {
             const configured = role.session_options?.acp?.command;
+            // Resolve once: both argv and permission-metadata provenance must describe
+            // the same artifact. A bare PATH fallback is launchable for compatibility,
+            // but is never authenticated for protected-MCP auto-approval.
+            const resolved = configured == null
+                ? codexAcpLaunchForResolution(bundledCodexAcp())
+                : undefined;
             const argv = Array.isArray(configured)
                 ? [...configured]
                 : typeof configured === 'string'
                     ? ['sh', '-c', configured]
-                    : bundledAcpAgent(CODEX_ACP_PACKAGE, 'codex-acp', 'codex-acp');
+                    : resolved.argv;
             const initialMode = acpAgentMode(role);
             return {
                 argv,
                 env: initialMode ? { ...prep.env, INITIAL_AGENT_MODE: initialMode } : prep.env,
+                ...(resolved?.permissionMetadataSource
+                    ? { permissionMetadataSource: resolved.permissionMetadataSource } : {}),
             };
         },
+        // INITIAL_AGENT_MODE covers session/new in codex-acp; session/set_mode
+        // keeps resumed/loaded sessions and live status on the identical mode.
+        acpPermissionModeId(role) {
+            return acpAgentMode(role);
+        },
         isolationPaths(role, _dirs) {
             const codexHome = join(home(), '.codex');
             const profile = role.harness_options?.profile;
@@ -362,7 +418,9 @@ export function makeCodexAdapter(exec = realExec) {
                 const mode = acpAgentMode(role) ?? 'agent';
                 const configured = role.session_options?.acp?.command;
                 const overrideAvailable = configured == null && canOverrideBundledAcpApproval();
-                const actual = overrideAvailable ? { approval, sandbox } : acpModePermissions(mode);
+                const actual = overrideAvailable
+                    ? { approval, sandbox: acpRuntimeSandbox(role) }
+                    : acpModePermissions(mode);
                 const exact = actual.approval === approval && actual.sandbox === sandbox;
                 return {
                     ...translated,
@@ -372,10 +430,9 @@ export function makeCodexAdapter(exec = realExec) {
                             ? `custom ACP command cannot be verified against approval=${approval} sandbox=${sandbox}; `
                                 + `its '${mode}' mode is conservatively treated as approval=${actual.approval} `
                                 + `sandbox=${actual.sandbox}`
-                            : `codex-acp mode '${mode}' actually uses approval=${actual.approval} `
-                                + `sandbox=${actual.sandbox}, and the bundled ${BUNDLED_CODEX_ACP_VERSION} `
-                                + `app-server override is unavailable; this does not exactly represent `
-                                + `approval=${approval} sandbox=${sandbox}`],
+                            : `Codex ACP mode '${mode}' couples approval and filesystem as `
+                                + `approval=${actual.approval} sandbox=${actual.sandbox}; this does not exactly `
+                                + `represent approval=${approval} sandbox=${sandbox}`],
                     capabilities: codexCapabilities(actual.approval, actual.sandbox),
                 };
             }
@@ -411,6 +468,8 @@ export function makeCodexAdapter(exec = realExec) {
             currentIdentityTool: 'current_identity',
             sendTool: 'send_message',
             getMessagesTool: 'get_messages',
+            listHistoryTool: 'list_history',
+            getHistoryItemTool: 'get_history_item',
             monitorInstruction: (id, configuredRole) => {
                 const consented = configuredRole?.harness_options?.monitor === true;
                 const consent = consented

package/dist/harness/types.d.ts

@@ -1,3 +1,4 @@
+import type { McpServer } from '@agentclientprotocol/sdk';
 import type { CommonPermissions, FleetPermissionMode, ResolvedRole } from '../config.js';
 export interface PrereqCheck {
     name: string;
@@ -21,14 +22,39 @@ export interface SessionPrep {
     env: Record<string, string>;
     /** Optional launcher selected after runtime prerequisite probing. */
     command?: string;
+    /**
+     * The settings overlay prepareSession wrote, if it wrote one.
+     *
+     * The tmux launch delivers this as `--settings <path>` in `argv`; an ACP agent
+     * takes no flags, so it needs the PATH rather than the flag. Recorded here so
+     * the two deliveries read one value instead of each re-deriving the filename.
+     */
+    settingsOverlay?: string;
+    /**
+     * The MCP config file prepareSession wrote for `harness_options.mcp_servers`,
+     * if the role declared any. Same reason as `settingsOverlay`: the tmux launch
+     * passes the file, the ACP launch has to send the servers themselves.
+     */
+    mcpConfigFile?: string;
 }
+/**
+ * One MCP server as ACP's `session/new` declares it.
+ *
+ * ⚠ THE PROTOCOL'S OWN TYPE, DELIBERATELY NOT A LOCAL RESTATEMENT. `mcpServers`
+ * goes onto the wire unchanged, so a hand-written near-copy would compile while
+ * being subtly wrong — `env` and `headers` are REQUIRED arrays, and the stdio
+ * variant is the one with no `type` field at all. Aliasing it also keeps
+ * `session/new`'s response type inferable, which a structural stand-in silently
+ * broke (every field of the result degraded to `unknown`).
+ */
+export type AcpMcpServer = McpServer;
 export interface Launch {
     argv: string[];
     env: Record<string, string>;
 }
-export interface AcpLaunch {
-    argv: string[];
-    env: Record<string, string>;
+export interface AcpLaunch extends Launch {
+    /** Metadata vocabulary authenticated by the exact ACP artifact in argv. */
+    permissionMetadataSource?: 'codex-acp';
 }
 /**
  * The result of expressing neutral `permissions:` in a harness's own terms.
@@ -67,6 +93,8 @@ export interface BriefingVocab {
     currentIdentityTool: string;
     sendTool: string;
     getMessagesTool: string;
+    listHistoryTool: string;
+    getHistoryItemTool: string;
     monitorInstruction(identity: string, role?: ResolvedRole): string;
     /** Wake-source wording for a role whose monitor is supervisor-owned (monitor.mode=fleet). */
     supervisedWakeNote(identity: string, role?: ResolvedRole): string;
@@ -74,7 +102,7 @@ export interface BriefingVocab {
     restartPrompt(identity: string, worklogPath: string, role?: ResolvedRole): string;
 }
 /**
- * How a harness's host state splits for sandboxing (5.1). `home` is the
+ * How a harness's host state splits for sandboxing. `home` is the
  * directory the CLI treats as its own and whose RUNTIME state must be per-role;
  * `shared` are the credential, instruction and configuration paths that stay
  * shared and become read-only inside the sandbox.
@@ -95,7 +123,13 @@ export interface HarnessAdapter {
     id: string;
     supportsResume: boolean;
     checkPrereqs(): Promise<PrereqReport>;
-    validateOptions(opts: unknown): ValidationError[];
+    /**
+     * `role` is the SESSION-AWARE half: some harness options can only be honoured
+     * on some session types, and an option that is silently dropped is worse than
+     * one that is refused. Optional so an adapter that has nothing session-specific
+     * to say keeps its one-argument implementation.
+     */
+    validateOptions(opts: unknown, role?: ResolvedRole): ValidationError[];
     prepareSession(role: ResolvedRole, dirs: RoleDirs): Promise<SessionPrep>;
     buildLaunch(role: ResolvedRole, mode: 'fresh' | 'resume', s: SessionState, prep: SessionPrep): Launch;
     buildAcpLaunch?(role: ResolvedRole, prep: SessionPrep): AcpLaunch;
@@ -105,6 +139,23 @@ export interface HarnessAdapter {
      * agent's default. Omit for a harness whose ACP agent has no modes.
      */
     acpPermissionModeId?(role: ResolvedRole): string | undefined;
+    /**
+     * The MCP servers this role declares, for the `mcpServers` array of ACP's
+     * `session/new` / `resume` / `load`. Empty (or omitted) leaves the agent's own
+     * configuration alone, which is what fleet has always sent.
+     */
+    acpMcpServers?(role: ResolvedRole): AcpMcpServer[];
+    /**
+     * Agent-specific `_meta` for `session/new` — how a capability the CLI takes as
+     * a flag reaches an ACP agent that accepts no flags.
+     *
+     * ⚠ THIS IS A PER-AGENT VOCABULARY, NOT PROTOCOL. `_meta` is free-form in ACP,
+     * so what an adapter puts here is only honoured by the agent it was written
+     * for. An adapter must therefore return nothing for an ACP command it did not
+     * choose, and the options that depend on it must be refused at validation for
+     * such a role rather than sent and silently ignored.
+     */
+    acpSessionMeta?(role: ResolvedRole, prep: SessionPrep): Record<string, unknown> | undefined;
     /** Effective portable policy and harness-native approval mode after native overrides win. */
     effectivePermissionMode?(role: ResolvedRole): {
         fleetMode: FleetPermissionMode;
@@ -127,7 +178,7 @@ export interface HarnessAdapter {
     nativePermissionOverrides(options: unknown): Record<string, unknown>;
     /**
      * Host paths this harness needs inside a sandbox, split into a per-role
-     * writable home and shared read-only credentials/config (5.1). Omit for a
+     * writable home and shared read-only credentials/config. Omit for a
      * harness with no host state of its own.
      */
     isolationPaths?(role: ResolvedRole, dirs: RoleDirs): HarnessIsolationPaths;

package/dist/isolation/bubblewrap.d.ts

@@ -1,10 +1,10 @@
 import { type Exec } from '../exec.js';
 import type { IsolationBackend, NetworkMode } from './types.js';
 /**
- * Phase 2 network policy: only `deny` unshares the network namespace. `broker`
- * keeps the host network so ours messaging (a loopback TCP daemon on this host —
- * see the Phase-0 spike) keeps working; hardening `broker` to `--unshare-net` +
- * a loopback forwarder is Phase 4. `allow`/`allowlist` also keep host net.
+ * Only `deny` unshares the network namespace. `broker`
+ * keeps the host network so ours messaging through a loopback TCP daemon keeps
+ * working; hardening `broker` to `--unshare-net` plus
+ * a loopback forwarder is not implemented. `allow`/`allowlist` also keep host net.
  */
 export declare function unsharesNet(network: NetworkMode): boolean;
 export declare function makeBubblewrapBackend(exec?: Exec): IsolationBackend;

package/dist/isolation/bubblewrap.js

@@ -1,9 +1,9 @@
 import { realExec } from '../exec.js';
 /**
- * Phase 2 network policy: only `deny` unshares the network namespace. `broker`
- * keeps the host network so ours messaging (a loopback TCP daemon on this host —
- * see the Phase-0 spike) keeps working; hardening `broker` to `--unshare-net` +
- * a loopback forwarder is Phase 4. `allow`/`allowlist` also keep host net.
+ * Only `deny` unshares the network namespace. `broker`
+ * keeps the host network so ours messaging through a loopback TCP daemon keeps
+ * working; hardening `broker` to `--unshare-net` plus
+ * a loopback forwarder is not implemented. `allow`/`allowlist` also keep host net.
  */
 export function unsharesNet(network) {
     return network === 'deny';

package/dist/isolation/policy.d.ts

@@ -23,7 +23,7 @@ export declare function mountConflict(mount: string, forbidden: string): 'exact'
  */
 export declare function validateIsolationConfig(raw: unknown): string[];
 /**
- * Where a role's per-role harness runtime state lives (5.1). Under the agent's
+ * Where a role's per-role harness runtime state lives. Under the agent's
  * own state directory, so it is covered by the state dir's existing lifecycle
  * and by the forbidden-path exception, and is never shared with a peer.
  */

package/dist/isolation/policy.js

@@ -105,7 +105,7 @@ export function validateIsolationConfig(raw) {
     return problems;
 }
 /**
- * Where a role's per-role harness runtime state lives (5.1). Under the agent's
+ * Where a role's per-role harness runtime state lives. Under the agent's
  * own state directory, so it is covered by the state dir's existing lifecycle
  * and by the forbidden-path exception, and is never shared with a peer.
  */
@@ -147,7 +147,7 @@ export function resolveIsolation(cfg, ctx) {
     addRw(stateDir);
     addRw(runCwd);
     if (ctx.harnessHome && ctx.harnessRuntimeDir) {
-        // The harness home is backed by a PER-ROLE directory (5.1): the agent gets a
+        // The harness home is backed by a PER-ROLE directory: the agent gets a
         // writable home for its sessions, caches and history, and anything a future
         // CLI version writes lands there too. The shared credentials, global
         // instructions and configuration are then layered back read-only, so they

package/dist/isolation/registry.d.ts

@@ -11,12 +11,12 @@ export interface Selection {
     detail: string;
 }
 /**
- * Pick the isolation backend for a resolved policy, honouring `auto` (bwrap-first,
- * rootless — OQ-5) and the `on_unavailable` degradation policy.
+ * Pick the isolation backend for a resolved policy, honouring rootless,
+ * bwrap-first `auto` and the `on_unavailable` degradation policy.
  *
  * - `none`         → the identity backend.
  * - `bubblewrap`   → bwrap if available, else degrade/refuse per on_unavailable.
- * - `podman`       → not implemented yet (Phase 6) ⇒ treated as unavailable.
+ * - `podman`       → not implemented ⇒ treated as unavailable.
  * - `auto`         → bwrap if available, else degrade/refuse.
  *
  * On `on_unavailable: strict` with nothing available, throws (fail closed).

package/dist/isolation/registry.js

@@ -4,12 +4,12 @@ import { makeNoneBackend } from './none.js';
 export { makeBubblewrapBackend, unsharesNet } from './bubblewrap.js';
 export { makeNoneBackend } from './none.js';
 /**
- * Pick the isolation backend for a resolved policy, honouring `auto` (bwrap-first,
- * rootless — OQ-5) and the `on_unavailable` degradation policy.
+ * Pick the isolation backend for a resolved policy, honouring rootless,
+ * bwrap-first `auto` and the `on_unavailable` degradation policy.
  *
  * - `none`         → the identity backend.
  * - `bubblewrap`   → bwrap if available, else degrade/refuse per on_unavailable.
- * - `podman`       → not implemented yet (Phase 6) ⇒ treated as unavailable.
+ * - `podman`       → not implemented ⇒ treated as unavailable.
  * - `auto`         → bwrap if available, else degrade/refuse.
  *
  * On `on_unavailable: strict` with nothing available, throws (fail closed).
@@ -20,9 +20,9 @@ export async function selectIsolationBackend(policy, exec = realExec) {
     const candidates = [];
     if (policy.backend === 'auto' || policy.backend === 'bubblewrap')
         candidates.push(makeBubblewrapBackend(exec));
-    // podman: Phase 6 — no candidate yet, so it falls through to on_unavailable.
+    // podman has no candidate yet, so it falls through to on_unavailable.
     let lastDetail = policy.backend === 'podman'
-        ? 'podman backend not implemented yet (Phase 6)'
+        ? 'podman backend is not implemented'
         : 'no isolation backend available';
     for (const b of candidates) {
         const a = await b.available();

package/dist/isolation/resources.d.ts

@@ -5,7 +5,7 @@ export interface ResourceArgs {
 }
 /**
  * Build the `systemd-run --user --scope -p … --` prefix that caps the pane's
- * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): a tmux pane is
+ * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap: a tmux pane is
  * a child of a tmux SERVER rather than of the role's own runner process, so the
  * only reliable per-agent limit is a transient scope at the pane itself. (Since
  * #32 that server is per role rather than fleet-wide, which is what keeps one

package/dist/isolation/resources.js

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 /**
  * Build the `systemd-run --user --scope -p … --` prefix that caps the pane's
- * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap (§5.3/§5.4): a tmux pane is
+ * cgroup-v2 scope. Composed OUTSIDE the sandbox wrap: a tmux pane is
  * a child of a tmux SERVER rather than of the role's own runner process, so the
  * only reliable per-agent limit is a transient scope at the pane itself. (Since
  * #32 that server is per role rather than fleet-wide, which is what keeps one

package/dist/isolation/types.d.ts

@@ -1,4 +1,4 @@
-/** Isolation backend selector. `auto` probes bubblewrap then podman; `none` disables wrapping. */
+/** Isolation backend selector. `auto` probes bubblewrap; `none` disables wrapping. */
 export type IsolationBackendId = 'auto' | 'bubblewrap' | 'podman' | 'none';
 /** What to do when the requested backend is unavailable. */
 export type OnUnavailable = 'warn' | 'strict';
@@ -38,7 +38,7 @@ export interface Mount {
     mode: 'ro' | 'rw';
 }
 /**
- * Runtime facts the pure resolver needs to compute the durable mount set (§5.2):
+ * Runtime facts the pure resolver needs to compute the durable mount set:
  * the agent's state dir, its working dir, the fleet user's home, and (if the ours
  * broker exposes one) a unix-socket endpoint to bind in.
  */
@@ -52,7 +52,7 @@ export interface WrapContext {
     additionalWriteDirs?: string[];
     /**
      * The harness's home directory on the host (`~/.claude`, `~/.codex`). Mounted
-     * from `harnessRuntimeDir` so the agent's own runtime state is per-role (5.1).
+     * from `harnessRuntimeDir` so the agent's own runtime state is per-role.
      */
     harnessHome?: string;
     /** Per-role writable directory backing `harnessHome` inside the sandbox. */

package/dist/loops/manager.d.ts

@@ -68,8 +68,32 @@ export declare class ScheduledLoopManager implements ScheduledLoopManagerHandle
     private armAbandon;
     private finish;
     private advance;
+    /**
+     * Coalesce a backlog into one skip. The counters alone say how many
+     * occurrences were lost but never when or for how long, so the window is
+     * recorded too and carried on the state until a run is actually told about it
+     * — a dropped pass has to stay visible to the next one, not just to whoever
+     * was reading the log at the time.
+     */
     private skipMissed;
-    private skipRestartMisses;
+    /**
+     * Restart is not, by itself, a reason to lose an occurrence a running manager
+     * would still have run. `poll` tolerates lateness up to one full interval and
+     * runs the tick late; this path used to drop anything already due however
+     * recently, so a role restarted seconds after its own tick came due lost it
+     * outright. For an oversight role that is precisely the pass which would have
+     * recorded why it restarted, so the failure erased its own witness.
+     *
+     * The tolerance is the only thing shared with `poll`. A backlog at least one
+     * interval deep is still coalesced into a single skip and never replayed —
+     * after a long outage exactly one occurrence survives, and `schedule` then
+     * arms it through the ordinary path rather than firing a burst here.
+     *
+     * Running the survivor late cannot outpace the configured cadence: `advance`
+     * moves the cursor by exactly one `intervalMs` per occurrence from the nominal
+     * time, so a loop that keeps restarting still runs at most once per interval.
+     */
+    private skipRestartBacklog;
     /**
      * A run the store could not record is dropped, not retried: the cursor has
      * already moved, so this can never become a busy loop, and the outage is
@@ -86,5 +110,10 @@ export declare class ScheduledLoopManager implements ScheduledLoopManagerHandle
      * until the process was restarted.
      */
     private recover;
+    /**
+     * The envelope is the only channel a scheduled pass has for learning about
+     * the passes that did not happen. A gap stated here is what lets an oversight
+     * role report its own outage instead of resuming as if nothing was missed.
+     */
     private envelope;
 }

package/dist/loops/manager.js

@@ -39,7 +39,7 @@ export class ScheduledLoopManager {
     }
     start() {
         if (!this.store.fresh)
-            this.skipRestartMisses();
+            this.skipRestartBacklog();
         this.schedule();
     }
     async stop() {
@@ -143,10 +143,15 @@ export class ScheduledLoopManager {
     async attempt(definition, state, scheduledAt) {
         const runId = `sl_${randomUUID()}`;
         const origin = { kind: 'scheduled-loop', loop: definition.name, runId };
-        const prompt = this.envelope(definition, runId, scheduledAt);
+        // The gap is read here and cleared only if the turn is actually admitted:
+        // an attempt that ends `skipped_busy` or `unavailable` reported it to
+        // nobody, so it has to still be there for the attempt that succeeds.
+        const gap = state.missedGap;
+        const prompt = this.envelope(definition, runId, scheduledAt, gap);
         let claimed = false;
         const result = await this.arbiter.tryScheduled(prompt, origin, () => {
             claimed = true;
+            state.missedGap = null;
             state.activeRunId = runId;
             state.lastRunId = runId;
             state.lastStartedAt = new Date(this.deps.now()).toISOString();
@@ -265,7 +270,15 @@ export class ScheduledLoopManager {
         state.nextScheduledAt = new Date(next).toISOString();
         state.nextDueAt = new Date(next + deterministicJitter(this.role, definition.name, next, definition.jitterMs)).toISOString();
     }
+    /**
+     * Coalesce a backlog into one skip. The counters alone say how many
+     * occurrences were lost but never when or for how long, so the window is
+     * recorded too and carried on the state until a run is actually told about it
+     * — a dropped pass has to stay visible to the next one, not just to whoever
+     * was reading the log at the time.
+     */
     skipMissed(definition, state, now) {
+        const from = state.nextScheduledAt;
         let missed = 0;
         while (Date.parse(state.nextDueAt) <= now) {
             this.advance(definition, state);
@@ -275,14 +288,43 @@ export class ScheduledLoopManager {
         state.counts.skippedMissed = increment(state.counts.skippedMissed, missed);
         state.lastOutcome = 'skipped_missed';
         state.lastFinishedAt = new Date(now).toISOString();
+        // Successive outages before any run lands merge into one gap: the earliest
+        // start wins, so the window always spans the whole silence.
+        const previous = state.missedGap;
+        state.missedGap = {
+            count: increment(previous?.count ?? 0, missed),
+            fromAt: previous?.fromAt ?? from,
+            throughAt: state.lastScheduledAt ?? from,
+            detectedAt: new Date(now).toISOString(),
+        };
         this.store.persist();
-        this.deps.log(`[${this.role}] loop ${definition.name} skipped_missed count=${missed}`);
+        this.deps.log(`[${this.role}] loop ${definition.name} skipped_missed count=${missed} `
+            + `gap=${from}..${state.missedGap.throughAt} `
+            + `unreported=${state.missedGap.count}`);
     }
-    skipRestartMisses() {
+    /**
+     * Restart is not, by itself, a reason to lose an occurrence a running manager
+     * would still have run. `poll` tolerates lateness up to one full interval and
+     * runs the tick late; this path used to drop anything already due however
+     * recently, so a role restarted seconds after its own tick came due lost it
+     * outright. For an oversight role that is precisely the pass which would have
+     * recorded why it restarted, so the failure erased its own witness.
+     *
+     * The tolerance is the only thing shared with `poll`. A backlog at least one
+     * interval deep is still coalesced into a single skip and never replayed —
+     * after a long outage exactly one occurrence survives, and `schedule` then
+     * arms it through the ordinary path rather than firing a burst here.
+     *
+     * Running the survivor late cannot outpace the configured cadence: `advance`
+     * moves the cursor by exactly one `intervalMs` per occurrence from the nominal
+     * time, so a loop that keeps restarting still runs at most once per interval.
+     */
+    skipRestartBacklog() {
         const now = this.deps.now();
         for (const definition of this.definitions.values()) {
             const state = this.store.state.loops[definition.name];
-            if (definition.enabled && !state.operatorDisabled && Date.parse(state.nextDueAt) <= now)
+            if (definition.enabled && !state.operatorDisabled
+                && now >= Date.parse(state.nextDueAt) + definition.intervalMs)
                 this.skipMissed(definition, state, now);
         }
     }
@@ -340,17 +382,38 @@ export class ScheduledLoopManager {
             this.deps.clearTimer(this.timer);
         this.arm(backoffMs(this.pollFailures));
     }
-    envelope(definition, runId, scheduledAt) {
+    /**
+     * The envelope is the only channel a scheduled pass has for learning about
+     * the passes that did not happen. A gap stated here is what lets an oversight
+     * role report its own outage instead of resuming as if nothing was missed.
+     */
+    envelope(definition, runId, scheduledAt, gap) {
+        const lateBy = Math.max(0, this.deps.now() - scheduledAt);
         return [
             '[fleet-loop]',
             `loop: ${definition.name}`,
             `run: ${runId}`,
             `scheduled_at: ${new Date(scheduledAt).toISOString()}`,
+            ...(lateBy > 0 ? [`started_late_by_ms: ${lateBy}`] : []),
+            ...(gap ? [
+                `missed_occurrences: ${gap.count}`,
+                `missed_window: ${gap.fromAt}..${gap.throughAt}`,
+                `missed_gap_ms: ${Math.max(0, Date.parse(gap.detectedAt) - Date.parse(gap.fromAt))}`,
+            ] : []),
             'origin: local-trusted-config',
             '',
             'This is a scheduled internal maintenance turn, not an owner message and not ordinary ours mail.',
             'Perform one bounded pass. Do not wait for the next tick. Do not report to an owner unless your',
             'configured policy and an existing authenticated proactive-report route authorize a material report.',
+            // Same single route as the owner-request prompt, and for the same reason.
+            'To send a file, call ours `send_file` with the recipient and the path — to your owner-channel',
+            'identity if this role has one, otherwise directly to the contact who should receive it.',
+            'A file written anywhere else is not delivered and nothing will report that it was not.',
+            ...(gap ? ['',
+                'This loop did not run for the window above: those occurrences were coalesced away while the role',
+                'was unavailable, and this pass is the first since. Treat the gap as part of what you are reporting',
+                'on — it is the record of your own outage, and no later pass will be told about it.',
+            ] : []),
             '',
             definition.prompt,
         ].join('\n');

package/dist/loops/state.d.ts

@@ -8,11 +8,29 @@ export interface LoopCounts {
     skippedBusy: number;
     skippedMissed: number;
 }
+/**
+ * A coalesced run of occurrences that were never submitted, held until a run
+ * actually starts and can be told about it. Without it a dropped occurrence
+ * survives only as a counter, which says how many were lost but never when or
+ * for how long — and an oversight role cannot report an outage it cannot date.
+ */
+export interface LoopMissedGap {
+    /** Occurrences coalesced away, summed across every skip since the last run. */
+    count: number;
+    /** Nominal time of the earliest occurrence in the gap. */
+    fromAt: string;
+    /** Nominal time of the latest occurrence in the gap. */
+    throughAt: string;
+    /** When the manager noticed — the end of the outage, not of the last skip. */
+    detectedAt: string;
+}
 export interface LoopRuntimeState {
     definitionHash: string;
     promptHash: string;
     enabled: boolean;
     operatorDisabled: boolean;
+    /** Unreported gap, cleared by the first run that carries it. */
+    missedGap: LoopMissedGap | null;
     nextScheduledAt: string;
     nextDueAt: string;
     lastScheduledAt: string | null;