@phnx-labs/agents-cli 1.20.88 → 1.20.90

package/dist/commands/factory.js

@@ -6,6 +6,7 @@ import { homedir } from 'os';
 import { betaEnableHint, isBetaEnabled } from '../lib/beta.js';
 import { insertTask } from '../lib/cloud/store.js';
 import { emit } from '../lib/events.js';
+import { buildFactorySnapshot } from '../lib/factory/snapshot.js';
 function requireFactoryUrl() {
     const url = process.env.FACTORY_FLOOR_URL;
     if (!url) {
@@ -51,14 +52,28 @@ export function registerFactoryCommands(program) {
 Examples:
   agents factory submit PROJ-123
   agents factory submit https://linear.app/example/issue/PROJ-123
+  agents factory snapshot --json
 `);
-    factory.hook('preAction', () => {
-        if (enabled)
+    factory.hook('preAction', (_thisCommand, actionCommand) => {
+        // Foreman must be able to read its tick input before any beta-gated action.
+        if (enabled || actionCommand.name() === 'snapshot')
             return;
         console.error(chalk.red('agents factory is in beta.'));
         console.error(chalk.gray(betaEnableHint('factory')));
         process.exit(1);
     });
+    factory
+        .command('snapshot')
+        .description('Read the complete Software Factory state without dispatching or changing it.')
+        .option('--json', 'Output the stable machine-readable snapshot')
+        .action(async (opts) => {
+        const snapshot = await buildFactorySnapshot();
+        if (opts.json) {
+            console.log(JSON.stringify(snapshot, null, 2));
+            return;
+        }
+        renderSnapshot(snapshot);
+    });
     factory
         .command('submit <linear-ref>')
         .description('Submit a Linear issue (PROJ-123 or URL) to the Software Factory.')
@@ -93,3 +108,12 @@ Examples:
         console.log(`  tail output  agents cloud logs ${result.cloud_execution_id}`);
     });
 }
+function renderSnapshot(snapshot) {
+    console.log(chalk.bold(`Factory snapshot ${snapshot.generatedAt}`));
+    console.log(`  sessions     ${snapshot.sessions.length}`);
+    console.log(`  open PRs     ${snapshot.prs.length}`);
+    console.log(`  devices      ${snapshot.devices.length}`);
+    for (const [project, queue] of Object.entries(snapshot.queues)) {
+        console.log(`  ${project.padEnd(12)} todo ${queue.todo} · in progress ${queue.inProgress} · blocked ${queue.blocked}`);
+    }
+}

package/dist/commands/funnel.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-import { buildFunnelStatusCommand, buildFunnelUpCommand, parseFunnelPort } from '../lib/funnel.js';
+import { buildFunnelDownCommand, buildFunnelStatusCommand, buildFunnelUpCommand, parseFunnelPort } from '../lib/funnel.js';
 import { resolveHost } from '../lib/hosts/registry.js';
 import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
@@ -59,4 +59,19 @@ export function registerFunnelCommand(program) {
             process.exit(1);
         }
     });
+    funnel
+        .command('down <host>')
+        .description('Disable Tailscale Funnel exposure for a public HTTPS port.')
+        .option('--port <n>', 'Public Funnel port: 443, 8443, or 10000', '443')
+        .action(async (host, opts) => {
+        try {
+            const publicPort = parseFunnelPort(opts.port ?? '443');
+            await runOnHost(host, buildFunnelDownCommand(publicPort));
+            console.log(chalk.green(`Funnel disabled on ${host}: public :${publicPort}`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
 }

package/dist/commands/harness.d.ts

@@ -11,4 +11,31 @@
  * native harness registry. The `agents profiles` tree stays unchanged.
  */
 import type { Command } from 'commander';
+import { type Profile } from '../lib/profiles.js';
+/**
+ * Print one custom harness. Shared by `agents harness view <name>` and by
+ * `agents view <name>` — a custom harness resolves as an agent type there, so
+ * both entry points must describe it identically.
+ */
+export declare function renderHarnessDetail(name: string): void;
+/** Options accepted by `agents harness fork`. */
+export interface ForkOptions {
+    model?: string;
+    baseUrl?: string;
+    authProvider?: string;
+    version?: string;
+    label?: string;
+    description?: string;
+    keyStdin?: boolean;
+    force?: boolean;
+}
+/**
+ * Build the new harness for `agents harness fork <source> <name>`.
+ *
+ * Two sources, one verb: an existing custom harness is copied and overridden;
+ * a native agent id is turned into a harness pinned to `--model` on that host.
+ * Forking a native harness therefore requires `--model` — there is nothing to
+ * copy a model from.
+ */
+export declare function buildFork(source: string, name: string, opts: ForkOptions): Profile;
 export declare function registerHarnessCommands(program: Command): void;

package/dist/commands/harness.js

@@ -11,15 +11,82 @@
  * native harness registry. The `agents profiles` tree stays unchanged.
  */
 import chalk from 'chalk';
-import { addProfile } from './profiles.js';
-import { listProfiles, readProfile, deleteProfile, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, getProfilePath, } from '../lib/profiles.js';
+import { addProfile, ensureProviderToken } from './profiles.js';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileHostLabel, profileProviderLabel, profileModelLabel, profileAuthLabel, profileLabel, forkProfile, profileFromHostModel, authEnvKeyForHost, getProfilePath, validateProfileName, } from '../lib/profiles.js';
 import { listPresets } from '../lib/profiles-presets.js';
-import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName } from '../lib/agents.js';
 /** Short capability summary for a native harness — its supported run modes. */
 function nativeModes(id) {
     const modes = AGENTS[id]?.capabilities?.modes ?? [];
     return modes.length ? modes.join('/') : '-';
 }
+/**
+ * Print one custom harness. Shared by `agents harness view <name>` and by
+ * `agents view <name>` — a custom harness resolves as an agent type there, so
+ * both entry points must describe it identically.
+ */
+export function renderHarnessDetail(name) {
+    const p = readProfile(name);
+    console.log(chalk.bold(profileLabel(p)) + chalk.gray('  (custom harness)'));
+    if (p.description)
+        console.log(chalk.gray(p.description));
+    console.log('');
+    console.log(`Host:     ${profileHostLabel(p)}`);
+    console.log(`Model:    ${profileModelLabel(p)}`);
+    if (p.fallback_model)
+        console.log(`Fallback: ${p.fallback_model}`);
+    console.log(`Provider: ${profileProviderLabel(p)}`);
+    console.log(`Auth:     ${profileAuthLabel(p)}`);
+    if (p.forkedFrom)
+        console.log(`Forked:   from ${p.forkedFrom}`);
+    console.log(chalk.gray(getProfilePath(p.name)));
+    console.log('');
+    console.log(chalk.gray(`Run: agents run ${p.name} "hello"`));
+}
+/**
+ * Build the new harness for `agents harness fork <source> <name>`.
+ *
+ * Two sources, one verb: an existing custom harness is copied and overridden;
+ * a native agent id is turned into a harness pinned to `--model` on that host.
+ * Forking a native harness therefore requires `--model` — there is nothing to
+ * copy a model from.
+ */
+export function buildFork(source, name, opts) {
+    if (profileExists(source)) {
+        return forkProfile(readProfile(source), name, {
+            model: opts.model,
+            baseUrl: opts.baseUrl,
+            provider: opts.authProvider,
+            version: opts.version,
+            label: opts.label,
+            description: opts.description,
+        });
+    }
+    const host = resolveAgentName(source);
+    if (!host) {
+        throw new Error(`No harness or agent named '${source}'.\n` +
+            `Fork from a custom harness (agents harness list) or a native one: ${ALL_AGENT_IDS.join(', ')}.`);
+    }
+    if (!opts.model) {
+        throw new Error(`--model <id> is required when forking the native '${host}' harness (there is no model to inherit).`);
+    }
+    return profileFromHostModel(name, host, opts.model, {
+        version: opts.version,
+        baseUrl: opts.baseUrl,
+        provider: opts.authProvider,
+        authEnvVar: opts.authProvider ? authEnvKeyForHostOrThrow(host) : undefined,
+        label: opts.label,
+        description: opts.description ?? `Forked from ${host}: ${opts.model}`,
+    });
+}
+/** Auth env var for a host, as a hard error when the host declares none. */
+function authEnvKeyForHostOrThrow(host) {
+    const key = authEnvKeyForHost(host);
+    if (!key) {
+        throw new Error(`--auth-provider is set but host '${host}' has no known auth env var; it manages its own login.`);
+    }
+    return key;
+}
 export function registerHarnessCommands(program) {
     const cmd = program
         .command('harness')
@@ -30,11 +97,18 @@ A custom harness pins a host CLI (opencode, claude, codex, grok, antigravity, ..
 model and gives it a name. 'agents run <name>' then behaves like a native agent
 type, and 'agents repo push user' syncs it to every device.
 
+A custom harness is its own agent type in 'agents view' — its own block beside Claude
+and Codex, not a row indented under the host CLI that executes it.
+
 Examples:
   # Meta Muse Spark 1.1 through OpenCode, called 'spark'
   agents harness add spark --host opencode --model meta/muse-spark-1.1
   agents run spark "refactor api/handlers/checkout.py"
 
+  # Fork a native harness, or copy one of your own and swap the model
+  agents harness fork opencode deepseek --model deepseek/deepseek-v4-flash-0731 --auth-provider openrouter
+  agents harness fork deepseek deepseek-chat --model deepseek/deepseek-chat-v3
+
   # Per-run model override still wins
   agents run spark --model opencode/big-pickle "quick pass"
 
@@ -66,6 +140,48 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('fork <source> <name>')
+        .description('Fork a native harness (claude, opencode, ...) or an existing custom one into a new named harness.')
+        .option('--model <id>', 'Model to pin on the fork (required when forking a native harness)')
+        .option('--base-url <url>', 'Custom endpoint base URL (claude/codex hosts)')
+        .option('--auth-provider <provider>', 'Attach a keychain-backed API key under this provider')
+        .option('--version <version>', 'Pin the host CLI version (e.g., 1.16.0)')
+        .option('--label <text>', 'Human-facing name shown by `agents view` (defaults to <name>)')
+        .option('--description <text>', 'One-line description')
+        .option('--key-stdin', 'Read the API key from stdin instead of prompting (for scripts/CI)')
+        .option('--force', 'Overwrite an existing harness with the same name')
+        .addHelpText('after', `
+Examples:
+  # Fork OpenCode into a harness pinned to a DeepSeek model on OpenRouter
+  agents harness fork opencode deepseek --model deepseek/deepseek-v4-flash-0731 --auth-provider openrouter
+
+  # Fork Claude Code onto a private gateway
+  agents harness fork claude corp --model gpt-x --base-url https://gw.corp/v1 --auth-provider corp
+
+  # Copy an existing harness and swap only the model
+  agents harness fork deepseek deepseek-chat --model deepseek/deepseek-chat-v3
+`)
+        .action(async (source, name, opts) => {
+        try {
+            validateProfileName(name);
+            if (profileExists(name) && !opts.force) {
+                throw new Error(`Harness '${name}' already exists. Use --force to overwrite.`);
+            }
+            // Build first so a bad source/flag combination fails before prompting
+            // for a key the user would then have stored for nothing.
+            const forked = buildFork(source, name, opts);
+            if (opts.authProvider)
+                await ensureProviderToken(opts.authProvider, undefined, opts.keyStdin);
+            writeProfile(forked);
+            console.log(chalk.green(`Harness '${name}' forked from ${source}.`));
+            console.log(chalk.gray(`Try: agents run ${name} "hello"`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
     cmd
         .command('list')
         .alias('ls')
@@ -114,16 +230,7 @@ Examples:
         .description('Show one custom harness (host, model, provider, auth, path).')
         .action((name) => {
         try {
-            const p = readProfile(name);
-            console.log(chalk.bold(p.name));
-            if (p.description)
-                console.log(chalk.gray(p.description));
-            console.log('');
-            console.log(`Host:     ${profileHostLabel(p)}`);
-            console.log(`Model:    ${profileModelLabel(p)}`);
-            console.log(`Provider: ${profileProviderLabel(p)}`);
-            console.log(`Auth:     ${profileAuthLabel(p)}`);
-            console.log(chalk.gray(getProfilePath(p.name)));
+            renderHarnessDetail(name);
         }
         catch (err) {
             console.error(chalk.red(err.message));

package/dist/commands/menubar.js

@@ -7,7 +7,8 @@
  * user; these commands are the manual override.
  */
 import chalk from 'chalk';
-import { enableMenubarService, disableMenubarService, getMenubarStatus, } from '../lib/menubar/install-menubar.js';
+import { setHelpSections } from '../lib/help.js';
+import { enableMenubarService, disableMenubarService, getMenubarStatus, runMenubarSetup, } from '../lib/menubar/install-menubar.js';
 function notMac() {
     if (process.platform !== 'darwin') {
         console.log(chalk.yellow('The menu bar helper is macOS only.'));
@@ -15,10 +16,122 @@ function notMac() {
     }
     return false;
 }
+/** Shared status readout — `status`, bare `menubar`, and `setup --check` all end here. */
+function printStatus(s, opts = {}) {
+    const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
+    console.log(chalk.bold('Menu bar helper\n'));
+    console.log(`  running            ${yn(s.running)}`);
+    console.log(`  service installed  ${yn(s.serviceInstalled)}`);
+    if (opts.brief) {
+        console.log(chalk.gray('\n  setup | enable | disable | status'));
+        return;
+    }
+    console.log(`  app installed      ${s.installedApp ? chalk.gray(s.installedApp) : chalk.gray('no')}`);
+    console.log(`  installed version  ${s.installedVersion ? chalk.gray(s.installedVersion) : chalk.gray('unknown')}`);
+    console.log(`  current version    ${chalk.gray(s.currentVersion)}`);
+    console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
+    console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
+    // Two copies of the INSTALLED bundle is the duplicate the user sees as two
+    // agents marks in the menu bar. It used to read as a healthy `running: yes`.
+    if (s.instances.length > 1) {
+        console.log(chalk.yellow(`\n  ${s.instances.length} copies of the installed helper are running — that is the duplicate menu-bar icon:`));
+        for (const p of s.instances)
+            console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
+        console.log(chalk.gray('  Fix it with `agents menubar setup`.'));
+    }
+    if (s.foreignInstances.length > 0) {
+        // RegisterEventHotKey is first-come, so the helper that registered the
+        // chord first owns Cmd-Shift-V/O. A process list cannot say which that
+        // was — only that a rival exists — so report the conflict, not a winner.
+        // The loser has no other symptom: its chords simply never fire.
+        const n = s.foreignInstances.length;
+        console.log(chalk.yellow(`\n  ${n} other helper process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
+        for (const p of s.foreignInstances)
+            console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
+        console.log(chalk.gray('  End them with `agents menubar setup`.'));
+    }
+    if (s.stale) {
+        console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar setup` now.'));
+    }
+    else if (!s.serviceInstalled && !s.disabledByUser) {
+        console.log(chalk.gray('\n  Set it up with `agents menubar setup`.'));
+    }
+}
+function printSetupResult(r) {
+    console.log(chalk.bold('Menu bar setup\n'));
+    for (const step of r.steps) {
+        const mark = step.outcome === 'failed' ? chalk.red('✗')
+            : step.outcome === 'changed' ? chalk.green('+') : chalk.green('✓');
+        console.log(`  ${mark} ${step.name.padEnd(15)} ${chalk.gray(step.detail)}`);
+    }
+    console.log();
+    if (r.configured) {
+        console.log(chalk.green('Menu bar configured.') + chalk.gray('  One agents mark, started at login.'));
+    }
+    else {
+        console.log(chalk.red('Menu bar not fully configured.') + chalk.gray('  See the failed step above.'));
+    }
+}
 export function registerMenubarCommands(program) {
     const menubar = program
         .command('menubar')
         .description('Manage the macOS menu-bar helper (running sessions, agents awaiting input, routines)');
+    // `setup` is the one command that gets a machine to the intended state:
+    // exactly one status item, started at login. `enable` stays the narrow
+    // install+start; setup adds duplicate cleanup and verifies the end state.
+    const setup = menubar
+        .command('setup')
+        .description('Configure the menu bar end-to-end: one instance, started at login')
+        .option('--check', 'Report the current state, change nothing')
+        .option('--json', 'Emit machine-readable JSON')
+        .action((options) => {
+        if (options.check) {
+            const s = getMenubarStatus();
+            if (options.json) {
+                process.stdout.write(JSON.stringify(s) + '\n');
+                return;
+            }
+            if (notMac())
+                return;
+            printStatus(s);
+            return;
+        }
+        if (!options.json && notMac())
+            return;
+        const r = runMenubarSetup();
+        if (options.json) {
+            process.stdout.write(JSON.stringify(r) + '\n');
+        }
+        else {
+            printSetupResult(r);
+        }
+        if (!r.configured)
+            process.exitCode = 1;
+    });
+    setHelpSections(setup, {
+        examples: `
+      # Configure the menu bar end-to-end (idempotent — safe to re-run)
+      agents menubar setup
+
+      # Two agents marks in the menu bar? This ends the duplicate.
+      agents menubar setup
+
+      # See the current state without changing anything
+      agents menubar setup --check
+    `,
+        notes: `
+      Configures, in order: every running helper ended, the helper bundle at
+      ~/Library/Application Support/agents-cli, its code signature, the launchd
+      login item (com.phnx-labs.agents-menubar — RunAtLoad + KeepAlive), then
+      verifies exactly one helper came back up.
+
+      Every running helper is ended and launchd restarts one, so the survivor is
+      always the login-managed copy. Exits nonzero if it cannot reach that state.
+
+      Setup clears a previous \`agents menubar disable\`. To turn the menu bar off
+      again, run \`agents menubar disable\`.
+    `,
+    });
     menubar
         .command('enable')
         .description('Install and start the menu-bar helper (launches at login)')
@@ -40,7 +153,7 @@ export function registerMenubarCommands(program) {
         if (notMac())
             return;
         disableMenubarService();
-        console.log(chalk.green('Menu bar helper disabled.') + chalk.gray('  Re-enable any time with `agents menubar enable`.'));
+        console.log(chalk.green('Menu bar helper disabled.') + chalk.gray('  Re-enable any time with `agents menubar setup`.'));
     });
     menubar
         .command('status')
