@phnx-labs/agents-cli 1.22.8 → 1.22.10

package/dist/lib/crabbox/config.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The repo-local crabbox config (`.crabbox.yaml` at the repo root).
+ *
+ * crabbox itself reads this file when warming a box (the `profile:` key becomes
+ * the box's `profile` label). `agents run --lease` reads it too so the warm-pool
+ * reuse check matches on the SAME profile the warmup would have used — a reused
+ * box is then interchangeable with a fresh one (scripts/sandbox.sh's
+ * `pick_ready_box` resolves the pool the same way).
+ */
+/**
+ * The profile label a box warm pool shares. Matches sandbox.sh's
+ * `PROFILE="${PROFILE:-default}"`: a run with no configured profile and a box
+ * with no `profile` label both normalize here, so they still match each other.
+ */
+export declare const DEFAULT_CRABBOX_PROFILE = "default";
+/**
+ * The `profile:` declared by `<repoRoot>/.crabbox.yaml`, or undefined when the
+ * file is missing, unreadable, or has no profile key (crabbox then applies its
+ * own default, which the pool matcher treats as DEFAULT_CRABBOX_PROFILE).
+ */
+export declare function readCrabboxRepoProfile(repoRoot: string): string | undefined;

package/dist/lib/crabbox/config.js

@@ -0,0 +1,43 @@
+/**
+ * The repo-local crabbox config (`.crabbox.yaml` at the repo root).
+ *
+ * crabbox itself reads this file when warming a box (the `profile:` key becomes
+ * the box's `profile` label). `agents run --lease` reads it too so the warm-pool
+ * reuse check matches on the SAME profile the warmup would have used — a reused
+ * box is then interchangeable with a fresh one (scripts/sandbox.sh's
+ * `pick_ready_box` resolves the pool the same way).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+/**
+ * The profile label a box warm pool shares. Matches sandbox.sh's
+ * `PROFILE="${PROFILE:-default}"`: a run with no configured profile and a box
+ * with no `profile` label both normalize here, so they still match each other.
+ */
+export const DEFAULT_CRABBOX_PROFILE = 'default';
+/**
+ * The `profile:` declared by `<repoRoot>/.crabbox.yaml`, or undefined when the
+ * file is missing, unreadable, or has no profile key (crabbox then applies its
+ * own default, which the pool matcher treats as DEFAULT_CRABBOX_PROFILE).
+ */
+export function readCrabboxRepoProfile(repoRoot) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(repoRoot, '.crabbox.yaml'), 'utf-8');
+    }
+    catch {
+        return undefined; // no repo crabbox config — crabbox's own default applies
+    }
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return undefined;
+    const profile = parsed.profile;
+    return typeof profile === 'string' && profile.length > 0 ? profile : undefined;
+}

package/dist/lib/crabbox/lease.d.ts

@@ -1,10 +1,12 @@
 /**
  * `agents run --lease` orchestrator.
  *
- * Lease an ephemeral crabbox → provision the picked runtime(s) + their
- * credentials → run the agent on the box (via `crabbox run`, which owns the
- * SSH) → tear the box down. The whole box-side sequence rides a single
- * `--script-stdin` body so the token contents never touch argv.
+ * Acquire a box → provision the picked runtime(s) + their credentials → run the
+ * agent on the box (via `crabbox run`, which owns the SSH) → tear the box down.
+ * Acquisition is reuse-first against the warm profile pool (a ready box carrying
+ * the run's profile + netMode labels is reused and kept; `--fresh` opts out and
+ * always leases a new, torn-down box). The whole box-side sequence rides a
+ * single `--script-stdin` body so the token contents never touch argv.
  *
  * ── Command-layer contract (RUSH-1920/1921/1924) ─────────────────────────────
  * Exports the commands layer (exec.ts / lease.ts / ssh.ts) consumes:
@@ -12,7 +14,9 @@
  *     --bare) gates the `copy-setup` progress sentinel; `opts.netMode`
  *     ('public' | 'tailscale', default 'public') adds the `joined-tailnet` step.
  *   • `LeaseRunOptions.copySetup` / `LeaseRunOptions.netMode` — forwarded by
- *     `leaseAndRun` (netMode → `crabboxWarmup`).
+ *     `leaseAndRun` (netMode → `crabboxWarmup`). `LeaseRunOptions.fresh`
+ *     (`--fresh`) skips the warm profile-pool reuse check and always leases a
+ *     new box, torn down after the run.
  *   • `crabboxWarmup(opts.netMode)` — 'tailscale' leases onto the tailnet
  *     (`--network tailscale -tailscale-tags tag:crabbox`); auth key rides the
  *     child env as `CRABBOX_TAILSCALE_AUTH_KEY` (crabboxEnv, cli.ts).
@@ -80,6 +84,12 @@ export interface LeaseRunOptions {
     keep?: boolean;
     /** Existing warm crabbox slug to reuse instead of provisioning a new lease. */
     reuseBox?: string;
