@phnx-labs/agents-cli 1.20.93 → 1.21.1

package/dist/lib/daemon.js

@@ -24,6 +24,7 @@ import { BrowserService } from './browser/service.js';
 import { BrowserIPCServer } from './browser/ipc.js';
 import { redactSecrets } from './redact.js';
 import { getAgentsBinPath, getCliLaunch, BUN_VIRTUAL_ROOT } from './cli-entry.js';
+import { isSchedulerEnabled, assertSchedulerEnabled } from './device-config.js';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
 const LOG_FILE = 'logs.jsonl';
@@ -53,6 +54,11 @@ const WEDGE_THRESHOLD_TICKS = 3;
 export function shouldTakeOverBroker(isHosting, brokerReachable) {
     return !isHosting && !brokerReachable;
 }
+export function schedulerGateTransition(running, enabled) {
+    if (running)
+        return enabled ? 'reload' : 'stop';
+    return enabled ? 'boot' : 'none';
+}
 function getDaemonDir() {
     const dir = getDaemonDirRoot();
     fs.mkdirSync(dir, { recursive: true });
@@ -398,7 +404,7 @@ export async function runDaemon() {
         log('ERROR', `Stray daemon reaper failed: ${err.message}`);
     }
     // #416: host the secrets broker socket-first — before the scheduler and the
-    // heavy browser/session-sync services — so `agents secrets` resolves within
+    // heavy browser services — so `agents secrets` resolves within
     // ms of daemon start. Only host when no broker is already reachable, so we
     // never orphan a live standalone broker's clients (that broker stays the
     // server until it idle-exits or the daemon restarts). Best-effort: a failure
@@ -419,7 +425,23 @@ export async function runDaemon() {
     catch (err) {
         log('WARN', `Secrets broker host skipped: ${err.message}`);
     }
-    const scheduler = new JobScheduler(async (config) => {
+    // scheduler.enabled=false in this machine's device doc means NO routines fire
+    // here — the scheduler and its catchup recovery simply never start, while the
+    // daemon keeps its other duties (secrets broker, browser IPC, session sync).
+    // The refusal message is the same one the start surfaces
+    // (`routines add` auto-start, manual `routines start`) raise. The gate is
+    // re-evaluated on every SIGHUP reload (handleReload below) via
+    // schedulerGateTransition, so flipping the key never needs a daemon restart.
+    const schedulerEnabledAtBoot = isSchedulerEnabled();
+    if (!schedulerEnabledAtBoot) {
+        try {
+            assertSchedulerEnabled();
+        }
+        catch (err) {
+            log('WARN', err.message);
+        }
+    }
+    const triggerJob = async (config) => {
         const jobLabel = config.command
             ? 'command'
             : config.workflow
@@ -458,7 +480,36 @@ export async function runDaemon() {
             }
             catch { /* best-effort */ }
         }
-    });
+    };
+    let scheduler = null;
+    let catchupInterval;
+    // Catchup overlap guard. Declared up here (not beside catchupPass) because
+    // bootScheduler() runs before catchupPass's textual position — a `let` down
+    // there would still be in its TDZ at the first call and crash the daemon.
+    let catchingUp = false;
+    // Boot the scheduler + catchup recovery. Called at daemon start when the gate
+    // allows, and again from handleReload when the gate flips on (function
+    // declarations hoist — catchupPass below is in scope).
+    function bootScheduler() {
+        scheduler = new JobScheduler(triggerJob);
+        scheduler.loadAll();
+        const scheduled = scheduler.listScheduled();
+        log('INFO', `Loaded ${scheduled.length} jobs`);
+        for (const job of scheduled) {
+            log('INFO', `  ${job.name} -> next: ${job.nextRun?.toISOString() || 'unknown'}`);
+        }
+        void catchupPass();
+        catchupInterval = setInterval(() => { void catchupPass(); }, CATCHUP_TICK_MS);
+    }
+    // Stop the scheduler + catchup recovery (gate flipped off on reload).
+    function stopScheduler() {
+        scheduler?.stopAll();
+        scheduler = null;
+        if (catchupInterval !== undefined) {
+            clearInterval(catchupInterval);
+            catchupInterval = undefined;
+        }
+    }
     // Materialise opted-in project routines into the user layer on every start
     // so a fresh daemon picks up project YAML without a separate sync step.
     try {
@@ -470,12 +521,8 @@ export async function runDaemon() {
     catch (err) {
         log('WARN', `Project routines sync failed: ${err.message}`);
     }
-    scheduler.loadAll();
-    const scheduled = scheduler.listScheduled();
-    log('INFO', `Loaded ${scheduled.length} jobs`);
-    for (const job of scheduled) {
-        log('INFO', `  ${job.name} -> next: ${job.nextRun?.toISOString() || 'unknown'}`);
-    }
+    if (schedulerEnabledAtBoot)
+        bootScheduler();
     // Monitor engine: event-triggered watchers, beside the cron scheduler. Same
     // daemon, same dispatch seam — a monitor is a routine whose trigger is a
     // watched source instead of a clock. Reloads on SIGHUP alongside the scheduler.
@@ -495,15 +542,16 @@ export async function runDaemon() {
     // `catchup: false`, RUN late. Runs on a timer as well as at startup: a startup
     // pass alone misses a fire lost while the daemon stayed up but its event loop
     // was wedged, or one lost across an OS suspend that the process survived.
-    // Overlap guard, same shape as runSessionSync/runHealCheck below. A pass
+    // Overlap guard, same shape as runHealCheck below. A pass
     // awaits executeJobDetached per job and an off-box (host/cloud) dispatch can
     // block for a while, so a slow pass could still be working when the next tick
     // fires. Both passes would then see a job the first has not yet reached as
     // overdue — the miss is recorded before the await, but only for jobs already
     // processed — and spawn it twice. The idempotency of the `missed` record
     // guards across passes, not within one that is mid-flight.
-    let catchingUp = false;
-    const catchupPass = async () => {
+    // Function declaration (hoisted) so bootScheduler() can schedule it. Its
+    // guard (`catchingUp`) is declared beside `scheduler` above for TDZ safety.
+    async function catchupPass() {
         if (catchingUp)
             return;
         catchingUp = true;
@@ -553,9 +601,7 @@ export async function runDaemon() {
             // throw must not leave the guard latched shut for the daemon's lifetime.
             catchingUp = false;
         }
-    };
-    await catchupPass();
-    const catchupInterval = setInterval(() => { void catchupPass(); }, CATCHUP_TICK_MS);
+    }
     // Before the BrowserService comes up, reap browser + tunnel processes
     // spawned by previous daemons that are no longer alive. Without this,
     // a daemon hard-crash (SIGKILL, OOM) would leak every browser and SSH
@@ -588,42 +634,6 @@ export async function runDaemon() {
         writeHeartbeat();
         monitorRunningJobs();
     }, MONITOR_TICK_MS);
-    // Cross-machine session sync: push this machine's transcripts to R2 and pull
-    // every other machine's, ~every 90s. Skipped silently when the r2.backups
-    // bundle is absent. An overlap guard prevents a slow cycle from stacking.
-    let syncing = false;
-    const runSessionSync = async () => {
-        if (syncing)
-            return;
-        syncing = true;
-        try {
-            const { isBetaEnabled } = await import('./beta.js');
-            // Off by default: session sync is an opt-in beta feature. Check the beta
-            // flag FIRST so a machine that hasn't opted in skips the keychain read
-            // (isSyncConfigured) entirely, not just the network cycle.
-            if (!isBetaEnabled('session-sync'))
-                return;
-            const { isSyncConfigured } = await import('./session/sync/config.js');
-            if (!isSyncConfigured())
-                return;
-            const { syncSessions } = await import('./session/sync/sync.js');
-            const r = await syncSessions();
-            if (r.pushed || r.pulled || r.errors.length) {
-                log('INFO', `sessions sync: pushed ${r.pushed}, pulled ${r.pulled}, merged ${r.merged}` +
-                    (r.errors.length ? `, ${r.errors.length} error(s): ${r.errors[0]}` : ''));
-            }
-            if (r.warnings.length)
-                log('WARN', `sessions sync: ${r.warnings[0]}`);
-        }
-        catch (err) {
-            log('ERROR', `sessions sync failed: ${err.message}`);
-        }
-        finally {
-            syncing = false;
-        }
-    };
-    const syncInterval = setInterval(() => { void runSessionSync(); }, 90_000);
-    void runSessionSync(); // kick once at startup
     // Resource safety check: heal gaps between what DotAgents repos define and
     // what's actually installed in each agent home — the slow rot that nothing
     // else catches (a non-default version left stale, a Claude-invalid plugin
@@ -875,27 +885,37 @@ export async function runDaemon() {
         catch (err) {
             log('WARN', `Project routines sync failed: ${err.message}`);
         }
-        scheduler.reloadAll();
-        const reloaded = scheduler.listScheduled();
-        log('INFO', `Reloaded ${reloaded.length} jobs`);
+        // Re-evaluate the scheduler.enabled gate: flipping the key takes effect on
+        // this reload, no daemon restart needed. A `routines add` on a re-enabled
+        // box signals exactly this reload, which boots the scheduler — the
+        // "Scheduler reloaded" it prints is then truthful, not a dead-end.
+        const transition = schedulerGateTransition(scheduler !== null, isSchedulerEnabled());
+        if (transition === 'boot') {
+            log('INFO', 'scheduler.enabled is now on — booting the scheduler');
+            bootScheduler();
+        }
+        else if (transition === 'stop') {
+            log('WARN', 'scheduler.enabled is now off — stopping the scheduler; no routines will fire on this device');
+            stopScheduler();
+        }
+        else if (transition === 'reload') {
+            scheduler.reloadAll();
+            const reloaded = scheduler.listScheduled();
+            log('INFO', `Reloaded ${reloaded.length} jobs`);
+        }
         try {
             monitorEngine.reload();
         }
         catch (err) {
             log('ERROR', `Monitor engine reload failed: ${err.message}`);
         }
-        // Drop the memoized R2 config so rotated/added sync credentials are re-read
-        // on the next cycle instead of waiting for a restart.
-        void import('./session/sync/config.js').then(m => m.clearR2ConfigCache());
     };
     const handleShutdown = async () => {
         log('INFO', 'Daemon shutting down');
-        scheduler.stopAll();
+        stopScheduler();
         monitorEngine.stop();
         await browserIPC.stop();
         clearInterval(monitorInterval);
-        clearInterval(catchupInterval);
-        clearInterval(syncInterval);
         clearInterval(healInterval);
         clearTimeout(healKickoff);
         clearInterval(autoDispatchInterval);

package/dist/lib/device-config.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Device/user config keys — typed read/write over the two-tier agents.yaml store.
+ *
+ * One registry (`CONFIG_KEYS`) maps each CLI dotted name to where it lives:
+ *   - user scope   → central `~/.agents/agents.yaml` under `config:` (syncs
+ *                    fleet-wide via `agents repo push/pull`)
+ *   - device scope → `~/.agents/devices/<host>/agents.yaml` under `config:`
+ *                    (per-machine; mirrors how `defaultBrowserProfile` is routed)
+ *
+ * This machine's keys go through the readMeta/updateMeta funnel (state.ts) so the
+ * partition/overlay logic stays the single writer. Another device's doc is
+ * read/written in place — the devices/ tree syncs via the DotAgents repo, so
+ * editing `devices/mac-mini/agents.yaml` locally is how `configure`/`note`
+ * target a peer (`--device`-style).
+ *
+ * `browser.profile` is NOT a `config:` key — it is the existing
+ * `Meta.defaultBrowserProfile` field; the registry entry documents the mapping
+ * and set/get route to it so there is one source of truth (no duplicate key).
+ *
+ * Unset always means today's behavior.
+ */
+/** Which tier of the agents.yaml store a key lives in. */
+export type ConfigScope = 'user' | 'device';
+/** Value type of a config key — drives validation and `--json` rendering. */
+export type ConfigType = 'string' | 'int' | 'bool' | 'string-list';
+/** One known config key. */
+export interface ConfigKeySpec {
+    /** CLI dotted name, e.g. `interactive.host`. */
+    name: string;
+    /** camelCase key under the YAML `config:` block. */
+    yamlKey: string;
+    scope: ConfigScope;
+    type: ConfigType;
+    /** One-line description for help/list output. */
+    description: string;
+    /**
+     * When set, the value lives in this top-level Meta field instead of the
+     * `config:` block (only `browser.profile` → `defaultBrowserProfile` today).
+     */
+    field?: 'defaultBrowserProfile';
+    /** Extra validation beyond the type check; return an error string or null. */
+    validate?: (value: unknown) => string | null;
+}
+/** A key with its resolved value and the layer that set it. */
+export interface ConfigEntry {
+    spec: ConfigKeySpec;
+    /** The stored value, or undefined when unset (unset = default behavior). */
+    value: unknown;
+    /** Which layer set it; undefined when unset. */
+    layer?: ConfigScope;
+}
+/** Options scoping a read/write to a specific device's doc (default: this machine). */
+export interface ConfigTarget {
+    device?: string;
+}
+export declare const CONFIG_KEYS: readonly ConfigKeySpec[];
+/** Look up a key spec by CLI dotted name, or throw listing the known keys. */
+export declare function configKeySpec(name: string): ConfigKeySpec;
+/** Get one config key's value and the layer that set it. */
+export declare function getConfigValue(name: string, opts?: ConfigTarget): ConfigEntry;
+/** List every known key with its value and the layer that set it. */
+export declare function listConfig(opts?: ConfigTarget): ConfigEntry[];
+/** Set a config key (validated). Device-scope keys target this machine unless `opts.device` names a peer. */
+export declare function setConfigValue(name: string, value: unknown, opts?: ConfigTarget): void;
+/** Unset a config key — restores default behavior. No-op when already unset. */
+export declare function unsetConfigValue(name: string, opts?: ConfigTarget): void;
+/** True unless this machine's device doc disables the routines scheduler. */
+export declare function isSchedulerEnabled(): boolean;
+/**
+ * Throw when the routines scheduler is disabled on this machine, naming the
+ * setting and the fix. The single message every scheduler-start surface
+ * (auto-start on `routines add`, manual `routines start`, the daemon's own
+ * scheduler init) refuses with.
+ */
+export declare function assertSchedulerEnabled(): void;
+/**
+ * Read the `agents.max-concurrent` cap for each named device from its synced
+ * device doc (no SSH). Devices without a cap are omitted — uncapped is the
+ * default. Used as an input to host ranking (teams placement, Factory
+ * auto-launch), never as a remote probe.
+ */
+export declare function readMaxConcurrentCaps(devices: string[]): Record<string, number>;

package/dist/lib/device-config.js

@@ -0,0 +1,296 @@
+/**
+ * Device/user config keys — typed read/write over the two-tier agents.yaml store.
+ *
+ * One registry (`CONFIG_KEYS`) maps each CLI dotted name to where it lives:
+ *   - user scope   → central `~/.agents/agents.yaml` under `config:` (syncs
+ *                    fleet-wide via `agents repo push/pull`)
+ *   - device scope → `~/.agents/devices/<host>/agents.yaml` under `config:`
+ *                    (per-machine; mirrors how `defaultBrowserProfile` is routed)
+ *
+ * This machine's keys go through the readMeta/updateMeta funnel (state.ts) so the
+ * partition/overlay logic stays the single writer. Another device's doc is
+ * read/written in place — the devices/ tree syncs via the DotAgents repo, so
+ * editing `devices/mac-mini/agents.yaml` locally is how `configure`/`note`
+ * target a peer (`--device`-style).
+ *
+ * `browser.profile` is NOT a `config:` key — it is the existing
+ * `Meta.defaultBrowserProfile` field; the registry entry documents the mapping
+ * and set/get route to it so there is one source of truth (no duplicate key).
+ *
+ * Unset always means today's behavior.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { META_HEADER, getUserAgentsDir, readMeta, updateMeta } from './state.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
+import { machineId } from './machine-id.js';
+import { assertValidDeviceName } from './devices/registry.js';
+export const CONFIG_KEYS = [
+    {
+        name: 'interactive.host',
+        yamlKey: 'interactiveHost',
+        scope: 'user',
+        type: 'string',
+        description: 'Device that shows the user artifacts (browser opens, dashboards) — the "online macOS box" skills should use instead of guessing.',
+        validate: (v) => {
+            try {
+                assertValidDeviceName(v);
+                return null;
+            }
+            catch (err) {
+                return err?.message ?? String(err);
+            }
+        },
+    },
+    {
+        name: 'browser.profile',
+        yamlKey: 'defaultBrowserProfile',
+        scope: 'device',
+        type: 'string',
+        field: 'defaultBrowserProfile',
+        description: 'Browser profile `agents browser start` resolves to without --profile (set via `agents browser profiles set-default`).',
+    },
+    {
+        name: 'agents.max-concurrent',
+        yamlKey: 'maxAgents',
+        scope: 'device',
+        type: 'int',
+        description: 'Cap on concurrent agents on this device. What counts toward it depends on the consumer: ' +
+            'Factory auto-launch counts device-wide running agents; teams placement counts the team’s own roster on the device.',
+        validate: (v) => (v >= 1 ? null : 'agents.max-concurrent must be >= 1.'),
+    },
+    {
+        name: 'scheduler.enabled',
+        yamlKey: 'schedulerEnabled',
+        scope: 'device',
+        type: 'bool',
+        description: 'Whether the routines scheduler (daemon) may fire on this device.',
+    },
+    {
+        name: 'notes',
+        yamlKey: 'notes',
+        scope: 'device',
+        type: 'string-list',
+        description: 'Free-form operator notes about this device (one entry per `agents devices note`).',
+    },
+];
+/** Look up a key spec by CLI dotted name, or throw listing the known keys. */
+export function configKeySpec(name) {
+    const spec = CONFIG_KEYS.find((k) => k.name === name);
+    if (!spec) {
+        throw new Error(`Unknown config key '${name}'. Known keys: ${CONFIG_KEYS.map((k) => k.name).join(', ')}.`);
+    }
+    return spec;
+}
+/** Throw when `value` does not match the key's declared type or validation. */
+function assertValidValue(spec, value) {
+    switch (spec.type) {
+        case 'string':
+            if (typeof value !== 'string' || value.length === 0) {
+                throw new Error(`Config key '${spec.name}' expects a non-empty string, got ${JSON.stringify(value)}.`);
+            }
+            break;
+        case 'int':
+            if (!Number.isInteger(value)) {
+                throw new Error(`Config key '${spec.name}' expects an integer, got ${JSON.stringify(value)}.`);
+            }
+            break;
+        case 'bool':
+            if (typeof value !== 'boolean') {
+                throw new Error(`Config key '${spec.name}' expects a boolean, got ${JSON.stringify(value)}.`);
+            }
+            break;
+        case 'string-list':
+            if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+                throw new Error(`Config key '${spec.name}' expects a list of strings, got ${JSON.stringify(value)}.`);
+            }
+            break;
+    }
+    const err = spec.validate?.(value);
+    if (err)
+        throw new Error(`Invalid value for '${spec.name}': ${err}`);
+}
+// ─── Sibling-device doc access ────────────────────────────────────────────────
+/** Path to any device's doc (self or a peer) under the synced devices/ tree. */
+function deviceDocPath(device) {
+    return path.join(getUserAgentsDir(), 'devices', device, 'agents.yaml');
+}
+/**
+ * Read a device doc directly. Returns null when the file does not exist. A
+ * malformed file is a hard error — silently returning null would let the next
+ * write wipe the device's pins/default (same contract as the device registry).
+ * A valid-but-non-map document (a bare string, a list) is the same kind of
+ * corruption: reject it here instead of failing later with a TypeError.
+ */
+function readDeviceDoc(device) {
+    const p = deviceDocPath(device);
+    let raw;
+    try {
+        raw = fs.readFileSync(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const corrupted = (detail) => new Error(`Device config corrupted at ${p}: ${detail}. Inspect and restore from backup.`);
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch (err) {
+        throw corrupted(err?.message ?? String(err));
+    }
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw corrupted(`expected a YAML map, got ${Array.isArray(parsed) ? 'a list' : JSON.stringify(parsed)}`);
+    }
+    return parsed;
+}
+/** Write a device doc in place (atomic). Only ever holds device-local fields. */
+function writeDeviceDoc(device, doc) {
+    const p = deviceDocPath(device);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const body = Object.keys(doc).length > 0 ? doc : { agents: {} };
+    atomicWriteFileSync(p, META_HEADER + yaml.stringify(body));
+}
+// ─── Reads ────────────────────────────────────────────────────────────────────
+function entryFromMeta(spec, meta) {
+    if (spec.field === 'defaultBrowserProfile') {
+        const value = meta.defaultBrowserProfile;
+        return { spec, value, layer: value !== undefined ? 'device' : undefined };
+    }
+    if (spec.scope === 'user') {
+        const value = meta.config?.[spec.yamlKey];
+        return { spec, value, layer: value !== undefined ? 'user' : undefined };
+    }
+    const value = meta.deviceConfig?.[spec.yamlKey];
+    return { spec, value, layer: value !== undefined ? 'device' : undefined };
+}
+/** True when `device` names this machine (case-insensitive, mirroring
+ * `isLocalDevice` in teams/scheduler.ts) — `configure ZION` on host zion must
+ * take the self path (readMeta/updateMeta funnel), not the peer-doc path. */
+function isSelfDevice(device) {
+    return device.toLowerCase() === machineId();
+}
+/** Get one config key's value and the layer that set it. */
+export function getConfigValue(name, opts) {
+    const spec = configKeySpec(name);
+    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
+        const doc = readDeviceDoc(opts.device) ?? {};
+        return entryFromMeta(spec, { deviceConfig: doc.config, defaultBrowserProfile: doc.defaultBrowserProfile });
+    }
+    return entryFromMeta(spec, readMeta());
+}
+/** List every known key with its value and the layer that set it. */
+export function listConfig(opts) {
+    return CONFIG_KEYS.map((spec) => getConfigValue(spec.name, opts));
+}
+// ─── Writes ───────────────────────────────────────────────────────────────────
+function setInMeta(spec, value) {
+    updateMeta((m) => {
+        if (spec.field === 'defaultBrowserProfile') {
+            return { ...m, defaultBrowserProfile: value };
+        }
+        if (spec.scope === 'user') {
+            return { ...m, config: { ...m.config, [spec.yamlKey]: value } };
+        }
+        return { ...m, deviceConfig: { ...m.deviceConfig, [spec.yamlKey]: value } };
+    });
+}
+function unsetInMeta(spec) {
+    updateMeta((m) => {
+        if (spec.field === 'defaultBrowserProfile') {
+            const { defaultBrowserProfile, ...rest } = m;
+            void defaultBrowserProfile;
+            return rest;
+        }
+        const block = spec.scope === 'user' ? m.config : m.deviceConfig;
+        if (!block || !(spec.yamlKey in block))
+            return m;
+        const next = { ...block };
+        delete next[spec.yamlKey];
+        const cleaned = Object.keys(next).length > 0 ? next : undefined;
+        return spec.scope === 'user' ? { ...m, config: cleaned } : { ...m, deviceConfig: cleaned };
+    });
+}
+function setInDeviceDoc(device, spec, value) {
+    const doc = readDeviceDoc(device) ?? {};
+    if (spec.field === 'defaultBrowserProfile') {
+        doc.defaultBrowserProfile = value;
+    }
+    else {
+        doc.config = { ...doc.config, [spec.yamlKey]: value };
+    }
+    writeDeviceDoc(device, doc);
+}
+function unsetInDeviceDoc(device, spec) {
+    const doc = readDeviceDoc(device);
+    if (!doc)
+        return; // nothing stored — unset is a no-op
+    if (spec.field === 'defaultBrowserProfile') {
+        delete doc.defaultBrowserProfile;
+    }
+    else if (doc.config && spec.yamlKey in doc.config) {
+        delete doc.config[spec.yamlKey];
+        if (Object.keys(doc.config).length === 0)
+            delete doc.config;
+    }
+    else {
+        return; // key not present — no write needed
+    }
+    writeDeviceDoc(device, doc);
+}
+/** Set a config key (validated). Device-scope keys target this machine unless `opts.device` names a peer. */
+export function setConfigValue(name, value, opts) {
+    const spec = configKeySpec(name);
+    assertValidValue(spec, value);
+    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
+        setInDeviceDoc(opts.device, spec, value);
+        return;
+    }
+    setInMeta(spec, value);
+}
+/** Unset a config key — restores default behavior. No-op when already unset. */
+export function unsetConfigValue(name, opts) {
+    const spec = configKeySpec(name);
+    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
+        unsetInDeviceDoc(opts.device, spec);
+        return;
+    }
+    unsetInMeta(spec);
+}
+// ─── Consumers' helpers ───────────────────────────────────────────────────────
+/** True unless this machine's device doc disables the routines scheduler. */
+export function isSchedulerEnabled() {
+    return getConfigValue('scheduler.enabled').value !== false;
+}
+/**
+ * Throw when the routines scheduler is disabled on this machine, naming the
+ * setting and the fix. The single message every scheduler-start surface
+ * (auto-start on `routines add`, manual `routines start`, the daemon's own
+ * scheduler init) refuses with.
+ */
+export function assertSchedulerEnabled() {
+    if (isSchedulerEnabled())
+        return;
+    throw new Error(`The routines scheduler is disabled on this device (scheduler.enabled=false in ~/.agents/devices/${machineId()}/agents.yaml). ` +
+        `Re-enable with: agents devices configure ${machineId()} --scheduler on`);
+}
+/**
+ * Read the `agents.max-concurrent` cap for each named device from its synced
+ * device doc (no SSH). Devices without a cap are omitted — uncapped is the
+ * default. Used as an input to host ranking (teams placement, Factory
+ * auto-launch), never as a remote probe.
+ */
+export function readMaxConcurrentCaps(devices) {
+    const caps = {};
+    for (const device of devices) {
+        const value = getConfigValue('agents.max-concurrent', { device }).value;
+        if (typeof value === 'number')
+            caps[device] = value;
+    }
+    return caps;
+}

package/dist/lib/event-provenance.d.ts

@@ -0,0 +1,19 @@
+import { type ActorKind } from './actor.js';
+export interface EventProvenance {
+    osUser: string;
+    transport: 'local' | 'ssh';
+    sshClientIp?: string;
+    actor: string;
+    kind: ActorKind;
+    machineId: string;
+    sessionId?: string;
+    agent?: string;
+    launchId?: string;
+    parentSessionId?: string;
+}
+/**
+ * Stamp the shared identity floor used by both operational and activity events.
+ * Explicit event payload fields may override these defaults at the call site.
+ */
+export declare function stampProvenance(env?: NodeJS.ProcessEnv): EventProvenance;
+export declare function resetEventProvenanceForTest(): void;

package/dist/lib/event-provenance.js

@@ -0,0 +1,48 @@
+import * as os from 'os';
+import { resolveActor } from './actor.js';
+import { machineId } from './machine-id.js';
+import { parseSshConnection } from './session/provenance.js';
+let cachedOrigin;
+let cachedDeviceId;
+/**
+ * Stamp the shared identity floor used by both operational and activity events.
+ * Explicit event payload fields may override these defaults at the call site.
+ */
+export function stampProvenance(env = process.env) {
+    if (!cachedOrigin) {
+        let osUser = 'unknown';
+        try {
+            osUser = os.userInfo().username;
+        }
+        catch {
+            // A uid without a passwd entry has no attributable OS user.
+        }
+        const ssh = env.SSH_CONNECTION ? parseSshConnection(env.SSH_CONNECTION) : undefined;
+        const actor = resolveActor();
+        cachedOrigin = {
+            osUser,
+            transport: ssh ? 'ssh' : 'local',
+            ...(ssh ? { sshClientIp: ssh.clientIp } : {}),
+            actor: actor.id,
+            kind: actor.kind,
+        };
+    }
+    const provenance = {
+        ...cachedOrigin,
+        machineId: (cachedDeviceId ??= machineId()),
+    };
+    const sessionId = env.AGENT_SESSION_ID || env.AGENTS_SESSION_ID;
+    if (sessionId)
+        provenance.sessionId = sessionId;
+    if (env.AGENTS_AGENT_NAME)
+        provenance.agent = env.AGENTS_AGENT_NAME;
+    if (env.AGENT_LAUNCH_ID)
+        provenance.launchId = env.AGENT_LAUNCH_ID;
+    if (env.AGENTS_PARENT_SESSION_ID)
+        provenance.parentSessionId = env.AGENTS_PARENT_SESSION_ID;
+    return provenance;
+}
+export function resetEventProvenanceForTest() {
+    cachedOrigin = undefined;
+    cachedDeviceId = undefined;
+}