@@ -56,33 +169,7 @@ export function registerMenubarCommands(program) {
             console.log(chalk.yellow('The menu bar helper is macOS only.'));
             return;
         }
-        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
-        console.log(chalk.bold('Menu bar helper\n'));
-        console.log(`  running            ${yn(s.running)}`);
-        console.log(`  service installed  ${yn(s.serviceInstalled)}`);
-        console.log(`  app installed      ${s.installedApp ? chalk.gray(s.installedApp) : chalk.gray('no')}`);
-        console.log(`  installed version  ${s.installedVersion ? chalk.gray(s.installedVersion) : chalk.gray('unknown')}`);
-        console.log(`  current version    ${chalk.gray(s.currentVersion)}`);
-        console.log(`  bundle source      ${s.source ? chalk.gray(s.source) : chalk.red('missing (cannot enable)')}`);
-        console.log(`  disabled by user   ${yn(s.disabledByUser)}`);
-        if (s.foreignInstances.length > 0) {
-            // RegisterEventHotKey is first-come, so the helper that registered the
-            // chord first owns Cmd-Shift-V/O. A process list cannot say which that
-            // was — only that a rival exists — so report the conflict, not a
-            // winner. The loser
-            // has no other symptom: its chords simply never fire.
-            const n = s.foreignInstances.length;
-            console.log(chalk.yellow(`\n  ${n} other helper process${n === 1 ? '' : 'es'} running — ${n === 1 ? 'it' : 'they'} may hold Cmd-Shift-V/O instead of the installed one:`));
-            for (const p of s.foreignInstances)
-                console.log(chalk.gray(`    ${p.pid}  ${p.executable}`));
-            console.log(chalk.gray('  End it, then `agents menubar enable` to restart the installed helper.'));
-        }
-        if (s.stale) {
-            console.log(chalk.yellow('\n  Installed helper is stale — runs on next `agents` startup, or `agents menubar enable` now.'));
-        }
-        else if (!s.serviceInstalled && !s.disabledByUser) {
-            console.log(chalk.gray('\n  Enable it with `agents menubar enable`.'));
-        }
+        printStatus(s);
     });
     // Bare `agents menubar` -> status.
     menubar.action(() => {
@@ -91,10 +178,6 @@ export function registerMenubarCommands(program) {
             console.log(chalk.yellow('The menu bar helper is macOS only.'));
             return;
         }
-        const yn = (b) => (b ? chalk.green('yes') : chalk.gray('no'));
-        console.log(chalk.bold('Menu bar helper\n'));
-        console.log(`  running            ${yn(s.running)}`);
-        console.log(`  service installed  ${yn(s.serviceInstalled)}`);
-        console.log(chalk.gray('\n  enable | disable | status'));
+        printStatus(s, { brief: true });
     });
 }

package/dist/commands/profiles.d.ts

@@ -15,6 +15,9 @@ import { type Preset } from '../lib/profiles-presets.js';
  * without mocking @inquirer/prompts.
  */
 export declare function buildProfileFromCollection(name: string, preset: Preset, collected: Record<string, string>, version?: string): Profile;
+/** Read all available data from stdin synchronously, trimmed. */
+/** Ensure a provider API key exists in keychain, prompting or reading stdin if missing. */
+export declare function ensureProviderToken(provider: string, signupUrl?: string, fromStdin?: boolean): Promise<void>;
 /** Options accepted by {@link addProfile} — shared by `agents profiles add` and `agents harness add`. */
 export interface AddProfileOptions {
     preset?: string;

package/dist/commands/profiles.js

@@ -47,7 +47,7 @@ async function promptForSecret(message) {
 }
 /** Read all available data from stdin synchronously, trimmed. */
 /** Ensure a provider API key exists in keychain, prompting or reading stdin if missing. */
-async function ensureProviderToken(provider, signupUrl, fromStdin) {
+export async function ensureProviderToken(provider, signupUrl, fromStdin) {
     const item = keychainItemName(provider);
     if (hasKeychainToken(item)) {
         return;

package/dist/commands/routines.d.ts

@@ -14,10 +14,29 @@ import type { DeviceRegistry } from '../lib/devices/registry.js';
  * callers drop it straight into a status line.
  */
 export declare function formatRunDuration(startedAt: string, completedAt: string | null): string;
+/**
+ * The last run THIS device can speak for.
+ *
+ * A run record is written by whichever daemon fired the routine, into that
+ * machine's own runs dir — records carry no device attribution, so a record
+ * found here only ever describes this device's history. When a routine is
+ * pinned away from this machine (`devices:` excludes it) any local record is a
+ * leftover from before the pin, and reporting it as the routine's status paints
+ * another device's healthy routine red. Report nothing instead; the local
+ * history stays readable via `agents routines runs <name>`, and the owning
+ * device's status via `agents routines list --device <name>`.
+ */
+export declare function localLatestRun(job: JobConfig): RunMeta | null;
 export interface RoutineListGroup {
     key: string;
     title: string;
     jobs: JobConfig[];
+    /**
+     * Whether this device's run records describe the group. False for a
+     * `Device: <peer>` group — the rows are the same routine seen from a machine
+     * that does not fire it there, so Last Status is not ours to report.
+     */
+    local: boolean;
 }
 export declare function groupRoutineJobsByDevice(jobs: JobConfig[], registry: DeviceRegistry, self?: string): RoutineListGroup[];
 export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];

package/dist/commands/routines.js

@@ -70,6 +70,8 @@ function fireConditionLabel(job) {
             job.trigger.action ? `action=${job.trigger.action}` : null,
             job.trigger.teamKey ? `team=${job.trigger.teamKey}` : null,
             job.trigger.label ? `label=${job.trigger.label}` : null,
+            job.trigger.stateTo ? `stateTo=${job.trigger.stateTo}` : null,
+            job.trigger.stateFrom ? `stateFrom=${job.trigger.stateFrom}` : null,
         ].filter(Boolean).join(', ');
         return `on linear:${job.trigger.event}${filters ? ` (${filters})` : ''}`;
     }
@@ -136,6 +138,21 @@ function deviceLabel(job, width) {
         : raw;
     return { raw, display, dim: full.length === 0 || !jobRunsOnThisDevice(job) };
 }
+/**
+ * The last run THIS device can speak for.
+ *
+ * A run record is written by whichever daemon fired the routine, into that
+ * machine's own runs dir — records carry no device attribution, so a record
+ * found here only ever describes this device's history. When a routine is
+ * pinned away from this machine (`devices:` excludes it) any local record is a
+ * leftover from before the pin, and reporting it as the routine's status paints
+ * another device's healthy routine red. Report nothing instead; the local
+ * history stays readable via `agents routines runs <name>`, and the owning
+ * device's status via `agents routines list --device <name>`.
+ */
+export function localLatestRun(job) {
+    return jobRunsOnThisDevice(job) ? getLatestRun(job.name) : null;
+}
 export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
     const groups = new Map();
     const add = (key, title, job) => {
@@ -144,7 +161,9 @@ export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
             existing.jobs.push(job);
             return;
         }
-        groups.set(key, { key, title, jobs: [job] });
+        // `device:` is the only group that describes a machine other than this one,
+        // so it is the only one whose rows this device cannot report a status for.
+        groups.set(key, { key, title, jobs: [job], local: !key.startsWith('device:') });
     };
     for (const job of jobs) {
         const strategy = resolveHostStrategy(job);
@@ -191,7 +210,7 @@ export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
     };
     return [...groups.values()].sort((a, b) => order(a) - order(b) || a.title.localeCompare(b.title));
 }
