@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/lib/project-probe.js

@@ -0,0 +1,160 @@
+/**
+ * Project workspace probing — the drift signal behind `projects status --fleet`.
+ *
+ * Projects are natively multi-device: the same definition (home-relative paths)
+ * re-roots on every fleet machine, and the question is whether the project's
+ * repos are PRESENT on each box, on which branch, how far ahead/behind their
+ * upstream, and whether they carry uncommitted changes. This module is the pure
+ * local half: given a set of home-relative paths it probes each one with a
+ * handful of read-only git calls. Drift is measured against the LAST-FETCHED
+ * upstream (`@{upstream}`) — deliberately no `git fetch`, so a probe is fast
+ * and offline-safe. The fleet half (`--fleet`) just runs this probe on every
+ * peer via the canonical `remote-agents-json` SSH fan-out.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import chalk from 'chalk';
+import { expandLocalHome, toHomeRelative } from './project-root.js';
+/** Per-call git budget. A read-only git call taking >3s is wedged by any
+ * definition (NFS stall, index lock) — and the fleet fan-out SIGKILLs the SSH
+ * hop at 12s, so a probe must fit inside that budget to avoid a slow peer
+ * being misreported as unreachable: 3s × 5 calls leaves headroom even when
+ * one repo is genuinely stuck. */
+const GIT_TIMEOUT_MS = 3_000;
+/** One read-only git call against `absPath`; undefined on any failure. */
+function git(absPath, args) {
+    try {
+        return execFileSync('git', ['-C', absPath, ...args], {
+            encoding: 'utf8',
+            timeout: GIT_TIMEOUT_MS,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Probe one workspace repo. A missing path yields `{present: false}` and no
+ * git call is made. On a present repo every signal is best-effort: whatever
+ * succeeded is reported, and a repo whose `.git` exists yet every git call
+ * failed surfaces as present-with-error rather than silently clean.
+ */
+export function probeRepoWorkspace(absPath) {
+    const status = { path: toHomeRelative(absPath), present: false };
+    if (!fs.existsSync(path.join(absPath, '.git')))
+        return status;
+    status.present = true;
+    const branch = git(absPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
+    const upstream = git(absPath, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']);
+    // `--left-right --count A...B` prints "<left>\t<right>" — left is
+    // upstream-only (we are BEHIND by that much), right is HEAD-only (AHEAD).
+    const counts = upstream !== undefined
+        ? git(absPath, ['rev-list', '--left-right', '--count', '@{upstream}...HEAD'])
+        : undefined;
+    const dirtyOut = git(absPath, ['status', '--porcelain']);
+    const lastCommit = git(absPath, ['log', '-1', '--format=%cI']);
+    if (branch === undefined && dirtyOut === undefined && lastCommit === undefined) {
+        status.error = '.git exists but git could not read this repo';
+        return status;
+    }
+    if (branch !== undefined)
+        status.branch = branch;
+    if (upstream !== undefined)
+        status.upstream = upstream;
+    if (counts !== undefined) {
+        const [behind, ahead] = counts.split(/\s+/).map(Number);
+        if (Number.isFinite(behind) && Number.isFinite(ahead)) {
+            status.behind = behind;
+            status.ahead = ahead;
+        }
+    }
+    if (dirtyOut !== undefined)
+        status.dirty = dirtyOut === '' ? 0 : dirtyOut.split('\n').length;
+    if (lastCommit !== undefined)
+        status.lastCommit = lastCommit;
+    return status;
+}
+/** Probe each home-relative path (expanded against the local home), in order. */
+export function probeProjectWorkspaces(paths) {
+    return paths.map((p) => probeRepoWorkspace(expandLocalHome(p)));
+}
+/**
+ * The home-relative paths to probe for a project definition: its `root` plus
+ * each `repos[].path` (the opt-in for additional repos), deduped. Every target
+ * is normalized through the same `toHomeRelative(expandLocalHome(...))` the
+ * probe echoes, so a hand-edited def (absolute path under home, trailing
+ * slash) matches its probe rows exactly — `writeProjectDef` normalizes on
+ * write, but defs are hand-editable YAML and never silently drop a row.
+ */
+export function workspaceTargetsForDef(def) {
+    const targets = [def.root, ...(def.repos ?? []).map((r) => r.path)]
+        .filter((p) => typeof p === 'string' && p.length > 0)
+        .map((p) => toHomeRelative(expandLocalHome(p)));
+    return [...new Set(targets)];
+}
+/**
+ * Parse a peer's `projects probe --json` stdout, tagging each row with the
+ * machine that answered. Defensive against version skew / partial output, the
+ * same boundary contract as `parseRemoteActive`: non-JSON or a non-array
+ * yields `[]`, and rows without a `path`/`present` core are dropped.
+ */
+export function parseRemoteProbe(stdout, machine) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    return parsed.flatMap((x) => {
+        if (x && typeof x === 'object' && !Array.isArray(x)) {
+            const o = x;
+            if (typeof o.path === 'string' && typeof o.present === 'boolean') {
+                return [{ ...o, host: machine }];
+            }
+        }
+        return [];
+    });
+}
+/**
+ * One workspace's compact state: `✓ clean · main`, `⚠ 12 dirty · ↑3 ↓1 ·
+ * feature/x`, `✗ missing`, or `⚠ error: …`. Pure — chalk styling only.
+ */
+export function formatWorkspaceLine(s) {
+    if (!s.present)
+        return chalk.red('✗ missing');
+    if (s.error)
+        return chalk.yellow(`⚠ error: ${s.error}`);
+    const parts = [];
+    if (s.dirty !== undefined && s.dirty > 0)
+        parts.push(`${s.dirty} dirty`);
+    const drift = [
+        s.ahead !== undefined && s.ahead > 0 ? `↑${s.ahead}` : '',
+        s.behind !== undefined && s.behind > 0 ? `↓${s.behind}` : '',
+    ].filter(Boolean).join(' ');
+    if (drift)
+        parts.push(drift);
+    const head = parts.length > 0 ? chalk.yellow(`⚠ ${parts.join(' · ')}`) : chalk.green('✓ clean');
+    return s.branch ? `${head} ${chalk.dim('·')} ${s.branch}` : head;
+}
+/**
+ * The fleet view of one project's workspaces: one content line per probed
+ * path (host-sorted `host: state` cells joined by ` · `), labelled with the
+ * path when a project probes more than one. Pure — the caller adds the
+ * `fleet` row label.
+ */
+export function formatFleetWorkspaces(statuses) {
+    const paths = [...new Set(statuses.map((s) => s.path))];
+    const multi = paths.length > 1;
+    return paths.map((p) => {
+        const rows = statuses
+            .filter((s) => s.path === p)
+            .sort((a, b) => a.host.localeCompare(b.host));
+        const body = rows.map((r) => `${chalk.cyan(r.host)}: ${formatWorkspaceLine(r)}`).join(chalk.dim('  ·  '));
+        return multi ? `${chalk.dim(`${p} · `)}${body}` : body;
+    });
+}

package/dist/lib/project-resources.d.ts

@@ -5,3 +5,11 @@ export interface ProjectResourceSyncResult {
 }
 export declare function projectAgentRoot(projectRoot: string, agent: AgentId): string;
 export declare function syncProjectResourcesToAgent(agent: AgentId, version: string, projectAgentsDir: string): ProjectResourceSyncResult;
+/**
+ * One human line for the files a project sync left alone because you already
+ * wrote them. This is the normal steady state — every sync of a project whose
+ * `.claude/commands/` you hand-authored hits it — so it is a single grouped
+ * line, not one wrapped warning per file, and it says "yours" rather than the
+ * internal "user-owned". Returns null when nothing was skipped.
+ */
+export declare function formatKeptProjectResources(skipped: string[]): string | null;

package/dist/lib/project-resources.js

@@ -127,9 +127,37 @@ function record(kind, name, relPaths, result, manifestPaths) {
         manifestPaths.add(toPosixRel(rel));
 }
 function skip(dest, projectRoot, result) {
-    const rel = path.relative(projectRoot, dest);
-    result.skipped.push(rel);
-    console.warn(`Skipping project resource target ${rel}: already exists and is user-owned`);
+    result.skipped.push(path.relative(projectRoot, dest));
+}
+/**
+ * One human line for the files a project sync left alone because you already
+ * wrote them. This is the normal steady state — every sync of a project whose
+ * `.claude/commands/` you hand-authored hits it — so it is a single grouped
+ * line, not one wrapped warning per file, and it says "yours" rather than the
+ * internal "user-owned". Returns null when nothing was skipped.
+ */
+export function formatKeptProjectResources(skipped) {
+    if (skipped.length === 0)
+        return null;
+    const rels = [...skipped].sort((a, b) => a.localeCompare(b)).map(toPosixRel);
+    if (rels.length === 1)
+        return `Kept your existing ${rels[0]}`;
+    const byDir = new Map();
+    for (const rel of rels) {
+        const dir = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : '.';
+        const names = byDir.get(dir) ?? [];
+        names.push(rel.slice(rel.lastIndexOf('/') + 1));
+        byDir.set(dir, names);
+    }
+    if (byDir.size === 1) {
+        const [dir, names] = [...byDir.entries()][0];
+        const PREVIEW = 3;
+        const preview = names.slice(0, PREVIEW).join(', ');
+        const more = names.length > PREVIEW ? `, +${names.length - PREVIEW} more` : '';
+        return `Kept ${rels.length} of your own files in ${dir}: ${preview}${more}`;
+    }
+    const dirs = [...byDir.entries()].map(([dir, names]) => `${dir} (${names.length})`).join(', ');
+    return `Kept ${rels.length} of your own files in ${dirs}`;
 }
 function syncProjectCommands(agent, version, projectAgentsDir, agentRoot, result, manifestPaths) {
     const cfg = AGENTS[agent];

package/dist/lib/project-status.d.ts

@@ -13,6 +13,17 @@
  */
 import type { ActiveSession, ActiveStatus } from './session/active.js';
 import { type ProjectDef } from './projects.js';
+/** One live agent on a project — the WHO behind the byStatus count. */
+export interface ProjectMember {
+    /** Harness name (claude / codex / …), from the session's `kind`. */
+    agent: string;
+    /** Lifecycle status (running / idle / …). */
+    status: string;
+    /** Tracker ticket the session is tied to, when any. */
+    ticket?: string;
+    /** Machine the session runs on (provenance host / fleet peer), when known. */
+    host?: string;
+}
 /** One project's live session rollup. */
 export interface ProjectSessionRollup {
     name: string;
@@ -20,6 +31,8 @@ export interface ProjectSessionRollup {
     agents: number;
     /** Count per lifecycle status. */
     byStatus: Partial<Record<ActiveStatus, number>>;
+    /** Which agents are on the project (one per matched session). */
+    members: ProjectMember[];
     /** Summed checklist progress across this project's sessions. */
     plan: {
         done: number;
@@ -46,7 +59,20 @@ export declare function planPct(plan: {
     done: number;
     total: number;
 }): number | undefined;
-/** Harvested signals not on the session list: repo-global merged PRs + local artifacts, in a time window. */
+/** Sort members for the card: running first, then idle, then the rest; agent name asc within a state. */
+export declare function sortProjectMembers(members: ProjectMember[]): ProjectMember[];
+/** Cap for the members line before it collapses to `+N more`. */
+export declare const MEMBERS_LINE_LIMIT = 6;
+/**
+ * The `agents` line under `live`: one cell per DISTINCT member state —
+ * `claude · running · RUSH-2107 @zion` — with identical cells collapsed to a
+ * `×N` count (35 same-harness sessions in one state are one fact, not six
+ * truncated duplicates), capped at {@link MEMBERS_LINE_LIMIT} cells with a
+ * `+N more` tail counting members, not cells. Pure (chalk styling only); the
+ * caller adds the label.
+ */
+export declare function formatProjectMembers(members: ProjectMember[], limit?: number): string;
+/** Harvested signals not on the session list: repo-global merged PRs + releases, local artifacts, in a time window. */
 export interface ProjectRemoteSignals {
     windowDays: number;
     /** PRs merged into the primary repo within the window (via `gh`). */
@@ -55,6 +81,11 @@ export interface ProjectRemoteSignals {
     artifacts: number;
     /** Basename of the most recent artifact, when any. */
     lastArtifact?: string;
+    /** Latest release of the PRIMARY repo (via `gh release list`), when any. */
+    latestRelease?: {
+        tag: string;
+        publishedAt: string;
+    };
 }
 /**
  * Harvest the signals that don't live on the active-session list: recently

package/dist/lib/project-status.js

@@ -13,11 +13,21 @@
  */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
+import chalk from 'chalk';
 import { projectNameForCwd } from './projects.js';
 import { readRecentActivity } from './activity.js';
 const execFileAsync = promisify(execFile);
 function blank(name) {
-    return { name, agents: 0, byStatus: {}, plan: { done: 0, total: 0 }, openPrs: [], tickets: [], worktrees: 0 };
+    return {
+        name,
+        agents: 0,
+        byStatus: {},
+        members: [],
+        plan: { done: 0, total: 0 },
+        openPrs: [],
+        tickets: [],
+        worktrees: 0,
+    };
 }
 /**
  * Roll active sessions up by project. Returns a map keyed by project name,
@@ -41,6 +51,12 @@ export function rollupSessionsByProject(defs, sessions) {
         }
         r.agents++;
         r.byStatus[s.status] = (r.byStatus[s.status] ?? 0) + 1;
+        const member = { agent: s.kind, status: s.status };
+        if (s.ticket?.id)
+            member.ticket = s.ticket.id;
+        if (s.machine)
+            member.host = s.machine;
+        r.members.push(member);
         if (s.todos) {
             r.plan.done += s.todos.done;
             r.plan.total += s.todos.total;
@@ -67,6 +83,59 @@ export function planPct(plan) {
         return undefined;
     return Math.round((plan.done / plan.total) * 100);
 }
+/**
+ * Display order for the members line: the states a human scans for first
+ * (running, then idle, then need-input, then queued), everything else after,
+ * status name then agent name ascending within a state.
+ */
+const MEMBER_STATUS_RANK = { running: 0, idle: 1, input_required: 2, queued: 3 };
+/** Sort members for the card: running first, then idle, then the rest; agent name asc within a state. */
+export function sortProjectMembers(members) {
+    return [...members].sort((a, b) => {
+        const ra = MEMBER_STATUS_RANK[a.status] ?? 4;
+        const rb = MEMBER_STATUS_RANK[b.status] ?? 4;
+        if (ra !== rb)
+            return ra - rb;
+        if (ra === 4 && a.status !== b.status)
+            return a.status.localeCompare(b.status);
+        return a.agent.localeCompare(b.agent);
+    });
+}
+/** Cap for the members line before it collapses to `+N more`. */
+export const MEMBERS_LINE_LIMIT = 6;
+/**
+ * The `agents` line under `live`: one cell per DISTINCT member state —
+ * `claude · running · RUSH-2107 @zion` — with identical cells collapsed to a
+ * `×N` count (35 same-harness sessions in one state are one fact, not six
+ * truncated duplicates), capped at {@link MEMBERS_LINE_LIMIT} cells with a
+ * `+N more` tail counting members, not cells. Pure (chalk styling only); the
+ * caller adds the label.
+ */
+export function formatProjectMembers(members, limit = MEMBERS_LINE_LIMIT) {
+    if (members.length === 0)
+        return '';
+    // Collapse identical cells — 35 same-harness sessions in the same state are
+    // one fact (`claude · running ×16`), not six truncated duplicates.
+    const counts = new Map();
+    for (const m of sortProjectMembers(members)) {
+        const parts = [m.agent, m.status];
+        if (m.ticket)
+            parts.push(m.ticket);
+        const cell = parts.join(' · ') + (m.host ? ` @${m.host}` : '');
+        const key = cell.toLowerCase();
+        const entry = counts.get(key);
+        if (entry)
+            entry.n++;
+        else
+            counts.set(key, { cell, n: 1 });
+    }
+    const entries = [...counts.values()];
+    const shown = entries.slice(0, Math.max(1, limit));
+    const shownMembers = shown.reduce((acc, e) => acc + e.n, 0);
+    const more = members.length - shownMembers;
+    const cells = shown.map(({ cell, n }) => (n > 1 ? `${cell} ×${n}` : cell));
+    return cells.join(chalk.dim('  ·  ')) + (more > 0 ? chalk.dim(`  ·  +${more} more`) : '');
+}
 /**
  * Harvest the signals that don't live on the active-session list: recently
  * merged PRs (from GitHub via `gh`) and artifacts agents produced (from the
@@ -96,6 +165,18 @@ export async function enrichProjectSignals(def, windowDays, nowMs, opts = {}) {
         catch {
             /* gh missing / unauthenticated / repo not found — skip this signal */
         }
+        // Latest release of the PRIMARY repo only (repos[] is deliberately not
+        // scanned — one release line per card). Same best-effort degradation.
+        try {
+            const { stdout } = await execFileAsync('gh', ['release', 'list', '-R', def.repo, '-L', '1', '--json', 'tagName,publishedAt'], { timeout: 8000, encoding: 'utf8' });
+            const rows = JSON.parse(stdout);
+            const first = rows[0];
+            if (first?.tagName)
+                out.latestRelease = { tag: first.tagName, publishedAt: first.publishedAt ?? '' };
+        }
+        catch {
+            /* gh missing / unauthenticated / repo has no releases — skip this signal */
+        }
     }
     return out;
 }

package/dist/lib/projects.d.ts

@@ -24,6 +24,12 @@ export interface ProjectRepo {
     slug: string;
     /** Optional path within the repo an agent working this project cares about. */
     subpath?: string;
+    /**
+     * Optional home-relative local checkout of this repo. The def's `root` only
+     * knows the primary repo on disk; `path` opts an additional repo into
+     * workspace probing (`projects status --fleet`).
+     */
+    path?: string;
 }
 /**
  * A described context anchor: a subdirectory plus what it is. Agents starting on

package/dist/lib/projects.js

@@ -86,9 +86,15 @@ export function validateProjectDef(raw, sourceName) {
         def.repos = o.repos.flatMap((r) => {
             if (r && typeof r === 'object' && typeof r.slug === 'string') {
                 const rr = r;
+                // A malformed `path` sinks the whole entry, like any other malformed
+                // list row — a half-valid repo must not probe a surprising location.
+                if (rr.path !== undefined && typeof rr.path !== 'string')
+                    return [];
                 const repo = { slug: rr.slug };
                 if (typeof rr.subpath === 'string')
                     repo.subpath = rr.subpath;
+                if (typeof rr.path === 'string')
+                    repo.path = rr.path;
                 return [repo];
             }
             return [];
@@ -192,6 +198,12 @@ export function writeProjectDef(def) {
         defaultPath: validated.defaultPath
             ? toHomeRelative(expandLocalHome(validated.defaultPath))
             : undefined,
+        repos: validated.repos?.map((r) => {
+            const repo = { ...r };
+            if (r.path)
+                repo.path = toHomeRelative(expandLocalHome(r.path));
+            return repo;
+        }),
     };
     // Drop undefined keys so the YAML stays clean.
     const clean = Object.fromEntries(Object.entries(normalized).filter(([, v]) => v !== undefined));

package/dist/lib/remote-agents-json.d.ts

@@ -2,7 +2,7 @@ export interface RemoteAgentsJsonOptions<T> {
     args: string[];
     noFanoutEnv: string;
     hosts?: string[];
-    parse: (stdout: string, machine: string) => T[];
+    parse: (stdout: string, machine: string) => T[] | RemoteAgentsJsonParseResult<T>;
     /**
      * Suppress the per-device "unreachable — skipped" stderr line. The skipped
      * names still come back in {@link RemoteAgentsJsonResult.skipped}, so a caller
@@ -11,12 +11,25 @@ export interface RemoteAgentsJsonOptions<T> {
      */
     quiet?: boolean;
 }
+export interface RemoteAgentsJsonParseResult<T> {
+    items: T[];
+    valid: boolean;
+}
 export interface RemoteAgentsJsonResult<T> {
     items: T[];
     deviceCount: number;
     /** Devices that were dialed but answered with an error / no CLI / a timeout. */
     skipped: string[];
+    /** Devices that exited successfully but returned invalid JSON for this command. */
+    parseFailed: string[];
+    /** Whether automatic target discovery failed before any peer could be dialed. */
+    discoveryFailed: boolean;
 }
+export declare function normalizeRemoteAgentsJsonParse<T>(parsed: T[] | RemoteAgentsJsonParseResult<T>): RemoteAgentsJsonParseResult<T>;
+export declare function parseRemoteAgentsJsonPayload<T>(stdout: string, machine: string, parse: RemoteAgentsJsonOptions<T>['parse']): {
+    items: T[];
+    parseFailed: boolean;
+};
 /** Build the command one peer runs, with a guard that prevents recursive fan-out. */
 export declare function remoteAgentsJsonCommand(args: string[], noFanoutEnv: string, os?: string): string;
 /** Query explicit hosts, or every registered online peer when hosts is omitted. */

package/dist/lib/remote-agents-json.js

@@ -15,6 +15,15 @@ import { loadDevices, isControlDevice, isDialableDevice } from './devices/regist
 import { remoteShellFor, buildWindowsAgentsCommand } from './hosts/remote-cmd.js';
 import { machineId, normalizeHost } from './machine-id.js';
 const REMOTE_TIMEOUT_MS = 12_000;
+export function normalizeRemoteAgentsJsonParse(parsed) {
+    return Array.isArray(parsed) ? { items: parsed, valid: true } : parsed;
+}
+export function parseRemoteAgentsJsonPayload(stdout, machine, parse) {
+    const parsed = normalizeRemoteAgentsJsonParse(parse(stdout, machine));
+    return parsed.valid
+        ? { items: parsed.items, parseFailed: false }
+        : { items: [], parseFailed: true };
+}
 /** Build the command one peer runs, with a guard that prevents recursive fan-out. */
 export function remoteAgentsJsonCommand(args, noFanoutEnv, os) {
     if (remoteShellFor(os) === 'powershell') {
@@ -59,7 +68,7 @@ export async function gatherRemoteAgentsJson(options) {
             devices = await loadDevices();
         }
         catch {
-            return { items: [], deviceCount: 0, skipped: [] };
+            return { items: [], deviceCount: 0, skipped: [], parseFailed: [], discoveryFailed: true };
         }
         for (const device of Object.values(devices)) {
             // Live SSH-probe verdict first, cached tailscale snapshot only as a
@@ -90,6 +99,7 @@ export async function gatherRemoteAgentsJson(options) {
         }
     }
     const skipped = [];
+    const parseFailed = [];
     const results = await Promise.all(targets.map(async (target) => {
         const command = remoteAgentsJsonCommand(options.args, options.noFanoutEnv, target.os);
         const result = await sshCapture(target.target, command);
@@ -100,7 +110,15 @@ export async function gatherRemoteAgentsJson(options) {
             }
             return [];
         }
-        return options.parse(result.stdout, target.machine);
+        const parsed = parseRemoteAgentsJsonPayload(result.stdout, target.machine, options.parse);
+        if (parsed.parseFailed) {
+            parseFailed.push(target.name);
+            if (!options.quiet) {
+                process.stderr.write(chalk.gray(`  ${target.name}: unreachable or no agents CLI — skipped\n`));
+            }
+            return [];
+        }
+        return parsed.items;
     }));
-    return { items: results.flat(), deviceCount: targets.length, skipped };
+    return { items: results.flat(), deviceCount: targets.length, skipped, parseFailed, discoveryFailed: false };
 }

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

@@ -26,6 +26,17 @@ 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;
+/**
+ * The harness a routine runs on, for the notification's right-hand avatar, or
+ * undefined when none owns it. A command routine is deterministic housekeeping
+ * with no agent, so it gets no avatar. An agent routine names its own harness.
+ * A workflow routine has no `agent` field (the schema omits it — routines.ts
+ * `JobConfig.agent` and the validation that rejects setting both), and it runs
+ * via `agents run <workflow>`, which delegates to claude under the hood — so its
+ * avatar is the Claude mark, matching `effectiveAgent` on the finish path
+ * (runner.ts). Start and finish banners therefore show the same avatar.
+ */
+export declare function routineAgent(r: Pick<JobConfig, 'agent' | 'workflow' | 'command'>): string | undefined;
 /** "1m 20s" / "45s" / "2h 3m" from a millisecond duration, or null when unknown. */
 export declare function formatDuration(ms: number | undefined): string | null;
 /**

package/dist/lib/routine-notify.js

@@ -33,6 +33,24 @@ export function routineKind(r) {
         return 'workflow';
     return 'agent';
 }
+/**
+ * The harness a routine runs on, for the notification's right-hand avatar, or
+ * undefined when none owns it. A command routine is deterministic housekeeping
+ * with no agent, so it gets no avatar. An agent routine names its own harness.
+ * A workflow routine has no `agent` field (the schema omits it — routines.ts
+ * `JobConfig.agent` and the validation that rejects setting both), and it runs
+ * via `agents run <workflow>`, which delegates to claude under the hood — so its
+ * avatar is the Claude mark, matching `effectiveAgent` on the finish path
+ * (runner.ts). Start and finish banners therefore show the same avatar.
+ */
+export function routineAgent(r) {
+    const kind = routineKind(r);
+    if (kind === 'command')
+        return undefined;
+    if (kind === 'workflow')
+        return 'claude';
+    return r.agent?.trim() || undefined;
+}
 /** Human label for the routine body ("agent claude", "workflow deploy", "command"). */
 function routineLabel(r) {
     if (r.command)
@@ -90,6 +108,7 @@ export function routineStartNotification(config) {
         subtitle: config.name,
         body: `Running ${routineLabel(config)}`,
         action: 'routines:list',
+        agent: routineAgent(config),
     };
 }
 /**
@@ -108,6 +127,7 @@ export function routineStartFailedNotification(config, error) {
         subtitle: config.name,
         body: `Failed to start: ${error}`,
         action: 'routines:list',
+        agent: routineAgent(config),
     };
 }
 /**
@@ -131,6 +151,7 @@ export function routineFinishNotification(meta, opts = {}) {
             subtitle: meta.jobName,
             body: snippet ?? (dur ? `Completed in ${dur}` : 'Completed'),
             action,
+            agent: routineAgent(meta),
         };
     }
     // failed | timeout
@@ -144,6 +165,7 @@ export function routineFinishNotification(meta, opts = {}) {
         subtitle: meta.jobName,
         body: reason,
         action,
+        agent: routineAgent(meta),
     };
 }
 /** Read a finished run's report text + the best artifact to open on click. */

package/dist/lib/routines.d.ts

@@ -293,6 +293,47 @@ export declare function finalizeRunMeta(meta: RunMeta, status: RunMeta['status']
  * catchup/overdue, manual run) gates on this.
  */
 export declare function jobRunsOnThisDevice(config: Pick<JobConfig, 'devices'>): boolean;
+/**
+ * The ONE device that owns a routine — the single daemon allowed to fire it.
+ *
+ * `devices` is an allowlist, and every listed device used to fire
+ * independently, so a routine pinned to two boxes ran **twice** per schedule:
+ * two full agent sessions doing identical work, burning double the quota. On
+ * this fleet seven routines were in that state, e.g. `security-sweep` running
+ * at 15:30:02 on one box and 15:30:03 on the other, both completing.
+ *
+ * Ownership is a pure function of the config — the first entry in normalized
+ * sort order — so every daemon independently reaches the same answer with no
+ * lease, no cross-device coordination, and no split brain when the fleet
+ * partitions. A multi-entry pin is a misconfiguration
+ * ({@link hasAmbiguousDevicePin}); this keeps such a routine running exactly
+ * once instead of silently dropping it, while `validateJob` refuses to create
+ * a new one and `agents doctor` surfaces the existing ones.
+ *
+ * Returns null when the routine is unrestricted (empty or omitted `devices`).
+ */
+export declare function routineOwnerDevice(config: Pick<JobConfig, 'devices'>): string | null;
+/**
+ * Does this routine name more than one distinct device? Such a pin used to mean
+ * "fire on each of them"; it now means "fire only on the first", which is
+ * almost certainly not what the author intended either way — so it is reported
+ * as a misconfiguration rather than silently reinterpreted.
+ */
+export declare function hasAmbiguousDevicePin(config: Pick<JobConfig, 'devices'>): boolean;
+/** One routine whose `devices` names more than one machine, with its resolved owner. */
+export interface AmbiguousDevicePin {
+    name: string;
+    devices: string[];
+    /** The device that now fires it — the rest are inert. */
+    owner: string;
+}
+/**
+ * Every routine carrying a multi-device pin. Surfaced by `agents doctor` and
+ * `agents routines list` so an existing misconfiguration is visible rather than
+ * silently reinterpreted: before ownership became singular each of these fired
+ * once per listed device, doubling the work and the agent spend.
+ */
+export declare function findAmbiguousDevicePins(cwd?: string): AmbiguousDevicePin[];
 /**
  * Resolve the effective host strategy for a job.
  * Bare `host:` without an explicit strategy implies `host` (back-compat with
@@ -487,6 +528,18 @@ export declare function discoverJobsFromRepo(repoPath: string): Array<{
 export declare function jobExists(name: string): boolean;
 /** Get the filesystem path of a job's YAML config file, or null if not found. */
 export declare function getJobPath(name: string): string | null;
+/**
+ * Resolve a routine's YAML across EVERY layer `listJobs`/`readJob` read — user
+ * then system — not just the user dir.
+ *
+ * `getJobPath` is user-layer only because its callers write there. Read paths
+ * that ask "when did this routine come to exist" need the system layer too:
+ * a built-in shipped in the system repo has no user-layer file and no
+ * `createdAt`, so a user-layer-only lookup returns null, the overdue floor is
+ * skipped, and the routine reads as instantly overdue on first daemon start —
+ * exactly the case the floor exists to prevent.
+ */
+export declare function resolveJobFilePath(name: string): string | null;
 /**
  * Parse an "at" time string into a one-shot cron expression.
  * Supports formats like: