@ours.network/fleet 0.18.0-nightly.5 → 0.18.0

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,7 @@ export interface BriefingVocab {
     currentIdentityTool: string;
     sendTool: string;
     getMessagesTool: string;
+    watchCommand(identity: string): 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;
@@ -95,7 +122,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 +138,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;

package/dist/harness-plugins.d.ts

@@ -0,0 +1,48 @@
+import { type Exec } from './exec.js';
+export declare const HARNESS_PLUGIN_IDS: readonly ["codex", "claude-code"];
+export type HarnessPluginId = (typeof HARNESS_PLUGIN_IDS)[number];
+export type HarnessPluginChannel = 'stable' | 'nightly';
+export interface HarnessPluginConfig {
+    plugin_channel: HarnessPluginChannel;
+}
+export type HarnessPluginConfigs = Record<HarnessPluginId, HarnessPluginConfig>;
+export interface HarnessPluginLock {
+    schemaVersion: 1;
+    harness: HarnessPluginId;
+    channel: HarnessPluginChannel;
+    distTag: 'latest' | 'nightly';
+    package: string;
+    version: string;
+    registry: 'https://registry.npmjs.org';
+    resolvedAt: string;
+}
+export interface HarnessPluginInstallResult {
+    lock: HarnessPluginLock;
+    lockPath: string;
+    marketplacePath: string;
+    resolved: boolean;
+}
+export declare function resolveHarnessPluginConfigs(raw: unknown, file?: string): HarnessPluginConfigs;
+export declare const harnessPluginRoot: (harness: HarnessPluginId) => string;
+export declare const harnessPluginLockPath: (harness: HarnessPluginId) => string;
+export declare const harnessPluginMarketplaceRoot: (harness: HarnessPluginId) => string;
+export declare const harnessPluginMarketplacePath: (harness: HarnessPluginId) => string;
+export declare function readHarnessPluginLock(harness: HarnessPluginId): HarnessPluginLock | undefined;
+/**
+ * Re-materialize the generated marketplace from the persisted exact lock.
+ * This is the ONLY ordinary startup/reconciliation path: it performs no exec,
+ * no network call, and cannot observe a moving npm dist-tag.
+ */
+export declare function restoreLockedHarnessMarketplace(harness: HarnessPluginId, expectedChannel?: HarnessPluginChannel): HarnessPluginLock | undefined;
+/**
+ * Explicit install/update transaction.
+ *
+ * install reuses an existing same-channel lock (deterministic repair/reinstall);
+ * update always resolves the requested channel once and advances the lock.
+ */
+export declare function installHarnessPlugin(harness: HarnessPluginId, channel: HarnessPluginChannel, options?: {
+    update?: boolean;
+    exec?: Exec;
+    now?: () => Date;
+}): Promise<HarnessPluginInstallResult>;
+export declare function selectedHarnessPluginIds(values: string[]): HarnessPluginId[];

package/dist/harness-plugins.js

@@ -0,0 +1,309 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { replaceFileAtomically, withFileLock } from './atomic-file.js';
+import { realExec } from './exec.js';
+import { stateRoot } from './paths.js';
+export const HARNESS_PLUGIN_IDS = ['codex', 'claude-code'];
+const REGISTRY = 'https://registry.npmjs.org';
+const SPECS = {
+    codex: {
+        package: '@ours.network/codex',
+        marketplaceName: 'ours-fleet-codex-lock',
+        marketplaceManifest: '.agents/plugins/marketplace.json',
+        executable: 'codex',
+    },
+    'claude-code': {
+        package: '@ours.network/claude-code',
+        marketplaceName: 'ours-fleet-claude-lock',
+        marketplaceManifest: '.claude-plugin/marketplace.json',
+        executable: 'claude',
+    },
+};
+const EXACT_SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+export function resolveHarnessPluginConfigs(raw, file = 'fleet.yaml') {
+    const resolved = {
+        codex: { plugin_channel: 'stable' },
+        'claude-code': { plugin_channel: 'stable' },
+    };
+    if (raw === undefined)
+        return resolved;
+    if (!isRecord(raw))
+        throw new Error(`${file}: harnesses must be a map`);
+    const unknown = Object.keys(raw).filter(key => !HARNESS_PLUGIN_IDS.includes(key));
+    if (unknown.length)
+        throw new Error(`${file}: harnesses has unknown harness(es) ${unknown.join(', ')}; allowed: ${HARNESS_PLUGIN_IDS.join(', ')}`);
+    for (const harness of HARNESS_PLUGIN_IDS) {
+        const value = raw[harness];
+        if (value === undefined)
+            continue;
+        if (!isRecord(value))
+            throw new Error(`${file}: harnesses.${harness} must be a map`);
+        const bad = Object.keys(value).filter(key => key !== 'plugin_channel');
+        if (bad.length)
+            throw new Error(`${file}: harnesses.${harness} has unknown key(s) ${bad.join(', ')}; allowed: plugin_channel`);
+        const channel = value.plugin_channel;
+        if (channel !== 'stable' && channel !== 'nightly')
+            throw new Error(`${file}: harnesses.${harness}.plugin_channel must be one of: stable, nightly`);
+        resolved[harness] = { plugin_channel: channel };
+    }
+    return resolved;
+}
+export const harnessPluginRoot = (harness) => join(stateRoot(), 'harness-plugins', harness);
+export const harnessPluginLockPath = (harness) => join(harnessPluginRoot(harness), 'plugin-lock.json');
+export const harnessPluginMarketplaceRoot = (harness) => join(harnessPluginRoot(harness), 'marketplace');
+export const harnessPluginMarketplacePath = (harness) => join(harnessPluginMarketplaceRoot(harness), SPECS[harness].marketplaceManifest);
+function validateLock(value, harness, path) {
+    const spec = SPECS[harness];
+    const fail = (detail) => {
+        throw new Error(`invalid harness plugin lock ${path}: ${detail}; run \`ours-fleet plugins update ${harness}\``);
+    };
+    if (!isRecord(value))
+        return fail('expected a JSON object');
+    if (value.schemaVersion !== 1)
+        fail('unsupported schemaVersion');
+    if (value.harness !== harness)
+        fail(`harness must be '${harness}'`);
+    if (value.channel !== 'stable' && value.channel !== 'nightly')
+        fail('channel must be stable or nightly');
+    const expectedTag = value.channel === 'stable' ? 'latest' : 'nightly';
+    if (value.distTag !== expectedTag)
+        fail(`distTag must be '${expectedTag}' for channel '${value.channel}'`);
+    if (value.package !== spec.package)
+        fail(`package must be '${spec.package}'`);
+    if (typeof value.version !== 'string' || !EXACT_SEMVER.test(value.version))
+        return fail('version must be an exact semver');
+    const version = value.version;
+    if (value.channel === 'stable' && version.includes('-'))
+        fail('stable channel resolved to a prerelease');
+    if (value.channel === 'nightly' && !version.includes('-nightly.'))
+        fail('nightly channel did not resolve to a -nightly.N prerelease');
+    if (value.registry !== REGISTRY)
+        fail(`registry must be '${REGISTRY}'`);
+    if (typeof value.resolvedAt !== 'string' || !Number.isFinite(Date.parse(value.resolvedAt)))
+        fail('resolvedAt must be an ISO timestamp');
+    return value;
+}
+export function readHarnessPluginLock(harness) {
+    const path = harnessPluginLockPath(harness);
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`invalid harness plugin lock ${path}: ${error.message}; `
+            + `run \`ours-fleet plugins update ${harness}\``);
+    }
+    return validateLock(parsed, harness, path);
+}
+function marketplaceDocument(lock) {
+    const spec = SPECS[lock.harness];
+    const source = lock.harness === 'codex'
+        ? { source: 'npm', package: lock.package, version: lock.version, registry: lock.registry }
+        : { source: 'npm', package: lock.package, version: lock.version };
+    if (lock.harness === 'codex') {
+        return {
+            name: spec.marketplaceName,
+            interface: { displayName: `ours.network (${lock.channel}, locked ${lock.version})` },
+            plugins: [{
+                    name: 'ours', source,
+                    policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+                    category: 'Productivity',
+                }],
+        };
+    }
+    return {
+        $schema: 'https://json.schemastore.org/claude-code-marketplace.json',
+        name: spec.marketplaceName,
+        owner: { name: 'Adapt Framework Solutions Ltd', url: 'https://ours.network' },
+        description: `Generated by ours-fleet; @ours.network/claude-code is locked to ${lock.version}.`,
+        plugins: [{
+                name: 'ours', source,
+                description: 'Secure ours.network messaging for Claude Code.',
+            }],
+    };
+}
+function writeMarketplace(lock) {
+    const path = harnessPluginMarketplacePath(lock.harness);
+    replaceFileAtomically(path, `${JSON.stringify(marketplaceDocument(lock), null, 2)}\n`, 0o644);
+    return path;
+}
+/**
+ * Re-materialize the generated marketplace from the persisted exact lock.
+ * This is the ONLY ordinary startup/reconciliation path: it performs no exec,
+ * no network call, and cannot observe a moving npm dist-tag.
+ */
+export function restoreLockedHarnessMarketplace(harness, expectedChannel) {
+    const lock = readHarnessPluginLock(harness);
+    if (!lock) {
+        if (expectedChannel === 'nightly')
+            throw new Error(`harness '${harness}' requests nightly but has no exact lock; `
+                + `run \`ours-fleet plugins install ${harness}\``);
+        return undefined;
+    }
+    if (expectedChannel && lock.channel !== expectedChannel)
+        throw new Error(`harness '${harness}' requests ${expectedChannel} but its exact lock is ${lock.channel} `
+            + `(${lock.version}); run \`ours-fleet plugins update ${harness}\``);
+    if (lock)
+        writeMarketplace(lock);
+    return lock;
+}
+async function checked(exec, command, args, action) {
+    const result = await exec(command, args);
+    if (result.code !== 0)
+        throw new Error(`${action} failed (${command} ${args.join(' ')}): ${result.stderr.trim() || result.stdout.trim() || `exit ${result.code}`}`);
+    return result;
+}
+function parseJson(output, action) {
+    try {
+        return JSON.parse(output);
+    }
+    catch (error) {
+        throw new Error(`${action} returned invalid JSON: ${error.message}`);
+    }
+}
+async function resolveExactVersion(harness, channel, exec, now) {
+    const spec = SPECS[harness];
+    const distTag = channel === 'stable' ? 'latest' : 'nightly';
+    const result = await checked(exec, 'npm', ['view', `${spec.package}@${distTag}`, 'version', '--json'], `resolve ${spec.package} ${distTag}`);
+    const version = parseJson(result.stdout, `npm view ${spec.package}@${distTag}`);
+    if (typeof version !== 'string' || !EXACT_SEMVER.test(version))
+        throw new Error(`npm view ${spec.package}@${distTag} did not return one exact semver`);
+    if (channel === 'stable' && version.includes('-'))
+        throw new Error(`refusing stable ${spec.package}: npm latest resolved to prerelease ${version}`);
+    if (channel === 'nightly' && !version.includes('-nightly.'))
+        throw new Error(`refusing nightly ${spec.package}: npm nightly resolved to ${version}`);
+    return {
+        schemaVersion: 1,
+        harness,
+        channel,
+        distTag,
+        package: spec.package,
+        version,
+        registry: REGISTRY,
+        resolvedAt: now().toISOString(),
+    };
+}
+function marketplaceEntries(harness, output) {
+    const parsed = parseJson(output, `${SPECS[harness].executable} plugin marketplace list`);
+    if (harness === 'codex') {
+        if (!isRecord(parsed) || !Array.isArray(parsed.marketplaces))
+            throw new Error('codex plugin marketplace list returned an unexpected shape');
+        return parsed.marketplaces.filter(isRecord);
+    }
+    if (!Array.isArray(parsed))
+        throw new Error('claude plugin marketplace list returned an unexpected shape');
+    return parsed.filter(isRecord);
+}
+async function ensureMarketplaceRegistered(harness, exec) {
+    const spec = SPECS[harness];
+    const root = harnessPluginMarketplaceRoot(harness);
+    const result = await checked(exec, spec.executable, ['plugin', 'marketplace', 'list', '--json'], `list ${harness} marketplaces`);
+    const existing = marketplaceEntries(harness, result.stdout)
+        .find(entry => entry.name === spec.marketplaceName);
+    if (existing) {
+        if (harness === 'codex') {
+            const declared = isRecord(existing.marketplaceSource)
+                ? existing.marketplaceSource.source : existing.root;
+            if (typeof declared !== 'string' || resolve(declared) !== resolve(root))
+                throw new Error(`marketplace '${spec.marketplaceName}' already exists but does not point to ${root}; `
+                    + 'refusing to replace an unrelated marketplace');
+        }
+        else {
+            // Claude copies marketplace contents into its cache, but retains the
+            // source kind in list output. Refresh that copy after each lock update.
+            if (existing.source !== 'directory')
+                throw new Error(`marketplace '${spec.marketplaceName}' already exists but is not a local directory; `
+                    + 'refusing to replace an unrelated marketplace');
+            await checked(exec, 'claude', ['plugin', 'marketplace', 'update', spec.marketplaceName], `refresh ${harness} locked marketplace`);
+        }
+        return;
+    }
+    const args = harness === 'codex'
+        ? ['plugin', 'marketplace', 'add', root, '--json']
+        : ['plugin', 'marketplace', 'add', root, '--scope', 'user'];
+    await checked(exec, spec.executable, args, `register ${harness} locked marketplace`);
+}
+async function removeLegacyPluginSelections(harness, exec) {
+    const spec = SPECS[harness];
+    const result = await checked(exec, spec.executable, ['plugin', 'list', '--json'], `list ${harness} plugins`);
+    const parsed = parseJson(result.stdout, `${spec.executable} plugin list`);
+    if (harness === 'codex' && (!isRecord(parsed) || !Array.isArray(parsed.installed)))
+        throw new Error('codex plugin list returned an unexpected shape');
+    if (harness === 'claude-code' && !Array.isArray(parsed))
+        throw new Error('claude plugin list returned an unexpected shape');
+    const entries = (harness === 'codex'
+        ? parsed.installed
+        : parsed).filter(isRecord);
+    const ids = new Set(entries
+        .map(entry => harness === 'codex' ? entry.pluginId : entry.id)
+        .filter((id) => typeof id === 'string'));
+    const legacy = harness === 'codex'
+        ? ['ours@ours-codex-marketplace', 'ours-fleet@ours-codex-marketplace']
+        : ['ours@ours', 'ours@ours.network'];
+    for (const selector of legacy.filter(id => ids.has(id))) {
+        const args = harness === 'codex'
+            ? ['plugin', 'remove', selector, '--json']
+            : ['plugin', 'uninstall', selector, '--scope', 'user', '--keep-data'];
+        await checked(exec, spec.executable, args, `remove legacy moving selection ${selector}`);
+    }
+}
+async function installFromLock(lock, exec) {
+    const spec = SPECS[lock.harness];
+    // The Codex package also owns the ours-codex launcher. Pin that executable to
+    // the same exact artifact as the local marketplace; never invoke its broad
+    // installer, which may select daemon/SDK packages outside this feature.
+    if (lock.harness === 'codex') {
+        await checked(exec, 'npm', ['install', '--global', `${lock.package}@${lock.version}`], `install ${lock.package}@${lock.version}`);
+    }
+    await ensureMarketplaceRegistered(lock.harness, exec);
+    const selector = `ours@${spec.marketplaceName}`;
+    const args = lock.harness === 'codex'
+        ? ['plugin', 'add', selector, '--json']
+        : ['plugin', 'install', selector, '--scope', 'user'];
+    await checked(exec, spec.executable, args, `install ${selector}`);
+    // The same plugin under an older Git marketplace is a distinct harness
+    // selection and can remain enabled beside the lock. Remove only the known
+    // ours selectors, after the exact local selection is installed successfully.
+    await removeLegacyPluginSelections(lock.harness, exec);
+}
+/**
+ * Explicit install/update transaction.
+ *
+ * install reuses an existing same-channel lock (deterministic repair/reinstall);
+ * update always resolves the requested channel once and advances the lock.
+ */
+export async function installHarnessPlugin(harness, channel, options = {}) {
+    const exec = options.exec ?? realExec;
+    const root = harnessPluginRoot(harness);
+    return withFileLock(`${root}.lock`, async () => {
+        const existing = readHarnessPluginLock(harness);
+        const mustResolve = options.update === true || !existing || existing.channel !== channel;
+        const lock = mustResolve
+            ? await resolveExactVersion(harness, channel, exec, options.now ?? (() => new Date()))
+            : existing;
+        if (mustResolve)
+            replaceFileAtomically(harnessPluginLockPath(harness), `${JSON.stringify(lock, null, 2)}\n`);
+        // Publish the lock first. If installation is interrupted, every retry uses
+        // this same exact version; no half-finished transaction can observe a newer
+        // dist-tag on its own.
+        const marketplacePath = writeMarketplace(lock);
+        await installFromLock(lock, exec);
+        return {
+            lock,
+            lockPath: harnessPluginLockPath(harness),
+            marketplacePath,
+            resolved: mustResolve,
+        };
+    });
+}
+export function selectedHarnessPluginIds(values) {
+    if (!values.length)
+        return [...HARNESS_PLUGIN_IDS];
+    const unknown = values.filter(value => !HARNESS_PLUGIN_IDS.includes(value));
+    if (unknown.length)
+        throw new Error(`unknown harness(es) ${unknown.join(', ')}; allowed: ${HARNESS_PLUGIN_IDS.join(', ')}`);
+    return [...new Set(values)];
+}

package/dist/index.d.ts

@@ -28,3 +28,5 @@ export { doctor } from './doctor.js';
 export { runOnce, runTemp } from './runner.js';
 export { Tmux } from './tmux.js';
 export { VERSION } from './version.js';
+export { HARNESS_PLUGIN_IDS, installHarnessPlugin, readHarnessPluginLock, restoreLockedHarnessMarketplace, resolveHarnessPluginConfigs, } from './harness-plugins.js';
+export type { HarnessPluginId, HarnessPluginChannel, HarnessPluginConfig, HarnessPluginConfigs, HarnessPluginLock, HarnessPluginInstallResult, } from './harness-plugins.js';

package/dist/index.js

@@ -23,3 +23,4 @@ export { doctor } from './doctor.js';
 export { runOnce, runTemp } from './runner.js';
 export { Tmux } from './tmux.js';
 export { VERSION } from './version.js';
+export { HARNESS_PLUGIN_IDS, installHarnessPlugin, readHarnessPluginLock, restoreLockedHarnessMarketplace, resolveHarnessPluginConfigs, } from './harness-plugins.js';

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;