-function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
+function renderRoutineRows({ jobs, scheduler, overdueSet, link, now, local = true }) {
     const NAME_W = 24;
     const AGENT_W = 10;
     const REPO_W = REPO_DISPLAY_MAX;
@@ -205,7 +224,7 @@ function renderRoutineRows({ jobs, scheduler, overdueSet, link, now }) {
     for (const job of jobs) {
         const nextStr = nextRunLabel(job, scheduler, now);
         const schedStr = scheduleLabel(job);
-        const latestRun = getLatestRun(job.name);
+        const latestRun = local ? localLatestRun(job) : null;
         const lastStatus = latestRun?.status || '-';
         const sourceRepo = job.source?.repo ?? job.repo;
         const sourceLabel = sourceRepo
@@ -261,6 +280,10 @@ function parseRoutineTrigger(options) {
             trigger.teamKey = options.teamKey;
         if (typeof options.label === 'string')
             trigger.label = options.label;
+        if (typeof options.stateTo === 'string')
+            trigger.stateTo = options.stateTo;
+        if (typeof options.stateFrom === 'string')
+            trigger.stateFrom = options.stateFrom;
         return trigger;
     }
     throw new Error('--on source must be github or linear');
@@ -503,7 +526,7 @@ export function registerRoutinesCommands(program) {
         if (options.json) {
             const nowJson = new Date();
             const payload = jobs.map((job) => {
-                const latestRun = getLatestRun(job.name);
+                const latestRun = localLatestRun(job);
                 return {
                     name: job.name,
                     agent: job.agent ?? null,
@@ -556,9 +579,14 @@ export function registerRoutinesCommands(program) {
             catch (err) {
                 console.error(chalk.yellow(`Could not read device registry: ${err.message}`));
             }
-            for (const group of groupRoutineJobsByDevice(jobs, registry)) {
+            const groups = groupRoutineJobsByDevice(jobs, registry);
+            for (const group of groups) {
                 console.log(chalk.bold(`\n${group.title}`));
-                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now });
+                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now, local: group.local });
+            }
+            if (groups.some((group) => !group.local)) {
+                console.log();
+                console.log(chalk.gray('  Last Status is per-device: rows under another device show "-" — read it there with: agents routines list --device <name>'));
             }
         }
         if (overdueSet.size > 0) {
@@ -591,6 +619,8 @@ export function registerRoutinesCommands(program) {
         .option('--action <name>', 'Webhook action filter for --on triggers (GitHub: labeled/opened; Linear: update)')
         .option('--team-key <key>', 'Linear team key filter for --on linear:<event> (e.g. RUSH)')
         .option('--label <name>', 'Label filter for --on triggers (GitHub label name or Linear issue label)')
+        .option('--state-to <name>', 'Linear current-state filter for --on linear:<event> (e.g. Plan)')
+        .option('--state-from <name>', 'Linear previous-state filter for --on linear:<event> (e.g. Triage)')
         .option('--end-at <iso>', 'Stop firing on or after this ISO 8601 timestamp (e.g., "2026-12-31T23:59:00Z"); routine auto-disables.')
         .option('--disabled', 'Create the routine but keep it paused (enable later with resume)')
         .option('--resume <sessionId>', 'At fire time, resume this existing session id (via `agents run <agent> --resume`) instead of starting fresh — the actual session reopens with full context and the prompt becomes its next turn. Powers self-scheduled wake-ups (e.g. /hibernate). Requires --agent claude or codex; runs un-sandboxed (the session store lives in the real home, not the job overlay).')
@@ -884,12 +914,26 @@ export function registerRoutinesCommands(program) {
     routinesCmd
         .command('edit [name]')
         .description('Open a routine in $EDITOR. Creates a new YAML template if the routine does not exist.')
-        .action(async (name) => {
+        .option('--state-to <name>', 'Update the Linear current-state filter before opening the editor')
+        .option('--state-from <name>', 'Update the Linear previous-state filter before opening the editor')
+        .action(async (name, options) => {
         if (!name) {
             name = await pickJob('Select job to edit', undefined, ['agents routines edit <name>']) ?? undefined;
             if (!name)
                 return;
         }
+        const existing = readJob(name);
+        if (existing && (options.stateTo !== undefined || options.stateFrom !== undefined)) {
+            if (!existing.trigger || existing.trigger.type !== 'linear_event') {
+                console.error(chalk.red(`'${name}' does not have a Linear trigger; --state-to/--state-from only apply to linear triggers`));
+                process.exit(1);
+            }
+            if (options.stateTo !== undefined)
+                existing.trigger.stateTo = options.stateTo || undefined;
+            if (options.stateFrom !== undefined)
+                existing.trigger.stateFrom = options.stateFrom || undefined;
+            writeJob(existing);
+        }
         const jobPath = getJobPath(name);
         if (!jobPath) {
             // Job doesn't exist - create a new one