@phnx-labs/agents-cli 1.20.91 → 1.20.93

package/dist/lib/projects.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Named project definitions — the layer above the `--project <slug>` convention.
+ *
+ * `agents run --project <slug>` already resolves a bare name to a working
+ * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
+ * This module adds editable definitions on top: one YAML file per project under
+ * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
+ * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
+ * machines for free via `agents push/pull`). A defined project can name itself
+ * independently of its folder, bind more than one repo, pin a monorepo subpath,
+ * describe context subdirectories an agent should start from, carry a Linear
+ * link and external integrations, and set an explicit default path.
+ *
+ * Portable by construction: `root`/`defaultPath` are stored home-relative
+ * (`~/…`) via `toHomeRelative`, so the same definition re-roots on any machine
+ * whose home differs — the exact mechanism `project-root.ts` already relies on.
+ *
+ * Resolution stays additive: an undefined slug still resolves exactly as today
+ * (see `resolveProjectRef`), a defined one overrides it.
+ */
+/** A git repo bound to a project, with an optional monorepo subpath. */
+export interface ProjectRepo {
+    /** GitHub slug `owner/repo`. */
+    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
+ * the project read `purpose` to know where to look — an indexed starting point,
+ * not just a path. This is the richer form of the single monorepo-focus dir.
+ */
+export interface ProjectContext {
+    /** Path relative to the project root (e.g. `apps/web`). */
+    path: string;
+    /** One line on how this subtree relates to the project. */
+    purpose: string;
+}
+/** An external context source hung off the project (surfaced in `projects show`). */
+export interface ProjectIntegration {
+    /** e.g. `gdrive`, `notion`, `figma`, `url`. */
+    kind: string;
+    url: string;
+    label?: string;
+}
+/** The parsed `~/.agents/projects/<name>.yaml`. */
+export interface ProjectDef {
+    /** Stable id; matches the filename; what `--project` takes. */
+    name: string;
+    description?: string;
+    /** Repo / monorepo root, home-relative for portability. */
+    root?: string;
+    /** Where an agent's cwd lands. Defaults to `root` when unset. */
+    defaultPath?: string;
+    /** Primary GitHub slug (`owner/repo`) — for PR / CI / status roll-up. */
+    repo?: string;
+    /** All bound repos, each with an optional monorepo subpath. */
+    repos?: ProjectRepo[];
+    /** Described starting points inside the project. */
+    contexts?: ProjectContext[];
+    /** External context sources (Drive, docs, …). */
+    integrations?: ProjectIntegration[];
+    /** Linear project link — reuses the existing GraphQL path. */
+    linear?: {
+        projectId?: string;
+        url?: string;
+    };
+    /** Free-form doc links surfaced in `projects show`. */
+    docs?: string[];
+}
+/** A project name safe to use as a filename: no separators, `..`, or leading dot. */
+export declare function isSafeProjectName(name: string): boolean;
+/** Absolute path to a project's YAML definition. Throws on an unsafe name. */
+export declare function projectDefPath(name: string): string;
+/**
+ * Validate a raw parsed object into a `ProjectDef`, throwing an actionable error
+ * on the first problem. A malformed document or identity (bad/mismatched name)
+ * throws; malformed entries inside the optional lists (`repos`/`contexts`/
+ * `integrations`) are dropped so one bad row can't sink an otherwise good def.
+ */
+export declare function validateProjectDef(raw: unknown, sourceName?: string): ProjectDef;
+/**
+ * Load a single project definition by name. Returns undefined when the file is
+ * absent (the common "not a defined project, fall back to convention" case) but
+ * throws when a file EXISTS and is malformed — a broken definition is loud.
+ */
+export declare function loadProjectDef(name: string): ProjectDef | undefined;
+/**
+ * List every defined project, sorted by name. Skips (does not throw on) a
+ * malformed file so one bad definition can't break `projects list`; the loader
+ * for a single named project stays strict.
+ */
+export declare function listProjectDefs(): ProjectDef[];
+/**
+ * Persist a project definition, normalizing `root`/`defaultPath` to home-relative
+ * so it stays portable across machines. Creates the projects dir on first write.
+ */
+export declare function writeProjectDef(def: ProjectDef): string;
+/** Delete a project definition. Returns true if a file was removed. Never touches the repo. */
+export declare function removeProjectDef(name: string): boolean;
+/**
+ * The cwd an agent lands in for a defined project: `defaultPath` when set, else
+ * `root`. Home-relative when `forRemote` (the remote shell expands `~`), else
+ * expanded against the local home. Returns undefined when neither is set.
+ */
+export declare function projectBasePath(def: ProjectDef, forRemote: boolean): string | undefined;
+/**
+ * Which defined project a session belongs to, derived from its working
+ * directory. A session whose `cwd` sits inside a project's repo root (or a
+ * worktree under it) is a member; the LONGEST matching root wins so a nested
+ * project beats its parent. Returns undefined when no definition contains the
+ * path.
+ *
+ * The comparison is against the LOCAL home: roots and the cwd are both expanded
+ * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
+ * this machine's home layout. A session recorded on a different-home machine
+ * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
+ * home-relative variant lands (see the deferred item in docs/11-projects.md).
+ */
+export declare function projectNameForCwd(cwd: string | undefined, defs: ProjectDef[]): string | undefined;
+/**
+ * The canonical project label for a cwd, for every surface that buckets work by
+ * project (the activity timeline, feed posts, the sessions overview): the
+ * DEFINED project whose root contains the cwd (longest root wins, so a
+ * multi-repo project reads as one bucket), else the repository-level key from
+ * {@link resolveProjectKey}. `defs` comes from {@link listProjectDefs}, which is
+ * fail-open — with no definitions this degrades to exactly today's behavior.
+ */
+export declare function resolveProjectNameForCwd(cwd: string | undefined | null, defs: ProjectDef[]): string | undefined;
+/**
+ * Resolve a defined project's ref to a working directory, mirroring
+ * `buildProjectPath`'s `forRemote` contract (a home-relative `~/…` for the
+ * remote shell to expand, an absolute local path otherwise). A `@worktree`
+ * lands under the repo ROOT's `.agents/worktrees/`, not the `defaultPath`
+ * subdir — worktrees are per-repo, not per-focus. Returns undefined when the
+ * definition carries no `root`/`defaultPath` (caller falls back to convention).
+ */
+export declare function resolveDefinedProjectPath(def: ProjectDef, worktree: string | undefined, forRemote: boolean): string | undefined;

package/dist/lib/projects.js

@@ -0,0 +1,313 @@
+/**
+ * Named project definitions — the layer above the `--project <slug>` convention.
+ *
+ * `agents run --project <slug>` already resolves a bare name to a working
+ * directory by pure convention (`<projectRoot>/<slug>`, see `project-root.ts`).
+ * This module adds editable definitions on top: one YAML file per project under
+ * `~/.agents/projects/<name>.yaml`, sitting beside the existing `routines/`,
+ * `monitors/`, and `teams/` dirs in the user repo (so definitions sync across
+ * machines for free via `agents push/pull`). A defined project can name itself
+ * independently of its folder, bind more than one repo, pin a monorepo subpath,
+ * describe context subdirectories an agent should start from, carry a Linear
+ * link and external integrations, and set an explicit default path.
+ *
+ * Portable by construction: `root`/`defaultPath` are stored home-relative
+ * (`~/…`) via `toHomeRelative`, so the same definition re-roots on any machine
+ * whose home differs — the exact mechanism `project-root.ts` already relies on.
+ *
+ * Resolution stays additive: an undefined slug still resolves exactly as today
+ * (see `resolveProjectRef`), a defined one overrides it.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getProjectsDir } from './state.js';
+import { safeJoin } from './paths.js';
+import { toHomeRelative, expandLocalHome } from './project-root.js';
+import { resolveProjectKey } from './project-key.js';
+/** A project name safe to use as a filename: no separators, `..`, or leading dot. */
+export function isSafeProjectName(name) {
+    return (typeof name === 'string' &&
+        name.length > 0 &&
+        name.length <= 64 &&
+        /^[a-z0-9][a-z0-9._-]*$/i.test(name) &&
+        name !== '.' &&
+        name !== '..');
+}
+/** Absolute path to a project's YAML definition. Throws on an unsafe name. */
+export function projectDefPath(name) {
+    if (!isSafeProjectName(name)) {
+        throw new Error(`Invalid project name: "${name}" (letters, digits, ., _, - only)`);
+    }
+    return safeJoin(getProjectsDir(), `${name}.yaml`);
+}
+/**
+ * Validate a raw parsed object into a `ProjectDef`, throwing an actionable error
+ * on the first problem. A malformed document or identity (bad/mismatched name)
+ * throws; malformed entries inside the optional lists (`repos`/`contexts`/
+ * `integrations`) are dropped so one bad row can't sink an otherwise good def.
+ */
+export function validateProjectDef(raw, sourceName) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`Project ${sourceName ?? ''} is not a YAML mapping`.trim());
+    }
+    const o = raw;
+    // The filename is the identity; a `name:` field is optional but, when present,
+    // must be a valid slug — a malformed one is a loud error, not a silent fallback.
+    const hasNameField = 'name' in o && o.name !== undefined && o.name !== null;
+    let name;
+    if (hasNameField) {
+        if (typeof o.name !== 'string' || !isSafeProjectName(o.name)) {
+            throw new Error(`Project ${sourceName ?? ''}: "name" must be a valid slug (got ${JSON.stringify(o.name)})`);
+        }
+        name = o.name;
+    }
+    else {
+        name = sourceName;
+    }
+    if (!name || !isSafeProjectName(name)) {
+        throw new Error('Project definition is missing a valid "name"');
+    }
+    // The filename IS the stable id — a def whose `name:` disagrees with its
+    // filename would resolve under one name and list under another.
+    if (hasNameField && sourceName && name !== sourceName) {
+        throw new Error(`Project ${sourceName}: "name" (${JSON.stringify(name)}) must match the filename — the filename is the stable id`);
+    }
+    const def = { name };
+    if (typeof o.description === 'string')
+        def.description = o.description;
+    if (typeof o.root === 'string')
+        def.root = o.root;
+    if (typeof o.defaultPath === 'string')
+        def.defaultPath = o.defaultPath;
+    if (typeof o.repo === 'string')
+        def.repo = o.repo;
+    if (Array.isArray(o.repos)) {
+        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 [];
+        });
+    }
+    if (Array.isArray(o.contexts)) {
+        def.contexts = o.contexts.flatMap((c) => {
+            if (c &&
+                typeof c === 'object' &&
+                typeof c.path === 'string' &&
+                typeof c.purpose === 'string') {
+                const cc = c;
+                return [{ path: cc.path, purpose: cc.purpose }];
+            }
+            return [];
+        });
+    }
+    if (Array.isArray(o.integrations)) {
+        def.integrations = o.integrations.flatMap((i) => {
+            if (i &&
+                typeof i === 'object' &&
+                typeof i.kind === 'string' &&
+                typeof i.url === 'string') {
+                const ii = i;
+                const integ = { kind: ii.kind, url: ii.url };
+                if (typeof ii.label === 'string')
+                    integ.label = ii.label;
+                return [integ];
+            }
+            return [];
+        });
+    }
+    if (o.linear && typeof o.linear === 'object' && !Array.isArray(o.linear)) {
+        const l = o.linear;
+        def.linear = {};
+        if (typeof l.projectId === 'string')
+            def.linear.projectId = l.projectId;
+        if (typeof l.url === 'string')
+            def.linear.url = l.url;
+    }
+    if (Array.isArray(o.docs))
+        def.docs = o.docs.filter((d) => typeof d === 'string');
+    return def;
+}
+/**
+ * Load a single project definition by name. Returns undefined when the file is
+ * absent (the common "not a defined project, fall back to convention" case) but
+ * throws when a file EXISTS and is malformed — a broken definition is loud.
+ */
+export function loadProjectDef(name) {
+    if (!isSafeProjectName(name))
+        return undefined;
+    let raw;
+    try {
+        raw = fs.readFileSync(projectDefPath(name), 'utf8');
+    }
+    catch {
+        return undefined; // absent — not a defined project
+    }
+    return validateProjectDef(yaml.parse(raw), name);
+}
+/**
+ * List every defined project, sorted by name. Skips (does not throw on) a
+ * malformed file so one bad definition can't break `projects list`; the loader
+ * for a single named project stays strict.
+ */
+export function listProjectDefs() {
+    let files;
+    try {
+        // Definitions are `<name>.yaml` (what projectDefPath/loadProjectDef read). We
+        // deliberately do NOT list `.yml` here — accepting it would then ENOENT in the
+        // loader and silently drop the project. One extension, one code path.
+        files = fs.readdirSync(getProjectsDir()).filter((f) => f.endsWith('.yaml'));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        const name = f.replace(/\.yaml$/, '');
+        try {
+            const def = loadProjectDef(name);
+            if (def)
+                out.push(def);
+        }
+        catch {
+            /* malformed — skip in the listing */
+        }
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Persist a project definition, normalizing `root`/`defaultPath` to home-relative
+ * so it stays portable across machines. Creates the projects dir on first write.
+ */
+export function writeProjectDef(def) {
+    const validated = validateProjectDef(def, def.name);
+    const normalized = {
+        ...validated,
+        root: validated.root ? toHomeRelative(expandLocalHome(validated.root)) : undefined,
+        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));
+    const target = projectDefPath(def.name);
+    fs.mkdirSync(getProjectsDir(), { recursive: true });
+    fs.writeFileSync(target, yaml.stringify(clean), 'utf8');
+    return target;
+}
+/** Delete a project definition. Returns true if a file was removed. Never touches the repo. */
+export function removeProjectDef(name) {
+    try {
+        fs.unlinkSync(projectDefPath(name));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The cwd an agent lands in for a defined project: `defaultPath` when set, else
+ * `root`. Home-relative when `forRemote` (the remote shell expands `~`), else
+ * expanded against the local home. Returns undefined when neither is set.
+ */
+export function projectBasePath(def, forRemote) {
+    const base = def.defaultPath ?? def.root;
+    if (!base)
+        return undefined;
+    return forRemote ? base : expandLocalHome(base);
+}
+function projectRootsAbs(defs) {
+    const out = [];
+    for (const def of defs) {
+        const raw = def.root ?? def.defaultPath;
+        if (!raw)
+            continue;
+        out.push({ name: def.name, abs: path.resolve(expandLocalHome(raw)) });
+    }
+    return out;
+}
+/** True when `child` is `parent` or nested under it (path-segment aware). */
+function isUnder(child, parent) {
+    if (child === parent)
+        return true;
+    const withSep = parent.endsWith(path.sep) ? parent : parent + path.sep;
+    return child.startsWith(withSep);
+}
+/**
+ * Which defined project a session belongs to, derived from its working
+ * directory. A session whose `cwd` sits inside a project's repo root (or a
+ * worktree under it) is a member; the LONGEST matching root wins so a nested
+ * project beats its parent. Returns undefined when no definition contains the
+ * path.
+ *
+ * The comparison is against the LOCAL home: roots and the cwd are both expanded
+ * with `expandLocalHome` and resolved, so this matches sessions whose cwd shares
+ * this machine's home layout. A session recorded on a different-home machine
+ * (`/Users/x/…` vs `/home/x/…`) will not match until the fleet-wide,
+ * home-relative variant lands (see the deferred item in docs/11-projects.md).
+ */
+export function projectNameForCwd(cwd, defs) {
+    if (!cwd)
+        return undefined;
+    const abs = path.resolve(expandLocalHome(cwd));
+    let best;
+    let bestLen = -1;
+    for (const { name, abs: root } of projectRootsAbs(defs)) {
+        if (isUnder(abs, root) && root.length > bestLen) {
+            best = name;
+            bestLen = root.length;
+        }
+    }
+    return best;
+}
+/**
+ * The canonical project label for a cwd, for every surface that buckets work by
+ * project (the activity timeline, feed posts, the sessions overview): the
+ * DEFINED project whose root contains the cwd (longest root wins, so a
+ * multi-repo project reads as one bucket), else the repository-level key from
+ * {@link resolveProjectKey}. `defs` comes from {@link listProjectDefs}, which is
+ * fail-open — with no definitions this degrades to exactly today's behavior.
+ */
+export function resolveProjectNameForCwd(cwd, defs) {
+    if (!cwd)
+        return undefined;
+    return projectNameForCwd(cwd, defs) ?? resolveProjectKey(cwd);
+}
+/**
+ * Resolve a defined project's ref to a working directory, mirroring
+ * `buildProjectPath`'s `forRemote` contract (a home-relative `~/…` for the
+ * remote shell to expand, an absolute local path otherwise). A `@worktree`
+ * lands under the repo ROOT's `.agents/worktrees/`, not the `defaultPath`
+ * subdir — worktrees are per-repo, not per-focus. Returns undefined when the
+ * definition carries no `root`/`defaultPath` (caller falls back to convention).
+ */
+export function resolveDefinedProjectPath(def, worktree, forRemote) {
+    if (worktree) {
+        const rootRaw = def.root ?? def.defaultPath;
+        if (!rootRaw)
+            return undefined;
+        const wt = `${rootRaw}/.agents/worktrees/${worktree}`;
+        return forRemote ? wt : path.resolve(expandLocalHome(wt));
+    }
+    const base = projectBasePath(def, forRemote);
+    if (!base)
+        return undefined;
+    return forRemote ? base : path.resolve(base);
+}

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

@@ -3,10 +3,19 @@ export interface RemoteAgentsJsonOptions<T> {
     noFanoutEnv: string;
     hosts?: string[];
     parse: (stdout: string, machine: string) => T[];
+    /**
+     * Suppress the per-device "unreachable — skipped" stderr line. The skipped
+     * names still come back in {@link RemoteAgentsJsonResult.skipped}, so a caller
+     * that fans out by DEFAULT can report them once, compactly, instead of
+     * printing a line per offline box above its output. Never a silent drop.
+     */
+    quiet?: boolean;
 }
 export interface RemoteAgentsJsonResult<T> {
     items: T[];
     deviceCount: number;
+    /** Devices that were dialed but answered with an error / no CLI / a timeout. */
+    skipped: string[];
 }
 /** 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;

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

@@ -11,7 +11,7 @@ import chalk from 'chalk';
 import { SSH_OPTS, controlOpts, assertValidSshTarget, shellQuote } from './ssh-exec.js';
 import { sshTargetFor } from './devices/connect.js';
 import { resolveExplicitTargets } from './devices/resolve-target.js';
-import { loadDevices, isControlDevice } from './devices/registry.js';
+import { loadDevices, isControlDevice, isDialableDevice } from './devices/registry.js';
 import { remoteShellFor, buildWindowsAgentsCommand } from './hosts/remote-cmd.js';
 import { machineId, normalizeHost } from './machine-id.js';
 const REMOTE_TIMEOUT_MS = 12_000;
@@ -59,10 +59,12 @@ export async function gatherRemoteAgentsJson(options) {
             devices = await loadDevices();
         }
         catch {
-            return { items: [], deviceCount: 0 };
+            return { items: [], deviceCount: 0, skipped: [] };
         }
         for (const device of Object.values(devices)) {
-            if (device.tailscale?.online !== true)
+            // Live SSH-probe verdict first, cached tailscale snapshot only as a
+            // fallback — see isDialableDevice (mirrors session/remote-list.ts).
+            if (!isDialableDevice(device))
                 continue;
             if (normalizeHost(device.name) === self)
                 continue;
@@ -87,14 +89,18 @@ export async function gatherRemoteAgentsJson(options) {
             }
         }
     }
+    const skipped = [];
     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);
         if (result.code !== 0) {
-            process.stderr.write(chalk.gray(`  ${target.name}: unreachable or no agents CLI — skipped\n`));
+            skipped.push(target.name);
+            if (!options.quiet) {
+                process.stderr.write(chalk.gray(`  ${target.name}: unreachable or no agents CLI — skipped\n`));
+            }
             return [];
         }
         return options.parse(result.stdout, target.machine);
     }));
-    return { items: results.flat(), deviceCount: targets.length };
+    return { items: results.flat(), deviceCount: targets.length, skipped };
 }

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/run-notify.js

@@ -34,6 +34,9 @@ export function buildRunFinishNotification(ctx, exitCode) {
     const n = {
         title: exitCode === 0 ? `${label} finished` : `${label} failed`,
         body: shorten(ctx.prompt?.trim() || `${ctx.agent} run`),
+        // The harness that ran becomes the banner's right-hand avatar, so a finished
+        // run is identifiable at a glance even when `--name` renamed the title.
+        agent: ctx.agent,
     };
     if (where)
         n.subtitle = where;

package/dist/lib/secrets/audit.d.ts

@@ -1,4 +1,4 @@
-export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked';
+export type SecretAuditEvent = 'secrets.get' | 'secrets.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view';
 export interface SecretAuditParams {
     /** Which audit event this is — a read (`secrets.get`) or an unlock grant. */
     event: SecretAuditEvent;