@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/profiles.js

@@ -223,11 +223,75 @@ export function profileFromPreset(profileName, preset, version) {
             envVar: preset.authEnvVar,
             keychainItem: keychainItemName(preset.provider),
         },
+        authOptional: preset.authOptional,
         description: preset.description,
         preset: preset.name,
         provider: preset.provider,
     };
 }
+/**
+ * Env var each host CLI reads to override its model. Mirror of the read-side
+ * `MODEL_ENV_KEYS` above, keyed by host so a one-shot `--host <agent> --model
+ * <id>` writes the model onto the var that host actually honors.
+ */
+const MODEL_ENV_KEY_BY_HOST = {
+    claude: 'ANTHROPIC_MODEL',
+    opencode: 'OPENCODE_MODEL',
+    grok: 'GROK_MODEL',
+    gemini: 'GEMINI_MODEL',
+    codex: 'OPENAI_MODEL',
+};
+/** Base-URL env var per host, for the OpenAI/Anthropic-compatible hosts where it applies. */
+const BASE_URL_ENV_KEY_BY_HOST = {
+    claude: 'ANTHROPIC_BASE_URL',
+    codex: 'OPENAI_BASE_URL',
+};
+/** Return the model-override env var for a host (known hosts mapped; else `<HOST>_MODEL`). */
+export function modelEnvKeyForHost(host) {
+    return MODEL_ENV_KEY_BY_HOST[host] ?? `${host.toUpperCase()}_MODEL`;
+}
+/** Return the base-URL env var for a host, or null when the host has no known override var. */
+export function baseUrlEnvKeyForHost(host) {
+    return BASE_URL_ENV_KEY_BY_HOST[host] ?? null;
+}
+/** Env var each host reads its auth token from, for custom-endpoint (`--auth-provider`) harnesses. */
+const AUTH_ENV_KEY_BY_HOST = {
+    claude: 'ANTHROPIC_AUTH_TOKEN',
+    codex: 'OPENAI_API_KEY',
+    gemini: 'GEMINI_API_KEY',
+    grok: 'XAI_API_KEY',
+    opencode: 'OPENCODE_API_KEY',
+};
+/** Return the auth-token env var for a host, or null when unknown. */
+export function authEnvKeyForHost(host) {
+    return AUTH_ENV_KEY_BY_HOST[host] ?? null;
+}
+/**
+ * Build a custom-harness profile from a host CLI + model in one shot, without a
+ * preset. The model lands on the host's model env var ({@link modelEnvKeyForHost});
+ * auth is attached only when both `provider` and `authEnvVar` are supplied
+ * (hosts that manage their own login — e.g. opencode — need neither).
+ */
+export function profileFromHostModel(name, host, model, opts = {}) {
+    const env = { [modelEnvKeyForHost(host)]: model };
+    if (opts.baseUrl) {
+        const key = baseUrlEnvKeyForHost(host);
+        if (key)
+            env[key] = opts.baseUrl;
+    }
+    const profile = {
+        name,
+        host: { agent: host, version: opts.version },
+        env,
+        description: opts.description ?? `Custom harness: ${host} + ${model}`,
+        provider: opts.provider ?? host,
+    };
+    if (opts.provider && opts.authEnvVar) {
+        profile.auth = { envVar: opts.authEnvVar, keychainItem: keychainItemName(opts.provider) };
+        profile.authOptional = false;
+    }
+    return profile;
+}
 /**
  * Resolve a profile into the env block that should be injected into the
  * spawned agent process. Reads the token from keychain at exec time so the
@@ -236,6 +300,12 @@ export function profileFromPreset(profileName, preset, version) {
 export function resolveProfileEnv(profile) {
     const env = { ...profile.env };
     if (profile.auth) {
+        // Optional auth (host manages its own login) with no stored token: inject
+        // nothing and let the host use its own credentials. Only required auth
+        // hard-fails on a missing keychain item.
+        if (profile.authOptional && !hasKeychainToken(profile.auth.keychainItem)) {
+            return env;
+        }
         const token = getKeychainToken(profile.auth.keychainItem);
         env[profile.auth.envVar] = token;
     }

package/dist/lib/pty-server.d.ts

@@ -8,16 +8,8 @@
  *
  * Protocol: newline-delimited JSON over ~/.agents/.system/pty.sock
  */
-/**
- * Capture a stable identifier for a process at the moment it was started.
- * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
- * still occupies the PID we observed at spawn time.
- *
- * Linux:  field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
- * macOS:  output of `ps -o lstart= -p <pid>` (start time in human format).
- * Returns null on any error so callers can skip the guard rather than crash.
- */
-export declare function captureProcessStartTime(pid: number): string | null;
+import { captureProcessStartTime } from './platform/index.js';
+export { captureProcessStartTime };
 /**
  * Wrap a user command so a `__SENTINEL__:<exit>` line is printed after it
  * finishes — that line drives completion detection in the exec/read flow.

package/dist/lib/pty-server.js

@@ -12,46 +12,12 @@ import * as net from 'net';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
-import { execFileSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { getPtyDir as getPtyDirRoot } from './state.js';
-import { isAlive } from './platform/index.js';
-/**
- * Capture a stable identifier for a process at the moment it was started.
- * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
- * still occupies the PID we observed at spawn time.
- *
- * Linux:  field 22 of /proc/<pid>/stat (starttime in clock ticks since boot).
- * macOS:  output of `ps -o lstart= -p <pid>` (start time in human format).
- * Returns null on any error so callers can skip the guard rather than crash.
- */
-export function captureProcessStartTime(pid) {
-    if (!pid || pid <= 0)
-        return null;
-    try {
-        if (process.platform === 'linux') {
-            const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf-8');
-            // The comm field (#2) is wrapped in parens and may contain spaces, so
-            // split off everything after the last `)` to get a clean field list.
-            const lastParen = stat.lastIndexOf(')');
-            if (lastParen < 0)
-                return null;
-            const tail = stat.slice(lastParen + 2);
-            const fields = tail.split(' ');
-            // After comm we are at field 3; starttime is field 22, so index 19 here.
-            return fields[19] || null;
-        }
-        const out = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], {
-            encoding: 'utf-8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        });
-        const trimmed = out.trim();
-        return trimmed.length > 0 ? trimmed : null;
-    }
-    catch {
-        return null;
-    }
-}
+import { isAlive, captureProcessStartTime } from './platform/index.js';
+// Re-exported for the existing importers of this module; the implementation is
+// in platform/process.ts, shared with teams/agents.ts so the two cannot drift.
+export { captureProcessStartTime };
 // --- Constants ---
 const IS_WINDOWS = process.platform === 'win32';
 const SENTINEL = '__AGENTS_PTY_DONE__';

package/dist/lib/registry.d.ts

@@ -17,7 +17,7 @@ export declare function getEnabledRegistries(type: RegistryType): Array<{
 }>;
 /** Add or update a registry configuration in agents.yaml. */
 export declare function setRegistry(type: RegistryType, name: string, config: Partial<RegistryConfig>): void;
-/** Remove a user-configured registry. Returns false if it did not exist. */
+/** Remove a user-configured or seeded registry. Returns false if it did not exist. */
 export declare function removeRegistry(type: RegistryType, name: string): boolean;
 /** Search MCP registries for servers matching a query string. */
 export declare function searchMcpRegistries(query: string, options?: {

package/dist/lib/registry.js

@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { createHash } from 'crypto';
-import { DEFAULT_REGISTRIES } from './types.js';
+import { DEFAULT_REGISTRIES, SEEDED_REGISTRIES } from './types.js';
 import { readMeta, writeMeta } from './state.js';
 import { discoverSkillsFromRepo } from './skills.js';
 const UNSAFE_PACKAGE_SPEC_CHARS = /[;&|`$\s\x00-\x1f\x7f]/;
@@ -26,13 +26,38 @@ export function validatedPyPISpec(spec) {
     }
     return spec;
 }
+/**
+ * Seeded presets offered for `type`, minus any the user has removed.
+ *
+ * These are resolved here rather than written into agents.yaml. Seeding used to
+ * happen on the state READ path and persisted the entry — but agents.yaml is
+ * git-tracked in the user's DotAgents repo, so that write left the working tree
+ * dirty and every `agents repo pull` aborted with "Working tree has uncommitted
+ * changes", naming neither the file nor the cause. Since every `agents`
+ * invocation reads state, the dirt returned the instant it was cleared, and the
+ * loop could not be escaped through the CLI at all (RUSH-1925).
+ *
+ * `seededPresets` is the removal tombstone: a key listed there means the user
+ * removed that preset, so it is not offered again. Users who were seeded under
+ * the old behaviour have the key listed *and* the entry in their own
+ * `registries:` block, which still wins below — so nothing disappears for them.
+ */
+function offeredSeeds(type, meta) {
+    const removed = new Set(meta.seededPresets || []);
+    const offered = {};
+    for (const [name, config] of Object.entries(SEEDED_REGISTRIES[type] || {})) {
+        if (!removed.has(`${type}.${name}`))
+            offered[name] = { ...config };
+    }
+    return offered;
+}
 /** Get all registries of a given type, merging defaults with user overrides. */
 export function getRegistries(type) {
     const meta = readMeta();
     const defaultRegs = DEFAULT_REGISTRIES[type] || {};
     const userRegs = meta.registries?.[type] || {};
     // Merge defaults with user config (user overrides defaults)
-    return { ...defaultRegs, ...userRegs };
+    return { ...defaultRegs, ...offeredSeeds(type, meta), ...userRegs };
 }
 /** Get only the enabled registries of a given type. */
 export function getEnabledRegistries(type) {
@@ -50,19 +75,34 @@ export function setRegistry(type, name, config) {
     if (!meta.registries[type]) {
         meta.registries[type] = {};
     }
-    const existing = meta.registries[type][name] || DEFAULT_REGISTRIES[type]?.[name];
+    // Seeded presets are resolved in memory and never materialized in agents.yaml
+    // (see offeredSeeds), so a partial update — `registry disable`, `enable`, or
+    // `config --api-key` — has nothing stored to merge with. Without the
+    // SEEDED_REGISTRIES fallback it would persist only the changed fields and drop
+    // `url`, and because userRegs wins over the in-memory seed in getRegistries the
+    // preset would stay broken even after re-enabling.
+    const existing = meta.registries[type][name]
+        || DEFAULT_REGISTRIES[type]?.[name]
+        || SEEDED_REGISTRIES[type]?.[name];
     meta.registries[type][name] = { ...existing, ...config };
     writeMeta(meta);
 }
-/** Remove a user-configured registry. Returns false if it did not exist. */
+/** Remove a user-configured or seeded registry. Returns false if it did not exist. */
 export function removeRegistry(type, name) {
     const meta = readMeta();
-    if (meta.registries?.[type]?.[name]) {
+    const inUserConfig = !!meta.registries?.[type]?.[name];
+    // A seeded preset has no entry in agents.yaml until the user edits it, so
+    // removal is recorded as a tombstone in seededPresets instead of a deletion.
+    const isOfferedSeed = !!offeredSeeds(type, meta)[name];
+    if (!inUserConfig && !isOfferedSeed)
+        return false;
+    if (inUserConfig)
         delete meta.registries[type][name];
-        writeMeta(meta);
-        return true;
+    if (SEEDED_REGISTRIES[type]?.[name]) {
+        meta.seededPresets = [...new Set([...(meta.seededPresets || []), `${type}.${name}`])];
     }
-    return false;
+    writeMeta(meta);
+    return true;
 }
 /**
  * Cap every registry network call. Without this a slow or unreachable registry

package/dist/lib/rotate.d.ts

@@ -126,6 +126,24 @@ export declare function pickBalancedCandidate(candidates: RotateCandidate[]): Ro
  */
 export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null): RotateResult | null;
 export declare function collectRunCandidates(agent: AgentId): Promise<RotateCandidate[]>;
+/**
+ * Resolve an account identity to the installed version slot that holds it, over
+ * an already-collected candidate list. Pure — no I/O — so it is unit-tested
+ * directly. Matches, case-insensitively, against a candidate's login `email`
+ * (the usual form) or its `accountKey`, and only ever returns a signed-in slot.
+ * Returns null when nothing matches, so the caller can fall back and warn.
+ */
+export declare function matchAccountVersion(candidates: RotateCandidate[], account: string): string | null;
+/**
+ * Resolve a routine's `account:` pin (login email or account key) to the
+ * installed version currently holding that account. Thin I/O wrapper over
+ * {@link collectRunCandidates} + {@link matchAccountVersion}; returns null when
+ * no signed-in version matches. Pinning a routine to a distinct account is the
+ * durable cure for the shared-single-use-refresh-token revocation storm
+ * (RUSH-1957): the pinned run never rotates and never lands on another
+ * routine's credential.
+ */
+export declare function resolveAccountVersion(agent: AgentId, account: string): Promise<string | null>;
 /**
  * Pick a healthy version for `agent` using weighted random by remaining
  * capacity. See `pickBalancedCandidate` for algorithm details.

package/dist/lib/rotate.js

@@ -316,6 +316,34 @@ export async function collectRunCandidates(agent) {
         };
     });
 }
+/**
+ * Resolve an account identity to the installed version slot that holds it, over
+ * an already-collected candidate list. Pure — no I/O — so it is unit-tested
+ * directly. Matches, case-insensitively, against a candidate's login `email`
+ * (the usual form) or its `accountKey`, and only ever returns a signed-in slot.
+ * Returns null when nothing matches, so the caller can fall back and warn.
+ */
+export function matchAccountVersion(candidates, account) {
+    const needle = account.trim().toLowerCase();
+    if (!needle)
+        return null;
+    const match = candidates.find((c) => c.signedIn &&
+        (c.email?.toLowerCase() === needle || c.accountKey?.toLowerCase() === needle));
+    return match?.version ?? null;
+}
+/**
+ * Resolve a routine's `account:` pin (login email or account key) to the
+ * installed version currently holding that account. Thin I/O wrapper over
+ * {@link collectRunCandidates} + {@link matchAccountVersion}; returns null when
+ * no signed-in version matches. Pinning a routine to a distinct account is the
+ * durable cure for the shared-single-use-refresh-token revocation storm
+ * (RUSH-1957): the pinned run never rotates and never lands on another
+ * routine's credential.
+ */
+export async function resolveAccountVersion(agent, account) {
+    const candidates = await collectRunCandidates(agent);
+    return matchAccountVersion(candidates, account);
+}
 /**
  * Pick a healthy version for `agent` using weighted random by remaining
  * capacity. See `pickBalancedCandidate` for algorithm details.

package/dist/lib/routine-notify.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Routine lifecycle desktop notifications (RUSH-2030).
+ *
+ * The daemon fires a branded notification when a scheduled routine starts and
+ * when it finishes (success or failure), routed through the MenubarHelper
+ * companion (notify-desktop.ts) so it carries the agents-cli mark.
+ *
+ * Anti-spam threshold (Acceptance Criteria #4 — "define a sensible threshold so
+ * users are not spammed"):
+ *   - Agent / workflow routines: notify on BOTH start and finish. These are the
+ *     runs whose output a user actually wants surfaced.
+ *   - Command routines (deterministic housekeeping — version checks, `git pull`,
+ *     notify shims that can fire every minute): notify only on FAILURE. A green
+ *     housekeeping run is noise; a broken one is worth a ping. No start ping.
+ *   - "Notable output" is folded into the single finish notification rather than
+ *     sent as a third message: on failure the error reason, on success the first
+ *     line of the run's report (the user-facing result) when the routine produced
+ *     one. One start + one finish per run — never a stream.
+ *
+ * The pure builders (`routineStartNotification` / `routineFinishNotification`)
+ * return `null` when the threshold says "don't notify", and are unit-tested; the
+ * `notifyRoutine*` wrappers do the filesystem read + dispatch for the daemon.
+ */
+import type { JobConfig, RunMeta } from './routines.js';
+import { type DesktopNotification } from './menubar/notify-desktop.js';
+type RoutineKind = 'agent' | 'workflow' | 'command';
+/** Which flavor of routine a config/meta describes — drives the notify threshold. */
+export declare function routineKind(r: Pick<JobConfig, 'agent' | 'workflow' | 'command'>): RoutineKind;
+/** "1m 20s" / "45s" / "2h 3m" from a millisecond duration, or null when unknown. */
+export declare function formatDuration(ms: number | undefined): string | null;
+/**
+ * First non-empty line of a run report, trimmed to a notification-sized snippet.
+ * This is the "notable output" surfaced on a successful finish — the routine's
+ * own user-facing result. Returns null for an empty/whitespace report so the
+ * caller falls back to a plain "Completed" body.
+ */
+export declare function notableSnippet(report: string | null | undefined, maxLen?: number): string | null;
+/**
+ * Notification for a routine START, or null when the threshold suppresses it
+ * (command-mode housekeeping). Clicking opens the runs folder
+ * (~/.agents/.history/runs).
+ */
+export declare function routineStartNotification(config: Pick<JobConfig, 'name' | 'agent' | 'workflow' | 'command'>): DesktopNotification | null;
+/**
+ * Notification for a routine that failed to even START — `executeJobDetached`
+ * threw before the child was spawned, so no run record and no finish will ever
+ * exist. The daemon fires the START notification unconditionally, so this closes
+ * the "exactly one start + one finish" invariant: the orphaned start gets its
+ * matching failure banner (RUSH-2030). Unlike a green finish this is never
+ * suppressed — a broken start is worth a ping for every routine kind, including
+ * command housekeeping. Clicking opens the runs folder (~/.agents/.history/runs)
+ * since there is no run report to open.
+ */
+export declare function routineStartFailedNotification(config: Pick<JobConfig, 'name' | 'agent' | 'workflow' | 'command'>, error: string): DesktopNotification;
+/**
+ * Notification for a routine FINISH, or null when the threshold suppresses it
+ * (a successful command-mode housekeeping run). Success carries the report's
+ * first line when present (the notable output); failure carries the reason.
+ * Clicking opens the run report/log when one is available, else the runs folder
+ * (~/.agents/.history/runs).
+ */
+export declare function routineFinishNotification(meta: Pick<RunMeta, 'jobName' | 'status' | 'exitCode' | 'errorMessage' | 'duration' | 'agent' | 'workflow' | 'command'>, opts?: {
+    report?: string | null;
+    artifactPath?: string | null;
+}): DesktopNotification | null;
+/** Daemon glue: fire the START notification for a triggered routine. Best-effort. */
+export declare function notifyRoutineStart(config: JobConfig): void;
+/**
+ * Daemon glue: fire the "failed to start" notification when a routine trigger
+ * threw before spawning a child. Pairs with the unconditional START ping so a
+ * pre-spawn failure never leaves an orphaned "Routine started". Best-effort.
+ */
+export declare function notifyRoutineStartFailed(config: JobConfig, error: string): void;
+/** Daemon glue: fire the FINISH notification for a completed run. Best-effort. */
+export declare function notifyRoutineFinish(meta: RunMeta): void;
+export {};

package/dist/lib/routine-notify.js

@@ -0,0 +1,190 @@
+/**
+ * Routine lifecycle desktop notifications (RUSH-2030).
+ *
+ * The daemon fires a branded notification when a scheduled routine starts and
+ * when it finishes (success or failure), routed through the MenubarHelper
+ * companion (notify-desktop.ts) so it carries the agents-cli mark.
+ *
+ * Anti-spam threshold (Acceptance Criteria #4 — "define a sensible threshold so
+ * users are not spammed"):
+ *   - Agent / workflow routines: notify on BOTH start and finish. These are the
+ *     runs whose output a user actually wants surfaced.
+ *   - Command routines (deterministic housekeeping — version checks, `git pull`,
+ *     notify shims that can fire every minute): notify only on FAILURE. A green
+ *     housekeeping run is noise; a broken one is worth a ping. No start ping.
+ *   - "Notable output" is folded into the single finish notification rather than
+ *     sent as a third message: on failure the error reason, on success the first
+ *     line of the run's report (the user-facing result) when the routine produced
+ *     one. One start + one finish per run — never a stream.
+ *
+ * The pure builders (`routineStartNotification` / `routineFinishNotification`)
+ * return `null` when the threshold says "don't notify", and are unit-tested; the
+ * `notifyRoutine*` wrappers do the filesystem read + dispatch for the daemon.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getRunDir } from './routines.js';
+import { notifyDesktop } from './menubar/notify-desktop.js';
+/** Which flavor of routine a config/meta describes — drives the notify threshold. */
+export function routineKind(r) {
+    if (r.command)
+        return 'command';
+    if (r.workflow)
+        return 'workflow';
+    return 'agent';
+}
+/** Human label for the routine body ("agent claude", "workflow deploy", "command"). */
+function routineLabel(r) {
+    if (r.command)
+        return 'command';
+    if (r.workflow)
+        return `workflow ${r.workflow}`;
+    return `agent ${r.agent ?? 'unknown'}`;
+}
+/** "1m 20s" / "45s" / "2h 3m" from a millisecond duration, or null when unknown. */
+export function formatDuration(ms) {
+    if (ms === undefined || !Number.isFinite(ms) || ms < 0)
+        return null;
+    const totalSec = Math.round(ms / 1000);
+    if (totalSec < 60)
+        return `${totalSec}s`;
+    const min = Math.floor(totalSec / 60);
+    const sec = totalSec % 60;
+    if (min < 60)
+        return sec ? `${min}m ${sec}s` : `${min}m`;
+    const hr = Math.floor(min / 60);
+    const remMin = min % 60;
+    return remMin ? `${hr}h ${remMin}m` : `${hr}h`;
+}
+/**
+ * First non-empty line of a run report, trimmed to a notification-sized snippet.
+ * This is the "notable output" surfaced on a successful finish — the routine's
+ * own user-facing result. Returns null for an empty/whitespace report so the
+ * caller falls back to a plain "Completed" body.
+ */
+export function notableSnippet(report, maxLen = 140) {
+    if (!report)
+        return null;
+    const firstLine = report
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (!firstLine)
+        return null;
+    return firstLine.length > maxLen ? `${firstLine.slice(0, maxLen - 1).trimEnd()}…` : firstLine;
+}
+/** Encode a click action that opens a file (report/log) in the default app. */
+function openAction(filePath) {
+    return filePath ? `open:${filePath}` : undefined;
+}
+/**
+ * Notification for a routine START, or null when the threshold suppresses it
+ * (command-mode housekeeping). Clicking opens the runs folder
+ * (~/.agents/.history/runs).
+ */
+export function routineStartNotification(config) {
+    if (routineKind(config) === 'command')
+        return null;
+    return {
+        title: 'Routine started',
+        subtitle: config.name,
+        body: `Running ${routineLabel(config)}`,
+        action: 'routines:list',
+    };
+}
+/**
+ * Notification for a routine that failed to even START — `executeJobDetached`
+ * threw before the child was spawned, so no run record and no finish will ever
+ * exist. The daemon fires the START notification unconditionally, so this closes
+ * the "exactly one start + one finish" invariant: the orphaned start gets its
+ * matching failure banner (RUSH-2030). Unlike a green finish this is never
+ * suppressed — a broken start is worth a ping for every routine kind, including
+ * command housekeeping. Clicking opens the runs folder (~/.agents/.history/runs)
+ * since there is no run report to open.
+ */
+export function routineStartFailedNotification(config, error) {
+    return {
+        title: 'Routine failed',
+        subtitle: config.name,
+        body: `Failed to start: ${error}`,
+        action: 'routines:list',
+    };
+}
+/**
+ * Notification for a routine FINISH, or null when the threshold suppresses it
+ * (a successful command-mode housekeeping run). Success carries the report's
+ * first line when present (the notable output); failure carries the reason.
+ * Clicking opens the run report/log when one is available, else the runs folder
+ * (~/.agents/.history/runs).
+ */
+export function routineFinishNotification(meta, opts = {}) {
+    const kind = routineKind(meta);
+    const ok = meta.status === 'completed';
+    if (kind === 'command' && ok)
+        return null; // green housekeeping is noise
+    const action = openAction(opts.artifactPath) ?? 'routines:list';
+    if (ok) {
+        const snippet = notableSnippet(opts.report);
+        const dur = formatDuration(meta.duration);
+        return {
+            title: 'Routine finished',
+            subtitle: meta.jobName,
+            body: snippet ?? (dur ? `Completed in ${dur}` : 'Completed'),
+            action,
+        };
+    }
+    // failed | timeout
+    const reason = meta.status === 'timeout'
+        ? 'Timed out'
+        : meta.errorMessage
+            ? meta.errorMessage
+            : `Exited with code ${meta.exitCode ?? '?'}`;
+    return {
+        title: 'Routine failed',
+        subtitle: meta.jobName,
+        body: reason,
+        action,
+    };
+}
+/** Read a finished run's report text + the best artifact to open on click. */
+function loadRunArtifacts(meta) {
+    try {
+        const runDir = getRunDir(meta.jobName, meta.runId);
+        const reportPath = path.join(runDir, 'report.md');
+        const stdoutPath = path.join(runDir, 'stdout.log');
+        let report = null;
+        let artifactPath = null;
+        if (fs.existsSync(reportPath)) {
+            report = fs.readFileSync(reportPath, 'utf-8');
+            artifactPath = reportPath;
+        }
+        else if (fs.existsSync(stdoutPath)) {
+            artifactPath = stdoutPath;
+        }
+        return { report, artifactPath };
+    }
+    catch {
+        return { report: null, artifactPath: null };
+    }
+}
+/** Daemon glue: fire the START notification for a triggered routine. Best-effort. */
+export function notifyRoutineStart(config) {
+    const n = routineStartNotification(config);
+    if (n)
+        notifyDesktop(n);
+}
+/**
+ * Daemon glue: fire the "failed to start" notification when a routine trigger
+ * threw before spawning a child. Pairs with the unconditional START ping so a
+ * pre-spawn failure never leaves an orphaned "Routine started". Best-effort.
+ */
+export function notifyRoutineStartFailed(config, error) {
+    notifyDesktop(routineStartFailedNotification(config, error));
+}
+/** Daemon glue: fire the FINISH notification for a completed run. Best-effort. */
+export function notifyRoutineFinish(meta) {
+    const { report, artifactPath } = loadRunArtifacts(meta);
+    const n = routineFinishNotification(meta, { report, artifactPath });
+    if (n)
+        notifyDesktop(n);
+}

package/dist/lib/routines-placement.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Runtime placement resolution for routines: local / host / fleet / cloud.
+ *
+ * The scheduler only decides *whether* this machine may fire the job
+ * (`devices` + `jobRunsOnThisDevice`). This module decides *where the job
+ * body runs* once it has been fired, using `hostStrategy`.
+ *
+ * Fleet semantics (RUSH-2035 / RUSH-1980): pick exactly one online device per
+ * fire. Cross-device double-fire is prevented by requiring a `devices` firing
+ * pin for fleet/host/cloud strategies (applied at add/sync time).
+ */
+import type { JobConfig } from './routines.js';
+export type PlacementTarget = {
+    mode: 'local';
+} | {
+    mode: 'host';
+    host: string;
+} | {
+    mode: 'cloud';
+};
+/**
+ * Pick one online fleet device for `hostStrategy: fleet`.
+ *
+ * Preference order:
+ * 1. This machine, if online and eligible (avoids needless SSH)
+ * 2. First eligible online device by name (stable / deterministic)
+ *
+ * `config.devices` is the *firing* allowlist only (which daemon may fire the
+ * job). It is intentionally NOT used as an execution pool filter — otherwise
+ * the double-fire pin (`devices: [self]`) would collapse fleet placement to
+ * always-local. Control / offline / no-address devices are never chosen.
+ */
+export declare function pickFleetDevice(_config?: Pick<JobConfig, 'devices'>): string | null;
+/**
+ * Resolve where a fired job's body should execute.
+ * Throws a human-readable Error when placement cannot be satisfied.
+ */
+export declare function resolvePlacementTarget(config: JobConfig): PlacementTarget;