+    /**
+     * Force a brand-new box: skip the warm profile-pool reuse check and tear the
+     * box down after the run (the pre-pool `--lease` behavior). `--fresh` at the
+     * command layer.
+     */
+    fresh?: boolean;
     /**
      * Raw wrapped Claude OAuth payload (from `resolveClaudeCredentialsBlob`), written
      * to `~/.claude/.credentials.json` on the box. The command layer resolves it

package/dist/lib/crabbox/lease.js

@@ -1,10 +1,12 @@
 /**
  * `agents run --lease` orchestrator.
  *
- * Lease an ephemeral crabbox → provision the picked runtime(s) + their
- * credentials → run the agent on the box (via `crabbox run`, which owns the
- * SSH) → tear the box down. The whole box-side sequence rides a single
- * `--script-stdin` body so the token contents never touch argv.
+ * Acquire a box → provision the picked runtime(s) + their credentials → run the
+ * agent on the box (via `crabbox run`, which owns the SSH) → tear the box down.
+ * Acquisition is reuse-first against the warm profile pool (a ready box carrying
+ * the run's profile + netMode labels is reused and kept; `--fresh` opts out and
+ * always leases a new, torn-down box). The whole box-side sequence rides a
+ * single `--script-stdin` body so the token contents never touch argv.
  *
  * ── Command-layer contract (RUSH-1920/1921/1924) ─────────────────────────────
  * Exports the commands layer (exec.ts / lease.ts / ssh.ts) consumes:
@@ -12,7 +14,9 @@
  *     --bare) gates the `copy-setup` progress sentinel; `opts.netMode`
  *     ('public' | 'tailscale', default 'public') adds the `joined-tailnet` step.
  *   • `LeaseRunOptions.copySetup` / `LeaseRunOptions.netMode` — forwarded by
- *     `leaseAndRun` (netMode → `crabboxWarmup`).
+ *     `leaseAndRun` (netMode → `crabboxWarmup`). `LeaseRunOptions.fresh`
+ *     (`--fresh`) skips the warm profile-pool reuse check and always leases a
+ *     new box, torn down after the run.
  *   • `crabboxWarmup(opts.netMode)` — 'tailscale' leases onto the tailnet
  *     (`--network tailscale -tailscale-tags tag:crabbox`); auth key rides the
  *     child env as `CRABBOX_TAILSCALE_AUTH_KEY` (crabboxEnv, cli.ts).
@@ -24,7 +28,7 @@
  *     secretsBundle?, userAgentsDir?, onData? }): Promise<CopySetupResult>` — the
  *     push-from-local the command layer runs before the box run.
  */
-import { crabboxFind, crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop } from './cli.js';
+import { crabboxFind, crabboxList, crabboxStatusReady, crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop, poolReusableBoxes } from './cli.js';
 import * as yaml from 'yaml';
 import { buildCredentialScript, buildHomeFileWriteScript, CLAUDE_TOKEN_REMOTE } from './runtimes.js';
 import { LEASE_AGENT_MARKER, leasePhaseSentinel } from './progress.js';
@@ -149,9 +153,32 @@ export function buildBootstrapScript(opts) {
         .filter((l) => l.length > 0)
         .join('\n');
 }
