@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/commands/routines.js

@@ -13,6 +13,7 @@ import * as yaml from 'yaml';
 import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemonPid, readDaemonLog, } from '../lib/daemon.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
 import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, getLatestRun, getRunDir, getJobPath, parseAtTime, } from '../lib/routines.js';
+import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
 import { IS_WINDOWS } from '../lib/platform/index.js';
 import { safeJoin } from '../lib/paths.js';
@@ -21,6 +22,21 @@ import { JobScheduler } from '../lib/scheduler.js';
 import { detectOverdueJobs } from '../lib/overdue.js';
 import { isInteractiveTerminal, requireInteractiveSelection } from './utils.js';
 import { setHelpSections } from '../lib/help.js';
+/**
+ * Human label for what fires a job: its cron schedule, or its event trigger
+ * for schedule-less (trigger-only) routines.
+ */
+function fireConditionLabel(job) {
+    if (job.schedule)
+        return humanizeCron(job.schedule, job.timezone);
+    if (job.trigger) {
+        const scope = job.trigger.repo
+            ? ` (${job.trigger.repo}${job.trigger.branch ? `@${job.trigger.branch}` : ''})`
+            : '';
+        return `on ${job.trigger.event}${scope}`;
+    }
+    return '-';
+}
 /** Start or reload the background scheduler so newly-added jobs fire on time. */
 function ensureSchedulerRunning() {
     if (isDaemonRunning()) {
@@ -73,7 +89,7 @@ async function pickJob(message, filter, alternatives = [], cwd) {
             message,
             choices: jobs.map((job) => ({
                 value: job.name,
-                name: `${job.name} ${chalk.gray(`(${job.workflow ? `wf:${job.workflow}` : job.agent}, ${job.schedule})`)}`,
+                name: `${job.name} ${chalk.gray(`(${job.workflow ? `wf:${job.workflow}` : job.agent}, ${job.schedule ?? fireConditionLabel(job)})`)}`,
             })),
         });
     }
