@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/commands/hosts.js

@@ -14,6 +14,7 @@ import { getProvider, listAllHosts, resolveHost } from '../lib/hosts/registry.js
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { listSshConfigHosts, listKnownHosts, isSshConfigHost } from '../lib/hosts/ssh-config.js';
 import { probeHost, remoteAgentsVersion, bootstrapAgentsCli, localCliVersion, } from '../lib/hosts/ready.js';
+import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
 import { listTasks } from '../lib/hosts/tasks.js';
 import { reconcileRunningTasks } from '../lib/hosts/reconcile.js';
 import { showHostTaskLog } from '../lib/hosts/logs.js';
@@ -29,18 +30,20 @@ function parseTarget(target) {
  * Callers that just probed the host pass the result through to avoid a second,
  * redundant `uname` round-trip; otherwise we probe here.
  */
-async function maybeBootstrap(target, hostName, probe = probeHost(target)) {
+async function maybeBootstrap(target, hostName, probe = probeHost(target, resolveRemoteOsSync(hostName))) {
     if (!probe.reachable) {
         console.log(chalk.yellow(`  Not reachable over SSH yet — skipping bootstrap. Fix key auth, then: agents hosts check ${hostName}`));
         return;
     }
-    const remoteVer = remoteAgentsVersion(target);
+    // Prefer the OS the probe just observed; fall back to the registry hint.
+    const os = probe.os ?? resolveRemoteOsSync(hostName);
+    const remoteVer = remoteAgentsVersion(target, os);
     const localVer = localCliVersion();
     if (!remoteVer) {
         const ok = await confirm({ message: `  agents-cli not found on ${hostName}. Install ${localVer ? `v${localVer}` : 'latest'} now?`, default: true });
         if (ok) {
             console.log(chalk.gray('  Installing agents-cli on the host…'));
-            const r = bootstrapAgentsCli(target, localVer);
+            const r = bootstrapAgentsCli(target, localVer, os);
             console.log(r.ok ? chalk.green('  Installed.') : chalk.red(`  Install failed:\n${r.output}`));
         }
         return;
@@ -49,7 +52,7 @@ async function maybeBootstrap(target, hostName, probe = probeHost(target)) {
     if (localVer && remoteClean !== localVer) {
         const ok = await confirm({ message: `  ${hostName} has agents-cli ${remoteClean}, you have ${localVer}. Upgrade to match?`, default: false });
         if (ok) {
-            const r = bootstrapAgentsCli(target, localVer);
+            const r = bootstrapAgentsCli(target, localVer, os);
             console.log(r.ok ? chalk.green('  Upgraded.') : chalk.red(`  Upgrade failed:\n${r.output}`));
         }
     }
@@ -141,15 +144,16 @@ async function doCheck(name) {
         return;
     }
     const target = sshTargetFor(host);
+    const os = host.os ?? resolveRemoteOsSync(name);
     process.stdout.write(`Probing ${chalk.cyan(name)} (${target})… `);
-    const probe = probeHost(target);
+    const probe = probeHost(target, os);
     if (!probe.reachable) {
         console.log(chalk.red('unreachable'));
         process.exitCode = 1;
         return;
     }
     console.log(chalk.green('reachable') + chalk.gray(probe.os ? ` · ${probe.os}` : ''));
-    const ver = remoteAgentsVersion(target);
+    const ver = remoteAgentsVersion(target, probe.os ?? os);
     console.log(`  agents-cli: ${ver ? chalk.green(ver) : chalk.yellow('not installed')}`);
 }
 async function doRemove(name) {

package/dist/commands/inspect.js

@@ -11,7 +11,7 @@
  * names render as OSC-8 hyperlinks to the marker file (SKILL.md / WORKFLOW.md /
  * AGENT.md / the file itself) so users can click straight to the source.
  */
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
 import { addHostOption } from '../lib/hosts/option.js';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -512,35 +512,34 @@ function renderRepoSummary(repo, options) {
 export function repoGitInfo(root) {
     const git = (args) => {
         try {
-            return execSync(`git -C ${JSON.stringify(root)} ${args}`, { stdio: ['ignore', 'pipe', 'ignore'] })
-                .toString().trim();
+            return execFileSync('git', ['-C', root, ...args], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' }).trim();
         }
         catch {
             return null;
         }
     };
-    const branch = git('rev-parse --abbrev-ref HEAD');
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD']);
     if (branch === null)
         return null;
-    // Read status WITHOUT trimming — git()'s .trim() would strip the leading
+    // Read status WITHOUT trimming — trimming would strip the leading
     // space of the first porcelain line (`XY path`), corrupting the path slice.
     let statusRaw;
     try {
-        statusRaw = execSync(`git -C ${JSON.stringify(root)} status --porcelain`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+        statusRaw = execFileSync('git', ['-C', root, 'status', '--porcelain'], { stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8' });
     }
     catch {
         statusRaw = null;
     }
     const dirtyFiles = statusRaw ? statusRaw.split('\n').filter(Boolean).map(l => l.slice(3)) : [];
     let lastCommit = null;
-    const log = git('log -1 --format=%h%x1f%s%x1f%cr');
+    const log = git(['log', '-1', '--format=%h%x1f%s%x1f%cr']);
     if (log) {
         const [sha, subject, relative] = log.split('\x1f');
         if (sha)
             lastCommit = { sha, subject: subject ?? '', relative: relative ?? '' };
     }
     let ahead = null, behind = null;
-    const counts = git("rev-list --left-right --count '@{upstream}...HEAD'");
+    const counts = git(['rev-list', '--left-right', '--count', '@{upstream}...HEAD']);
     if (counts) {
         const [b, a] = counts.split(/\s+/).map(n => parseInt(n, 10));
         if (Number.isFinite(b) && Number.isFinite(a)) {
@@ -548,7 +547,7 @@ export function repoGitInfo(root) {
             ahead = a;
         }
     }
-    return { branch, dirty: dirtyFiles.length, dirtyFiles, url: git('remote get-url origin'), lastCommit, ahead, behind };
+    return { branch, dirty: dirtyFiles.length, dirtyFiles, url: git(['remote', 'get-url', 'origin']), lastCommit, ahead, behind };
 }
 // ─── Summary mode ────────────────────────────────────────────────────────────
 async function renderSummary(agent, version, versionHome, options) {

package/dist/commands/lock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `agents lock` — write a deterministic `agents.lock` for the resolved resource
+ * set at the project root; `agents lock --frozen` verifies the live resources
+ * match that lock EXACTLY and fails closed (non-zero exit + a clear diff) on any
+ * drift. The reproducible-CI slice of governance #337.
+ *
+ * This is OFF the default path: normal `agents add` / `agents sync` never touch
+ * the lock. Generation and verification only run when this command is invoked.
+ */
+import { Command } from 'commander';
+/** Register the `agents lock` command. */
+export declare function registerLockCommand(program: Command): void;

package/dist/commands/lock.js

@@ -0,0 +1,70 @@
+/**
+ * `agents lock` — write a deterministic `agents.lock` for the resolved resource
+ * set at the project root; `agents lock --frozen` verifies the live resources
+ * match that lock EXACTLY and fails closed (non-zero exit + a clear diff) on any
+ * drift. The reproducible-CI slice of governance #337.
+ *
+ * This is OFF the default path: normal `agents add` / `agents sync` never touch
+ * the lock. Generation and verification only run when this command is invoked.
+ */
+import chalk from 'chalk';
+import { enumerateLockSources, buildLock, writeLock, readLock, verifyLock, lockDiffIsClean, resolveProjectRoot, LOCK_FILENAME, } from '../lib/lock.js';
+/** Register the `agents lock` command. */
+export function registerLockCommand(program) {
+    program
+        .command('lock')
+        .summary('Write or verify agents.lock — a SHA-256 manifest of resolved resources')
+        .description('Capture a deterministic SHA-256 per resolved resource file (commands, skills, hooks, rules, mcp, permissions, subagents — project > user > system > extras) into an agents.lock at the project root.\n\n' +
+        'Run bare to (re)generate the lock. Pass --frozen to VERIFY the live resolved resources match an existing agents.lock exactly — it exits non-zero with an added/removed/changed diff on any mismatch, and errors if no lock exists yet. That is the reproducible-CI gate; normal installs and syncs are unaffected.')
+        .option('--cwd <path>', 'Working directory to resolve resources and the project root from')
+        .option('--frozen', 'Verify resolved resources match agents.lock exactly; fail (non-zero) on any drift', false)
+        .action((opts) => {
+        runLock(opts);
+    });
+}
+function runLock(opts) {
+    const cwd = opts.cwd || process.cwd();
+    const projectRoot = resolveProjectRoot(cwd);
+    const sources = enumerateLockSources(cwd);
+    if (opts.frozen) {
+        verifyFrozen(projectRoot, sources);
+        return;
+    }
+    const lock = buildLock(sources);
+    const written = writeLock(projectRoot, lock);
+    const count = Object.keys(lock.resources).length;
+    console.log(chalk.green(`Wrote ${LOCK_FILENAME}`) +
+        chalk.gray(` — ${count} resource file(s) → ${written}`));
+}
+function verifyFrozen(projectRoot, sources) {
+    let existing;
+    try {
+        existing = readLock(projectRoot);
+    }
+    catch (e) {
+        console.error(chalk.red(`agents lock --frozen: ${e.message}`));
+        process.exitCode = 1;
+        return;
+    }
+    if (!existing) {
+        console.error(chalk.red(`No ${LOCK_FILENAME} at ${projectRoot}.`));
+        console.error(chalk.gray('Generate one first: agents lock'));
+        process.exitCode = 1;
+        return;
+    }
+    const diff = verifyLock(existing, sources);
+    if (lockDiffIsClean(diff)) {
+        const count = Object.keys(existing.resources).length;
+        console.log(chalk.green(`✓ ${count} resource file(s) match ${LOCK_FILENAME}`));
+        return;
+    }
+    console.error(chalk.red(`✗ resources drifted from ${LOCK_FILENAME}:`));
+    for (const key of diff.changed)
+        console.error(chalk.yellow(`  changed  ${key}`));
+    for (const key of diff.added)
+        console.error(chalk.yellow(`  added    ${key}`));
+    for (const key of diff.removed)
+        console.error(chalk.yellow(`  removed  ${key}`));
+    console.error(chalk.gray('Re-lock once the change is intended: agents lock'));
+    process.exitCode = 1;
+}

package/dist/commands/message.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agents message <target> <text>` — send a message to a running agent.
+ *
+ * Unifies two delivery paths behind one verb:
+ *   - a live LOCAL/teams/loop agent → enqueue into its file-spool mailbox; the
+ *     PreToolUse hook injects it at the agent's next tool call.
+ *   - a CLOUD task id → the existing provider follow-up path (was
+ *     `agents cloud message`).
+ *
+ * Cross-host is handled one layer up: `--host <h>` routes the whole command over
+ * ssh via `REMOTE_PASSTHROUGH` (see src/lib/hosts/passthrough.ts), so the box is
+ * written on the host that actually owns the agent.
+ */
+import type { Command } from 'commander';
+export declare function registerMessageCommand(program: Command): void;

package/dist/commands/message.js

@@ -0,0 +1,56 @@
+import chalk from 'chalk';
+import { getActiveSessions } from '../lib/session/active.js';
+import { getTaskById, updateTaskStatus } from '../lib/cloud/store.js';
+import { resolveProvider } from '../lib/cloud/registry.js';
+import { mailboxDir, enqueue } from '../lib/mailbox.js';
+import { resolveMessageTarget } from '../lib/mailbox-target.js';
+function die(msg, code = 1) {
+    console.error(chalk.red(msg));
+    process.exit(code);
+}
+export function registerMessageCommand(program) {
+    program
+        .command('message <target> <text>')
+        .description('Send a message to a running agent (delivered at its next tool call) or a cloud task.')
+        .option('--from <who>', 'Label recorded as the sender of this message')
+        .action(async (target, text, opts) => {
+        if (!target.trim()) {
+            die('Target must be a session/agent id or cloud task id. Run `agents sessions --active` to list running agents.');
+        }
+        const sessions = await getActiveSessions();
+        const res = resolveMessageTarget(target, sessions, (id) => getTaskById(id) != null);
+        switch (res.kind) {
+            case 'cloud': {
+                const task = getTaskById(res.id);
+                const provider = resolveProvider(task.provider);
+                try {
+                    await provider.message(res.id, text);
+                    updateTaskStatus(res.id, 'running');
+                    console.log(chalk.green(`Message sent to cloud task ${res.id}. Agent is continuing.`));
+                }
+                catch (err) {
+                    die(err.message);
+                }
+                return;
+            }
+            case 'local': {
+                try {
+                    const msgId = enqueue(mailboxDir(res.id), { to: res.id, text, from: opts.from });
+                    console.log(chalk.green(`Queued message ${msgId} for ${res.id}. `) +
+                        chalk.dim('The agent will see it at its next tool call.'));
+                }
+                catch (err) {
+                    die(err.message);
+                }
+                return;
+            }
+            case 'ambiguous': {
+                const lines = res.candidates.map((c) => `  ${c.id}  ${chalk.dim(c.label)}`).join('\n');
+                die(`"${target}" matches ${res.candidates.length} running agents:\n${lines}\nRe-run with a full id.`);
+                return;
+            }
+            case 'none':
+                die(`No running agent or cloud task matches "${target}". List targets with \`agents sessions --active\`.`);
+        }
+    });
+}

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);
             }
         }