+/**
+ * The first warm box in this run's profile pool that is actually SSH-ready, or
+ * null. Mirrors scripts/sandbox.sh's `pick_ready_box`: list the running boxes
+ * for the run's profile + netMode, then gate each on `crabbox status`
+ * ready=true — a box whose bootstrap failed still lists as `running` and would
+ * burn the whole SSH wait before hard-failing. A skipped box is left alone
+ * (never stopped): a concurrent run may be mid-boot on it, and crabbox's idle
+ * timeout reaps genuine duds.
+ */
+function pickReadyPoolBox(opts) {
+    const candidates = poolReusableBoxes(crabboxList({ secretsBundle: opts.secretsBundle }), {
+        profile: opts.profile,
+        netMode: opts.netMode,
+    });
+    for (const b of candidates) {
+        if (crabboxStatusReady(b.slug, { secretsBundle: opts.secretsBundle }))
+            return b;
+    }
+    return null;
+}
 export async function leaseAndRun(opts) {
     const startedAt = Date.now();
     let box;
+    // A box this run did NOT provision — either the caller named it (`--box`) or
+    // it came out of the warm profile pool. Reused boxes are never torn down.
+    let reused = false;
     if (opts.reuseBox) {
         opts.onPhase?.({ kind: 'reuse', slug: opts.reuseBox });
         const found = crabboxFind(opts.reuseBox, { secretsBundle: opts.secretsBundle });
@@ -160,17 +187,29 @@ export async function leaseAndRun(opts) {
         box = found.ready
             ? found
             : await crabboxWaitReady(opts.reuseBox, { secretsBundle: opts.secretsBundle });
+        reused = true;
     }
     else {
-        opts.onPhase?.({ kind: 'warmup', backend: opts.backend });
-        box = await crabboxWarmup({
-            class: opts.boxClass,
-            profile: opts.profile,
-            provider: opts.backend,
-            secretsBundle: opts.secretsBundle,
-            netMode: opts.netMode,
-        });
-        await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+        // Reuse-first: before paying for a fresh lease, look for a warm box in this
+        // run's profile pool (same profile label the warmup would use, same netMode).
+        // `--fresh` opts out and always provisions.
+        const pooled = opts.fresh ? null : pickReadyPoolBox(opts);
+        if (pooled) {
+            opts.onPhase?.({ kind: 'reuse', slug: pooled.slug });
+            box = pooled;
+            reused = true;
+        }
+        else {
+            opts.onPhase?.({ kind: 'warmup', backend: opts.backend });
+            box = await crabboxWarmup({
+                class: opts.boxClass,
+                profile: opts.profile,
+                provider: opts.backend,
+                secretsBundle: opts.secretsBundle,
+                netMode: opts.netMode,
+            });
+            await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+        }
     }
     opts.onPhase?.({ kind: 'ready', box, elapsedMs: Date.now() - startedAt });
     // Setup-copy (F1, RUSH-1920): push the git-tracked ~/.agents config onto the
@@ -203,8 +242,9 @@ export async function leaseAndRun(opts) {
     }
     finally {
         // Always attempt teardown (bounds credential lifetime to the run) unless the
-        // caller explicitly asked to keep the box or targeted an existing warm box.
-        if (!opts.keep && !opts.reuseBox) {
+        // caller explicitly asked to keep the box or the box was reused (an explicit
+        // --box target or a warm pool box — both outlive this run).
+        if (!opts.keep && !reused) {
             opts.onPhase?.({ kind: 'teardown' });
             toreDown = crabboxStop(box.slug, { secretsBundle: opts.secretsBundle });
         }

package/dist/lib/daemon.js

@@ -888,14 +888,14 @@ export async function runDaemon() {
     };
     const fleetCacheInterval = setInterval(() => { void runFleetCacheWarm(); }, 3 * 60_000);
     const fleetCacheKickoff = setTimeout(() => { void runFleetCacheWarm(); }, 60_000);
-    // Adaptive usage refresh: keep the usage cache the `agents run` router reads
+    // Usage refresh: keep the usage cache the `agents run` router reads
     // (RUSH-2061, readOnly hot path) fresh, WITHOUT the hot path ever fetching.
-    // This host is the sole writer for its own local accounts. The tick wakes at
-    // the 90s floor, but per-account cadence gates the actual live fetches: an
-    // account racing toward its 5h cap is polled sooner (down to 90s), an idle one
-    // rarely (up to 15min), capped at ~6 provider calls/account/hour and skipped
-    // entirely while its provider is under a 429 backoff. Overlap-guarded like the
-    // probes above; a box signed into no networked-usage account is a clean no-op.
+    // This host is the sole writer for its own local accounts. The tick wakes
+    // every 60s (USAGE_REFRESH_TICK_MS) to consider due accounts; each account
+    // is scheduled at a fixed 5-minute cadence (REFRESH_INTERVAL_MS), capped at
+    // ~12 provider calls/account/hour, skipped under 429 backoff, and fetched
+    // with fileOnly credentials so a background tick never pops macOS Touch ID.
+    // Overlap-guarded: a slow pass cannot stack concurrent refresh loops.
     let refreshingUsage = false;
     const runUsageRefreshTick = async () => {
         if (refreshingUsage)
@@ -910,9 +910,9 @@ export async function runDaemon() {
                 writeUsageCache: writeClaudeUsageCache,
                 backoffUntil: usageRateLimitedUntil,
             });
-            if (r.refreshed > 0 || r.failed > 0) {
-                log('INFO', `usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped`);
-            }
+            // Always log a compact summary so "is refresh working?" is greppable even
+            // when every account was not-due (proves the tick ran).
+            log('INFO', `usage refresh: ${r.refreshed} refreshed, ${r.failed} failed, ${r.skippedNotDue} not-due, ${r.skippedBackoff} backed-off, ${r.skippedCap} capped`);
         }
         catch (err) {
             log('ERROR', `usage refresh failed: ${err.message}`);
@@ -921,7 +921,8 @@ export async function runDaemon() {
             refreshingUsage = false;
         }
     };
-    const usageRefreshInterval = setInterval(() => { void runUsageRefreshTick(); }, 90_000);
+    // 60s wake matches USAGE_REFRESH_TICK_MS in usage-refresh.ts (keep in sync).
+    const usageRefreshInterval = setInterval(() => { void runUsageRefreshTick(); }, 60_000);
     const usageRefreshKickoff = setTimeout(() => { void runUsageRefreshTick(); }, 30_000);
     // RUSH-1817: the startup host decision above is one-shot. If a standalone
     // broker answered agentPing() at daemon start, the daemon declined to host —

package/dist/lib/devices/resolve-target.d.ts

@@ -1,4 +1,4 @@
-import { splitUserHost } from '../hosts/registry.js';
+import { splitUserHost, type MatchHostOptions } from '../hosts/registry.js';
 import { type DeviceProfile } from './registry.js';
 export { splitUserHost };
 /** A dialable peer: the ssh target, the machine id used to tag its rows, a
@@ -21,9 +21,10 @@ export interface ResolvedExplicitTargetSet {
  * `user@host` / IP / FQDN literal yields a synthesized key-auth profile. A bare
  * unregistered alias (no `@`/dot) — or an ssh_config-only alias, which `agents
  * ssh` has never dialed — returns undefined so the caller reports "Unknown
- * device" rather than dialing a literal.
+ * device" rather than dialing a literal. `token` may also be the `auto`
+ * affinity sentinel (RUSH-2185); `opts.resolveAuto` overrides the pick (tests).
  */
-export declare function resolveDeviceTarget(token: string): Promise<DeviceProfile | undefined>;
+export declare function resolveDeviceTarget(token: string, opts?: Pick<MatchHostOptions, 'resolveAuto'>): Promise<DeviceProfile | undefined>;
 /**
  * Resolve an explicit `--host`/`--device` list to dialable targets. A token that
  * fails the injection guard or names nothing reachable is skipped with a stderr

package/dist/lib/devices/resolve-target.js

@@ -71,10 +71,11 @@ async function toResolvedTarget(token) {
  * `user@host` / IP / FQDN literal yields a synthesized key-auth profile. A bare
  * unregistered alias (no `@`/dot) — or an ssh_config-only alias, which `agents
  * ssh` has never dialed — returns undefined so the caller reports "Unknown
- * device" rather than dialing a literal.
+ * device" rather than dialing a literal. `token` may also be the `auto`
+ * affinity sentinel (RUSH-2185); `opts.resolveAuto` overrides the pick (tests).
  */
-export async function resolveDeviceTarget(token) {
-    const host = await matchHost(token, { allowBareLiteral: true });
+export async function resolveDeviceTarget(token, opts = {}) {
+    const host = await matchHost(token, { allowBareLiteral: true, ...opts });
     if (!host)
         return undefined;
     if (host.device) {

package/dist/lib/hosts/passthrough.js

@@ -24,6 +24,7 @@ import { dispatchAgentsCommand, withActorEnv } from './dispatch.js';
 import { stripRoutingFlags, buildRemoteAgentsInvocation, HOST_ROUTING_SPECS, } from './remote-cmd.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { machineId } from '../session/sync/config.js';
+import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
 import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
 import { fanOutDevices, planFleetTargets, runLocalCommand, runOnDevice, } from '../devices/fleet.js';
@@ -396,7 +397,7 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     const deviceFlag = flagValue(allArgs, 'device');
     const hostsFlag = flagValue(allArgs, 'hosts');
     const devicesFlag = flagValue(allArgs, 'devices');
-    const hostName = hostFlag ?? deviceFlag;
+    let hostName = hostFlag ?? deviceFlag;
     const fleetAll = isFleetAllSentinel(hostFlag, deviceFlag, hostsFlag, devicesFlag);
     // Proceed when any routing flag is present, including the plural fleet flags
     // that may carry the `all` sentinel.
@@ -460,6 +461,22 @@ export async function maybeRunOnHost(command, allArgs, opts) {
     // flags and bare flags were already handled.
     if (!hostName)
         return false;
+    // `auto` is the same affinity sentinel `agents run --device auto` resolves
+    // (RUSH-2185) — pick the concrete target up front via resolveDeviceAffinity so
+    // the isSelfHost check right below (which compares a literal name, not "auto")
+    // still catches a local pick and runs the command locally rather than
+    // resolving to a real Host and self-SSHing (or, if this box isn't itself a
+    // registered device, dialing a literal, nonexistent host named "auto").
+    if (isDeviceAuto(hostName)) {
+        const plan = resolveDeviceAffinity({});
+        if (!plan.host) {
+            const stripped = stripRoutingFlags(allArgs, STRIP_SPECS);
+            process.argv = [process.argv[0], process.argv[1], ...stripped];
+            return false;
+        }
+        process.stderr.write(chalk.gray(`[agents] device=auto → ${plan.host}\n`));
+        hostName = plan.host;
+    }
     // Running against your own machine is just a local run — skip the SSH round-trip.
     // Match EVERY identity the box answers to (short id, loopback, tailscale
     // dnsName), not just machineId() — a `--host <self-dnsName>` used to slip past a

package/dist/lib/hosts/registry.d.ts

@@ -19,6 +19,7 @@
 import type { Host, HostProvider, HostProviderId } from './types.js';
 import { DeviceOffloadUnsupportedError } from './types.js';
 import { type DeviceProfile } from '../devices/registry.js';
+import { type DeviceAffinityPlan } from '../smart-launch.js';
 export { DeviceOffloadUnsupportedError };
 export declare function getProvider(id: HostProviderId): HostProvider;
 export declare function getAllProviders(): HostProvider[];
@@ -52,6 +53,9 @@ export interface MatchHostOptions {
      * "Unknown device" verdict reachable).
      */
     allowBareLiteral?: boolean;
+    /** Override the affinity pick for the `auto` sentinel (tests). Defaults to
+     * `resolveDeviceAffinity({})` — the same engine `agents run --device auto` uses. */
+    resolveAuto?: () => DeviceAffinityPlan;
 }
 /**
  * The one place a `--host` / `--device` token becomes a resolved host. Reads the

package/dist/lib/hosts/registry.js

@@ -25,6 +25,8 @@ import { readMeta } from '../state.js';
 import { isSshConfigHost } from './ssh-config.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { loadDevices, isControlDevice } from '../devices/registry.js';
+import { isDeviceAuto, resolveDeviceAffinity } from '../smart-launch.js';
+import { localMachineId } from '../session/origin-machine.js';
 // Re-export so existing importers (tests, commands) keep their path; the class
 // itself lives in types.ts so providers can throw it without a circular import.
 export { DeviceOffloadUnsupportedError };
@@ -146,6 +148,20 @@ function literalHost(token, host, user) {
  * into a dispatch verdict.
  */
 export async function matchHost(name, opts = {}) {
+    // `auto` is the same affinity sentinel `agents run --device auto` resolves
+    // (isDeviceAuto / resolveDeviceAffinity in ../smart-launch.js) — shared here so
+    // every caller through this one core (ssh, teams, dispatch/passthrough) picks a
+    // device the SAME way `run` does instead of rejecting it as "Unknown device
+    // 'auto'" (RUSH-2185). A `null` plan.host means the affinity engine picked this
+    // very machine; resolve that as the local device/host entry (if any) rather than
+    // returning nothing — callers that already special-case "target is this
+    // machine" (teams add/create, the passthrough self-host check) then treat it as
+    // local exactly as they would if the user had typed the local name.
+    if (isDeviceAuto(name)) {
+        const plan = (opts.resolveAuto ?? (() => resolveDeviceAffinity({})))();
+        const picked = plan.host ?? normalizeHost(localMachineId());
+        return matchHost(picked, opts);
+    }
     try {
         assertValidSshTarget(name);
     }

package/dist/lib/hosts/remote-cmd.js

@@ -113,6 +113,7 @@ export const RUN_OPTION_FORWARDING = {
     lease: 'local-only',
     box: 'local-only',
     keepBox: 'local-only',
+    fresh: 'local-only', // skips the warm-pool reuse for --lease; the lease path is always local
     reuse: 'local-only', // reuse-picker choice for --lease; the lease path is always local
     bare: 'local-only', // skips the local setup-copy push; lease-only concern
     tailscale: 'local-only', // --tailscale/--no-tailscale gate the lease net mode; never forwarded

package/dist/lib/observe-aliases.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Observe-umbrella aliases (Phase 3 surface consolidation).
+ *
+ * Thin name → real command expansion. No store merge — feed / sessions / events
+ * remain the stores; these are doors that point at the right reader.
+ *
+ *   inbox    → feed                  (needs-you default)
+ *   timeline → feed --filter updates (agent progress stream)
+ *   roster   → sessions --active     (live agent roster)
+ *
+ * `audit` is NOT an alias here — `agents audit` is already the tamper-evident
+ * run-dispatch log. Ops trail = `agents events` (optionally `--audit`).
+ */
+export type ObserveAlias = 'inbox' | 'timeline' | 'roster';
+export declare const OBSERVE_ALIASES: readonly ObserveAlias[];
+export interface ObserveExpandResult {
+    /** argv for the real command (no program name): e.g. ['feed', '--filter', 'updates'] */
+    argv: string[];
+    /** One-line note for stderr (optional); empty when silent. */
+    note: string;
+}
+/** True when `rest` already carries a `--filter` / `--filter=…` flag. */
+export declare function hasFilterFlag(rest: readonly string[]): boolean;
+/** True when `rest` already carries `--active`. */
+export declare function hasActiveFlag(rest: readonly string[]): boolean;
+/**
+ * Expand an observe alias + remaining user args into the real command argv.
+ * Returns null when `alias` is not an observe alias.
+ */
+export declare function expandObserveAlias(alias: string, rest?: readonly string[]): ObserveExpandResult | null;

package/dist/lib/observe-aliases.js

@@ -0,0 +1,56 @@
+/**
+ * Observe-umbrella aliases (Phase 3 surface consolidation).
+ *
+ * Thin name → real command expansion. No store merge — feed / sessions / events
+ * remain the stores; these are doors that point at the right reader.
+ *
+ *   inbox    → feed                  (needs-you default)
+ *   timeline → feed --filter updates (agent progress stream)
+ *   roster   → sessions --active     (live agent roster)
+ *
+ * `audit` is NOT an alias here — `agents audit` is already the tamper-evident
+ * run-dispatch log. Ops trail = `agents events` (optionally `--audit`).
+ */
+export const OBSERVE_ALIASES = ['inbox', 'timeline', 'roster'];
+/** True when `rest` already carries a `--filter` / `--filter=…` flag. */
+export function hasFilterFlag(rest) {
+    return rest.some((a) => a === '--filter' || a.startsWith('--filter='));
+}
+/** True when `rest` already carries `--active`. */
+export function hasActiveFlag(rest) {
+    return rest.some((a) => a === '--active');
+}
+/**
+ * Expand an observe alias + remaining user args into the real command argv.
+ * Returns null when `alias` is not an observe alias.
+ */
+export function expandObserveAlias(alias, rest = []) {
+    const tail = [...rest];
+    switch (alias) {
+        case 'inbox':
+            return {
+                argv: ['feed', ...tail],
+                note: 'agents inbox → agents feed (needs-you inbox)',
+            };
+        case 'timeline': {
+            const argv = hasFilterFlag(tail)
+                ? ['feed', ...tail]
+                : ['feed', '--filter', 'updates', ...tail];
+            return {
+                argv,
+                note: 'agents timeline → agents feed --filter updates',
+            };
+        }
+        case 'roster': {
+            const argv = hasActiveFlag(tail)
+                ? ['sessions', ...tail]
+                : ['sessions', '--active', ...tail];
+            return {
+                argv,
+                note: 'agents roster → agents sessions --active',
+            };
+        }
+        default:
+            return null;
+    }
+}

package/dist/lib/plugins.d.ts

@@ -2,11 +2,12 @@
  * Plugin discovery, validation, and syncing.
  *
  * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks,
- * commands, agents, bin scripts, MCP servers, and settings under a single
- * manifest (plugin.json). They are user-authored resources, sitting alongside
- * skills/, commands/, hooks/, etc. — git-tracked as source of truth. This
- * module discovers plugins, validates their manifests, and syncs their
- * contents into agent version homes.
+ * commands, agents, workflows, bin scripts, MCP servers, and settings under a
+ * single manifest (plugin.json). They are user-authored resources, sitting
+ * alongside skills/, commands/, hooks/, etc. — git-tracked as source of truth.
+ * This module discovers plugins, validates their manifests, and syncs their
+ * contents into agent version homes. Workflows under a plugin’s workflows/
+ * are resolved at run time by resolveWorkflowRef (Phase 5 packaging).
  */
 import type { AgentId, DiscoveredPlugin, PluginManifest, MarketplaceSpec } from './types.js';
 export interface PluginCapabilities {
@@ -95,6 +96,14 @@ export declare function discoverPluginHooks(pluginRoot: string): string[];
 export declare function discoverPluginCommands(pluginRoot: string): string[];
 /** Discover agent definition .md files inside a plugin's agents/ directory. */
 export declare function discoverPluginAgentDefs(pluginRoot: string): string[];
+/**
+ * Discover workflow directories inside a plugin's `workflows/` folder.
+ * A valid workflow is a directory containing WORKFLOW.md (same contract as
+ * project/user/system workflows). Phase 5: plugins package workflows as
+ * entrypoints so `agents run <name>` can resolve them without a separate
+ * install into ~/.agents/workflows/.
+ */
+export declare function discoverPluginWorkflows(pluginRoot: string): string[];
 /** Discover executable files in a plugin's bin/ directory. */
 export declare function discoverPluginBin(pluginRoot: string): string[];
 /** Discover MCP server names from .mcp.json at the plugin root. */

package/dist/lib/plugins.js

@@ -2,11 +2,12 @@
  * Plugin discovery, validation, and syncing.
  *
  * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks,
- * commands, agents, bin scripts, MCP servers, and settings under a single
- * manifest (plugin.json). They are user-authored resources, sitting alongside
- * skills/, commands/, hooks/, etc. — git-tracked as source of truth. This
- * module discovers plugins, validates their manifests, and syncs their
- * contents into agent version homes.
+ * commands, agents, workflows, bin scripts, MCP servers, and settings under a
+ * single manifest (plugin.json). They are user-authored resources, sitting
+ * alongside skills/, commands/, hooks/, etc. — git-tracked as source of truth.
+ * This module discovers plugins, validates their manifests, and syncs their
+ * contents into agent version homes. Workflows under a plugin’s workflows/
+ * are resolved at run time by resolveWorkflowRef (Phase 5 packaging).
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -107,6 +108,7 @@ export function buildDiscoveredPlugin(pluginRoot, manifest, spec = { kind: 'user
         scripts: discoverPluginScripts(pluginRoot),
         commands: discoverPluginCommands(pluginRoot),
         agentDefs: discoverPluginAgentDefs(pluginRoot),
+        workflows: discoverPluginWorkflows(pluginRoot),
         memory: discoverPluginMemory(pluginRoot),
         bin: discoverPluginBin(pluginRoot),
         mcpServers: discoverPluginMcpServers(pluginRoot),
@@ -131,6 +133,7 @@ export function pluginResourceGroups(plugin) {
         { label: 'skills', items: plugin.skills.map((s) => `/${plugin.name}:${s}`) },
         { label: 'commands', items: plugin.commands.map((c) => `/${plugin.name}:${c}`) },
         { label: 'subagents', items: plugin.agentDefs },
+        { label: 'workflows', items: plugin.workflows },
         { label: 'hooks', items: plugin.hooks },
         { label: 'memory', items: plugin.memory },
         { label: 'mcp', items: plugin.mcpServers },
@@ -334,6 +337,27 @@ export function discoverPluginAgentDefs(pluginRoot) {
         .filter(f => f.endsWith('.md') && !f.startsWith('.'))
         .map(f => f.slice(0, -3));
 }
+/**
+ * Discover workflow directories inside a plugin's `workflows/` folder.
+ * A valid workflow is a directory containing WORKFLOW.md (same contract as
+ * project/user/system workflows). Phase 5: plugins package workflows as
+ * entrypoints so `agents run <name>` can resolve them without a separate
+ * install into ~/.agents/workflows/.
+ */
+export function discoverPluginWorkflows(pluginRoot) {
+    const workflowsDir = path.join(pluginRoot, 'workflows');
+    if (!fs.existsSync(workflowsDir))
+        return [];
+    try {
+        return fs.readdirSync(workflowsDir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && !e.name.startsWith('.') &&
+            fs.existsSync(path.join(workflowsDir, e.name, 'WORKFLOW.md')))
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
 /** Discover executable files in a plugin's bin/ directory. */
 export function discoverPluginBin(pluginRoot) {
     const binDir = path.join(pluginRoot, 'bin');

package/dist/lib/redact.js

@@ -2,6 +2,10 @@
  * Shared redaction helpers for text that may be exported or logged.
  */
 const SECRET_PATTERNS = [
+    // Local home paths identify operators and disclose internal filesystem layout.
+    // Keep the useful path suffix while masking the machine-specific home prefix.
+    [/(^|[\s,"'`(=:])\/(?:home|Users)\/[^/\s,"'`]+/g, '$1[HOME]'],
+    [/(^|[\s,"'`(=])[A-Z]:\\Users\\[^\\\s,"'`]+/gi, '$1[HOME]'],
     [/\bAKIA[0-9A-Z]{16}\b/g, '[REDACTED_AWS_KEY]'],
     // GitHub: classic PATs (ghp_), OAuth (gho_), app/refresh/server tokens
     // (ghs_/ghr_), and fine-grained PATs (github_pat_). All share the 36-char

package/dist/lib/resources/types.d.ts

@@ -6,7 +6,8 @@
  * - Override on name conflict: Higher layer wins (project > user > system)
  */
 export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid' | 'hermes' | 'pi';
-export type Layer = 'system' | 'user' | 'project';
+/** Resource origin. Precedence (highest first): project > user > plugin > system. */
+export type Layer = 'system' | 'user' | 'project' | 'plugin';
 export type ResourceKind = 'command' | 'hook' | 'skill' | 'rule' | 'mcp' | 'permission' | 'subagent' | 'workflow' | 'memory';
 /** A resolved resource with its origin layer. */
 export interface ResolvedItem<T> {

package/dist/lib/resources/workflows.d.ts

@@ -3,7 +3,7 @@
  *
  * Workflows are directory bundles with a WORKFLOW.md containing YAML frontmatter.
  * They optionally contain subagents/, skills/, and plugins/ subdirectories.
- * Resolution order: project > user > system.
+ * Resolution order (docs/07-entrypoints): project > user > plugin > extra > system.
  */
 import type { AgentId, ResolvedItem, ResourceHandler } from './types.js';
 export interface WorkflowItem {