@@ -159,8 +175,9 @@ export function registerRoutinesCommands(program) {
                     agent: job.agent ?? null,
                     workflow: job.workflow ?? null,
                     repo: job.repo ?? null,
-                    schedule: job.schedule,
-                    scheduleHuman: humanizeCron(job.schedule, job.timezone),
+                    schedule: job.schedule ?? null,
+                    scheduleHuman: fireConditionLabel(job),
+                    trigger: job.trigger ?? null,
                     timezone: job.timezone ?? null,
                     enabled: job.enabled,
                     overdue: overdueSet.has(job.name),
@@ -193,7 +210,7 @@ export function registerRoutinesCommands(program) {
         for (const job of jobs) {
             const nextRun = scheduler.getNextRun(job.name);
             const nextStr = humanizeNextRun(nextRun ?? null, now, job.timezone);
-            let schedStr = humanizeCron(job.schedule, job.timezone);
+            let schedStr = fireConditionLabel(job);
             if (job.endAt) {
                 const end = new Date(job.endAt);
                 const endLabel = Number.isFinite(end.getTime())
@@ -565,6 +582,82 @@ export function registerRoutinesCommands(program) {
         }
         console.log(chalk.gray('\nTrack progress with: agents routines runs <name>'));
     });
+    routinesCmd
+        .command('webhook')
+        .description('Fire trigger-based routines from a single GitHub webhook payload (read from --file or stdin). One-shot: matches and fires, then exits. For a long-running receiver, run this behind your own HTTP forwarder.')
+        .requiredOption('--event <name>', 'GitHub event name, as sent in the X-GitHub-Event header (e.g. pull_request, push, workflow_run)')
+        .option('--file <path>', 'Read the webhook JSON payload from this file instead of stdin')
+        .option('--dry-run', 'Show which routines would fire without firing them')
+        .action(async (options) => {
+        // Load the raw JSON payload: --file wins, else drain stdin.
+        let raw;
+        if (options.file) {
+            const resolved = path.resolve(options.file);
+            if (!fs.existsSync(resolved)) {
+                console.log(chalk.red(`File not found: ${resolved}`));
+                process.exit(1);
+            }
+            raw = fs.readFileSync(resolved, 'utf-8');
+        }
+        else {
+            if (process.stdin.isTTY) {
+                console.log(chalk.red('No payload provided. Pass --file <path> or pipe the webhook JSON on stdin.'));
+                process.exit(1);
+            }
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(chunk);
+            raw = Buffer.concat(chunks).toString('utf-8');
+        }
+        let payload;
+        try {
+            const parsed = raw.trim() ? JSON.parse(raw) : {};
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error('payload must be a JSON object');
+            }
+            payload = parsed;
+        }
+        catch (err) {
+            console.log(chalk.red(`Invalid webhook payload JSON: ${err.message}`));
+            process.exit(1);
+        }
+        const webhook = { event: options.event, payload };
+        // Matching is intentionally user-layer only (fireWebhookJobs defaults to
+        // listJobs() with no cwd), mirroring `run`/`catchup`: a webhook must never
+        // fire a cloned project repo's `.agents/routines/*.yml` and run an
+        // attacker-supplied prompt under the user's agent session.
+        if (options.dryRun) {
+            const matched = matchJobsToWebhook(listAllJobs(), webhook);
+            if (matched.length === 0) {
+                console.log(chalk.gray(`No routines match a ${options.event} event for this payload.`));
+                return;
+            }
+            console.log(chalk.bold(`${matched.length} routine(s) would fire on ${options.event}:\n`));
+            for (const job of matched) {
+                console.log(`  ${chalk.cyan(job.name)} — ${fireConditionLabel(job)}`);
+            }
+            console.log(chalk.gray('\n(dry run — no routines triggered)'));
+            return;
+        }
+        // Fired jobs run detached via executeJobDetached (the same path cron
+        // uses). Keep the daemon alive so each run's meta.json is finalized.
+        if (!isDaemonRunning()) {
+            const started = startDaemon();
+            if (started.pid) {
+                console.log(chalk.gray(`Started scheduler (PID: ${started.pid}) so webhook runs are monitored.`));
+            }
+        }
+        const fired = await fireWebhookJobs(webhook);
+        if (fired.length === 0) {
+            console.log(chalk.gray(`No routines match a ${options.event} event for this payload.`));
+            return;
+        }
+        console.log(chalk.bold(`Fired ${fired.length} routine(s) on ${options.event}:\n`));
+        for (const f of fired) {
+            console.log(`  ${chalk.cyan(f.jobName)} → ${chalk.green('started')} (run: ${f.runId})`);
+        }
+        console.log(chalk.gray('\nTrack progress with: agents routines runs <name>'));
+    });
     routinesCmd
         .command('logs [name]')
         .description('Read stdout from the most recent execution. Use --run to see a specific past run.')
@@ -675,9 +768,12 @@ export function registerRoutinesCommands(program) {
         if (result.method === 'already-running') {
             console.log(chalk.yellow(`Scheduler already running (PID: ${result.pid})`));
         }
-        else {
+        else if (result.pid) {
             console.log(chalk.green(`Scheduler started (PID: ${result.pid})`));
         }
+        else {
+            console.log(chalk.yellow('Scheduler start dispatched but no PID surfaced. Check `agents routines status`.'));
+        }
     });
     routinesCmd
         .command('stop')

package/dist/commands/secrets-migrate.js

@@ -23,7 +23,7 @@ import chalk from 'chalk';
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, listLegacyKeychainItems, setKeychainToken, } from '../lib/secrets/index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, listLegacyKeychainItems, listOrphanedKeychainItems, migrateOrphanedKeychainItems, setKeychainToken, } from '../lib/secrets/index.js';
 import { getBackupsDir } from '../lib/state.js';
 import { encryptBlob, MIN_PASSPHRASE_LEN } from '../lib/secrets/sync.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -101,7 +101,7 @@ function migrateOne(record) {
 export function registerSecretsMigrateAclCommand(secrets) {
     secrets
         .command('migrate-acl')
-        .description('Refresh existing keychain ACLs to use the signed Agents CLI helper. Dry-run by default.')
+        .description('Refresh legacy keychain ACLs and re-home items stranded in a stale access group. Dry-run by default.')
         .option('--commit', 'Perform writes (default is dry-run reporting only)')
         .option('--prefix <p>', `Restrict to items beginning with PREFIX (default ${ITEM_PREFIX})`, ITEM_PREFIX)
         .option('--all', 'Rewrite EVERY matching item, not just legacy stragglers (slower; a Touch ID prompt per item)')
@@ -115,88 +115,137 @@ export function registerSecretsMigrateAclCommand(secrets) {
             if (!prefix.startsWith(ITEM_PREFIX)) {
                 throw new Error(`--prefix must start with '${ITEM_PREFIX}' to avoid touching unrelated Keychain items (got '${prefix}').`);
             }
-            // Default: migrate ONLY legacy stragglers (items still in the file-based
-            // keychain) — modern DP items need no rewrite and touching them is a
-            // Touch ID prompt per item for nothing. `--all` forces the old full
-            // rewrite. Either way this is one command over every matching item — no
-            // one-by-one invocation.
+            // Two independent classes of work under one command:
+            //   (a) Legacy ACL stragglers — items still in the file-based keychain
+            //       with a pre-migration trusted-app ACL. Rewritten value-by-value.
+            //   (b) Orphaned access groups — data-protection items filed under a
+            //       pre-#279 non-concrete group, invisible to the pinned queries.
+            //       Re-homed by the helper behind a single Touch ID.
+            // Default: only legacy stragglers for (a); `--all` forces a full rewrite.
             const names = opts.all ? listKeychainItems(prefix) : listLegacyKeychainItems(prefix);
             const items = names.map((item) => {
                 const localExists = hasKeychainToken(item);
                 return { item, sync: !localExists };
             });
-            if (items.length === 0) {
+            const orphans = listOrphanedKeychainItems(prefix);
+            if (items.length === 0 && orphans.length === 0) {
                 console.log(opts.all
                     ? chalk.gray(`No keychain items with prefix '${prefix}'.`)
-                    : chalk.green(`Nothing to migrate — all items under '${prefix}' already use the modern ACL.`));
+                    : chalk.green(`Nothing to migrate — all items under '${prefix}' use the modern ACL and access group.`));
                 return;
             }
             const label = opts.all ? 'item' : 'legacy item';
-            console.log(chalk.bold(`Found ${items.length} ${label}(s) under '${prefix}' to migrate.`));
+            if (items.length > 0) {
+                console.log(chalk.bold(`Found ${items.length} ${label}(s) under '${prefix}' with an outdated ACL.`));
+            }
+            if (orphans.length > 0) {
+                console.log(chalk.bold(`Found ${orphans.length} orphaned item(s) under '${prefix}' in a stale access group.`));
+            }
             if (!opts.commit) {
                 for (const { item, sync } of items) {
                     console.log(`  ${chalk.cyan(item)} ${chalk.gray(sync ? '(synced)' : '(local)')}`);
                 }
+                for (const item of orphans) {
+                    console.log(`  ${chalk.cyan(item)} ${chalk.yellow('(orphaned access group)')}`);
+                }
                 console.log();
                 console.log(chalk.gray('Dry-run — pass --commit to perform the migration.'));
                 return;
             }
-            // Commit phase. Snapshot every value first (one batched read behind a
-            // single helper process, so DP items share one auth context), encrypt,
-            // then mutate.
-            const fetched = getKeychainTokens(items.map((i) => i.item));
-            const records = [];
-            for (const { item, sync } of items) {
-                const value = fetched.get(item);
-                if (value === undefined) {
-                    console.error(chalk.red(`Skipping '${item}': read failed or item absent.`));
-                    continue;
+            // ---- Commit phase ----
+            let okCount = 0;
+            let failCount = 0;
+            // (a) Legacy ACL rewrite. Snapshot every value first (one batched read
+            // behind a single helper process), encrypt, then delete + re-add. A total
+            // read failure here counts the legacy items as failed but does NOT abort —
+            // the orphan sweep (b) is independent and must still run.
+            if (items.length > 0) {
+                const fetched = getKeychainTokens(items.map((i) => i.item));
+                const records = [];
+                for (const { item, sync } of items) {
+                    const value = fetched.get(item);
+                    if (value === undefined) {
+                        console.error(chalk.red(`Skipping '${item}': read failed or item absent.`));
+                        continue;
+                    }
+                    records.push({ item, sync, value });
                 }
-                records.push({ item, sync, value });
-            }
-            if (records.length === 0) {
-                console.error(chalk.red('No items could be read. Aborting before any writes.'));
-                process.exit(1);
-            }
-            const passphrase = opts.passphraseEnv
-                ? (() => {
-                    const v = process.env[opts.passphraseEnv];
-                    if (!v)
-                        throw new Error(`Env var '${opts.passphraseEnv}' not set.`);
-                    if (v.length < MIN_PASSPHRASE_LEN)
-                        throw new Error(`Passphrase must be at least ${MIN_PASSPHRASE_LEN} characters.`);
-                    return v;
-                })()
-                : await promptPassphrase();
-            const backupPath = writeEncryptedBackup(records, passphrase);
-            // Compute a quick fingerprint so the user can sanity-check recovery without
-            // decrypting. Hash of (count, sorted item names).
-            const fingerprint = crypto
-                .createHash('sha256')
-                .update(records.length + '\n' + records.map((r) => r.item).sort().join('\n'))
-                .digest('hex')
-                .slice(0, 12);
-            console.log(chalk.green(`Encrypted backup written to ${backupPath} (sha256-12: ${fingerprint}).`));
-            const results = [];
-            for (const record of records) {
-                const r = migrateOne(record);
-                results.push(r);
-                if (r.status === 'ok') {
-                    console.log(`  ${chalk.green('ok')}     ${record.item}`);
+                if (records.length === 0) {
+                    console.error(chalk.red('No legacy items could be read — skipping legacy rewrite.'));
+                    failCount += items.length;
                 }
                 else {
-                    console.log(`  ${chalk.red(r.status)} ${record.item} ${chalk.gray(r.detail ?? '')}`);
+                    const passphrase = opts.passphraseEnv
+                        ? (() => {
+                            const v = process.env[opts.passphraseEnv];
+                            if (!v)
+                                throw new Error(`Env var '${opts.passphraseEnv}' not set.`);
+                            if (v.length < MIN_PASSPHRASE_LEN)
+                                throw new Error(`Passphrase must be at least ${MIN_PASSPHRASE_LEN} characters.`);
+                            return v;
+                        })()
+                        : await promptPassphrase();
+                    const backupPath = writeEncryptedBackup(records, passphrase);
+                    // Quick fingerprint so the user can sanity-check recovery without decrypting.
+                    const fingerprint = crypto
+                        .createHash('sha256')
+                        .update(records.length + '\n' + records.map((r) => r.item).sort().join('\n'))
+                        .digest('hex')
+                        .slice(0, 12);
+                    console.log(chalk.green(`Encrypted backup written to ${backupPath} (sha256-12: ${fingerprint}).`));
+                    const results = [];
+                    for (const record of records) {
+                        const r = migrateOne(record);
+                        results.push(r);
+                        if (r.status === 'ok') {
+                            console.log(`  ${chalk.green('ok')}     ${record.item}`);
+                        }
+                        else {
+                            console.log(`  ${chalk.red(r.status)} ${record.item} ${chalk.gray(r.detail ?? '')}`);
+                        }
+                    }
+                    const ok = results.filter((r) => r.status === 'ok').length;
+                    okCount += ok;
+                    failCount += results.length - ok;
+                    if (results.length - ok > 0) {
+                        console.error(chalk.gray(`Restore from ${backupPath} using the backup passphrase if needed.`));
+                    }
+                }
+            }
+            // (b) Orphan re-home — one helper call, one Touch ID for the batch. The
+            // helper adds the pinned copy before deleting the orphan, so no pre-write
+            // backup is needed (a failed add leaves the orphan intact and readable).
+            if (orphans.length > 0) {
+                console.log(chalk.bold(`Re-homing ${orphans.length} orphaned item(s) into the current access group (one Touch ID)…`));
+                const results = migrateOrphanedKeychainItems(prefix);
+                const healed = new Set();
+                for (const r of results) {
+                    healed.add(r.item);
+                    if (r.status === 'ok') {
+                        okCount += 1;
+                        console.log(`  ${chalk.green('ok')}     ${r.item}`);
+                    }
+                    else {
+                        failCount += 1;
+                        console.log(`  ${chalk.red(r.status)} ${r.item} ${chalk.gray(r.detail ?? '')}`);
+                    }
+                }
+                // Any orphan we listed but the helper couldn't reach (e.g. under a
+                // different signing team) — surface it, never drop it silently.
+                for (const item of orphans) {
+                    if (!healed.has(item)) {
+                        failCount += 1;
+                        console.log(`  ${chalk.red('fail')} ${item} ${chalk.gray('unreachable (different signing team?)')}`);
+                    }
                 }
             }
-            const okCount = results.filter((r) => r.status === 'ok').length;
-            const failCount = results.length - okCount;
+            const total = okCount + failCount;
             console.log();
             if (failCount === 0) {
-                console.log(chalk.green(`Migrated ${okCount}/${results.length} item(s).`));
+                console.log(chalk.green(`Migrated ${okCount}/${total} item(s).`));
             }
             else {
-                console.error(chalk.yellow(`Migrated ${okCount}/${results.length} item(s); ${failCount} failed.`));
-                console.error(chalk.gray(`Restore from ${backupPath} using the backup passphrase if needed.`));
+                console.error(chalk.yellow(`Migrated ${okCount}/${total} item(s); ${failCount} failed.`));
                 process.exit(1);
             }
         }

package/dist/commands/secrets.d.ts

@@ -7,7 +7,16 @@
  */
 import { type Command } from 'commander';
 import { SSH_TARGET_RE, assertValidSshTarget } from '../lib/ssh-exec.js';
+import { quoteWin32ExecArg } from '../lib/platform/index.js';
+import { type SecretsBundle, type SecretsPolicy } from '../lib/secrets/bundles.js';
 export { SSH_TARGET_RE, assertValidSshTarget };
+/**
+ * Build the child environment for `agents secrets exec`. Strips
+ * loader/interpreter hijack vars (matching agent spawns in exec.ts) and never
+ * forwards AGENTS_SECRETS_PASSPHRASE — the master decryption key must not reach
+ * the executed command.
+ */
+export declare function buildSecretsExecEnv(parentEnv: NodeJS.ProcessEnv, secretEnv: Record<string, string>): NodeJS.ProcessEnv;
 /**
  * Serialize a resolved env map to `.env` lines that round-trip losslessly through
  * `parseDotenv` on the remote: `KEY="VALUE"`. parseDotenv strips exactly one outer
@@ -16,25 +25,29 @@ export { SSH_TARGET_RE, assertValidSshTarget };
  * parse, so multi-line values are rejected rather than silently corrupted.
  */
 export declare function bundleEnvToDotenv(env: Record<string, string>): string;
+/** The POLICY column for `secrets list`: the prompt policy, plus a "Nh left"
+ * hint when a `daily` bundle is currently held by the secrets-agent. `held`
+ * maps bundle name → expiry epoch-ms (from agentStatus()). */
+export declare function renderPolicyCol(b: SecretsBundle, held?: Map<string, number>): string;
 /** Register the `agents secrets` command tree. */
 export declare function registerSecretsCommands(program: Command): void;
+/** Validate a prompt-policy value, throwing a clear message on a bad one (the
+ * caller's try/catch renders it and exits). Accepts the legacy `biometry` /
+ * `session` / `none` tokens as aliases for `always` / `daily` / `never` so older
+ * flags and scripts keep working. `never`/`none` is the no-biometry-ACL tier —
+ * accepted here, then gated behind a loud confirmation in the command layer. */
+export declare function parsePolicyOpt(raw: string | undefined): SecretsPolicy;
 /**
- * Quote one argument for a Windows `cmd.exe` command line, as built by Node's
- * `spawn(..., { shell: true })` on win32 (`agents secrets exec`). cmd.exe does
- * NO quoting of its own, so an unquoted arg with a space is split into several
- * args, and a cmd metacharacter (`&|<>()^`) would be interpreted by the shell.
- * We wrap any arg with whitespace, a quote, or a metacharacter in double quotes
- * and escape embedded quotes / trailing backslashes per the CommandLineToArgvW
- * rules, so the *child's* argv parse reconstructs the original argument.
- *
- * CAVEAT: cmd.exe expands `%VAR%` (always) and `!VAR!` (under delayed expansion)
- * BEFORE argv parsing, and double-quoting does NOT suppress `%`/`!` (the
- * "BatBadBut" / CVE-2024-1874 class). We deliberately do not escape `%`/`!`:
- * `agents secrets exec` runs a caller-supplied command against a bundle the
- * caller owns, so caller-controlled `%`/`!` is not a privilege boundary. If that
- * ever changes (exec'ing an untrusted command line), route through a shell that
- * disables expansion rather than relying on this quoter. An empty arg becomes
- * `""`. Exported for tests. No-ops on non-Windows (the caller only invokes it
- * under `process.platform === 'win32'`).
+ * Gate a create/switch to the `never` prompt-policy behind an explicit,
+ * deliberate acknowledgement — it is the least-safe tier (no user-presence
+ * check on any read). Returns:
+ *   - `'ok'`    — not `never`, or already acknowledged via `--i-understand`.
+ *   - `'prompt'` — interactive shell: caller must run a loud confirm prompt.
+ * Throws in a non-interactive shell when the flag is absent, so a headless
+ * `create --policy never` can't silently downgrade a bundle's protection.
  */
-export declare function quoteWin32ExecArg(arg: string): string;
+export declare function assertNeverPolicyAcknowledged(policy: SecretsPolicy | undefined, opts: {
+    iUnderstand?: boolean;
+    interactive: boolean;
+}): 'ok' | 'prompt';
+export { quoteWin32ExecArg };