@phnx-labs/agents-cli 1.22.19 → 1.22.21

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 1.22.21
+
+- **`agents secrets exec <bundle> -- <cmd>` now resolves a locked keychain bundle
+  interactively at a real terminal.** The local resolve hardcoded `agentOnly: true`
+  (`commands/secrets.ts`), so running `exec` on a locked bundle at a terminal
+  failed closed with "run `agents secrets unlock` first" instead of raising the one
+  Touch ID sheet the human just implied by asking to use the values. It now gates
+  `agentOnly` on `isHeadlessSecretsContext() || !isInteractiveTerminal()`: an
+  unlocked bundle still runs silently, a locked bundle at an interactive terminal
+  resolves with a single sheet and then runs the command with the secrets injected,
+  and under an agent (`AGENTS_RUNTIME`) or headless (no TTY) it stays broker-only —
+  release/CI scripts never prompt. Mirrors the same fix for `view --reveal`.
+  `--host` remote resolves and `export`/`get` are unchanged. Source:
+  `apps/cli/src/commands/secrets.ts`.
+
+## 1.22.20
+
+- **Claude sessions are attributed to the account that produced them.** The session
+  scanner resolved ONE account email process-globally (`cachedClaudeAccount`) and
+  stamped it on every Claude row of a scan, so a machine with several signed-in
+  accounts reported all of its history under whichever resolved first — on a
+  three-account machine, 982 of 2,736 indexed sessions carried the wrong email and
+  most of the per-account cost was misplaced. Attribution now resolves per transcript,
+  from its path plus the version recorded inside the file. Two orgs sharing one email
+  (a Team seat and a personal Max plan) stay in separate buckets, keyed on the org
+  `usageKey` the same way `agents run`'s balanced rotation keys quota. Sessions whose
+  account cannot be established are reported as `unattributed:<reason>` rather than
+  folded into a real account. Source: `apps/cli/src/lib/session/claude-accounts.ts`,
+  `apps/cli/src/lib/session/discover.ts`.
+
+  Rows under the mutable `~/.claude` symlink are attributed by their recorded version,
+  not by wherever the symlink points now: only 684 of 1,334 such rows came from the
+  version the symlink currently names. Retired (`trash/`) homes keep their
+  `.claude.json`, so their transcripts stay attributable. A transcript in a home that
+  exists but is signed out stays dark and is named after that home — its location
+  proves which config dir Claude used.
+
+  **Harness scope: Claude only.** Attribution depends on the per-version home carrying
+  an `oauthAccount`. Other harnesses have their own per-version credential files, so
+  the mechanism generalizes, but each needs its own identity extractor and
+  quota-bucket notion. Until then a non-Claude session has no `account_key` and rolls
+  up under `unattributed:<agent>`.
+
+- **`account_key` / `account_org` on indexed sessions, and `--by account` rollups.**
+  Schema v33 adds both columns plus `idx_sessions_account_key`, and `queryUsageRollup`
+  accepts `groupBy: 'account'` — surfaced by `agents cost --by account` and
+  `agents output --by account`, which render the org and email rather than the raw
+  uuid. The migration repairs existing rows in place from `file_path` and `version`
+  and deliberately does **not** flush `scan_ledger`: attribution needs no transcript
+  re-parse, so a 2,736-row index migrates in ~200ms with every ledger entry still
+  warm. `getDB` also runs a guarded self-healing repair for rows an older CLI left
+  unattributed. Source: `apps/cli/src/lib/session/db.ts`.
+
+- **`upsertSessionsBatch` bound its named parameters from an untyped literal.** bun
+  binds named parameters in strict mode, where a MISSING key throws, while node binds
+  NULL — so a key omitted from that literal broke only the shipped standalone binary,
+  and the per-row guard swallowed it into a silently skipped session. The literal is
+  now typed against `SessionRow`, so the compiler rejects the next omission. Source:
+  `apps/cli/src/lib/session/db.ts`.
+
+- `readClaudeHomeConfig()` in `apps/cli/src/lib/agents.ts` — the single place a Claude
+  home's `oauthAccount` identity is read. `getAccountInfo` now uses it, so identity
+  extraction is no longer duplicated. Unlike `getAccountInfo` it does not apply the
+  credential floor, because a revoked token does not change which org produced a past
+  transcript.
+
+- **`agents routines add` accepts `--project <name>` (repeatable) and `--all-projects` to tag a routine to one or more projects.** Project names are validated against `agents projects list` at creation time; unknown names are rejected with a suggested fix command. The flag sets the new `projects?: string[]` field in the job config YAML — metadata-only, no effect on scheduling or execution. `--all-projects` sets `projects: ["*"]` (the "all defined projects" sentinel) and is mutually exclusive with `--project`. Source: `apps/cli/src/lib/routines.ts` (`JobConfig`, `validateJob`, `computeProjectGroup`, `writeJob`), `apps/cli/src/commands/routines.ts`.
+
+- **`agents routines list` now groups by project by default.** The human terminal view buckets routines under their associated project name, **All projects** (`projects: ["*"]`), **Cross-project** (multiple project entries), **Operations** (no `projects:` field), or **Unknown projects** (project names not found in `agents projects`). Pass `--group-by device` to restore the previous device-placement grouping. The `--json` payload gains `projects` (array) and `projectGroup` (string) fields. Source: `apps/cli/src/commands/routines.ts` (`groupRoutineJobsByProject`).
+
 ## 1.22.19
 
 ### Fixed

package/dist/commands/cost.js

@@ -10,7 +10,7 @@ export function registerCostCommand(program) {
         .description('Roll up $ cost and duration across local agent sessions')
         .option('--json', 'Output the rollup as JSON')
         .option('--since <time>', 'Only sessions newer than this (e.g., 7d, 4w, or ISO date)')
-        .option('--by <dimension>', 'Group the breakdown by: agent (default), project, or day')
+        .option('--by <dimension>', 'Group the breakdown by: agent (default), project, day, or account (the Claude org that produced each session)')
         .addHelpText('after', `
 Examples:
   agents cost                   Daily histogram + top sessions + per-agent breakdown
@@ -28,9 +28,9 @@ Cost is computed offline from a versioned per-model price table (${PRICING_VERSI
 function resolveGroup(by) {
     if (by === undefined)
         return 'agent';
-    if (by === 'agent' || by === 'project' || by === 'day')
+    if (by === 'agent' || by === 'project' || by === 'day' || by === 'account')
         return by;
-    console.error(chalk.red('error: --by must be one of: agent, project, day'));
+    console.error(chalk.red('error: --by must be one of: agent, project, day, account'));
     process.exit(1);
 }
 async function costAction(options) {
@@ -101,7 +101,10 @@ async function costAction(options) {
         out.push('');
     }
     // Per-agent / per-project / per-day breakdown.
-    const groupLabel = groupBy === 'agent' ? 'agent' : groupBy === 'project' ? 'project' : 'day';
+    const groupLabel = groupBy === 'agent' ? 'agent'
+        : groupBy === 'project' ? 'project'
+            : groupBy === 'account' ? 'account'
+                : 'day';
     out.push(chalk.bold(`By ${groupLabel}`));
     const cols = terminalWidth();
     const costW2 = Math.max(...breakdown.map(r => formatUsd(r.costUsd).length), 4);
@@ -109,12 +112,13 @@ async function costAction(options) {
     const sessionW = Math.max(...breakdown.map(r => `${String(r.sessionCount).padStart(countW)} session${r.sessionCount !== 1 ? 's' : ''}`.length));
     const durationW = Math.max(...breakdown.map(r => r.durationMs > 0 ? stringWidth(formatDuration(r.durationMs)) : 1), 1);
     const fixedW = 2 + 2 + costW2 + 2 + sessionW + 2 + durationW;
-    const keyW = Math.max(8, Math.min(Math.max(...breakdown.map(r => stringWidth(r.key)), groupLabel.length), cols - fixedW));
+    const display = (r) => r.label ?? r.key;
+    const keyW = Math.max(8, Math.min(Math.max(...breakdown.map(r => stringWidth(display(r))), groupLabel.length), cols - fixedW));
     for (const r of breakdown) {
         const cost = formatUsd(r.costUsd).padStart(costW2);
         const dur = r.durationMs > 0 ? formatDuration(r.durationMs) : '—';
         const sessions = `${String(r.sessionCount).padStart(countW)} session${r.sessionCount !== 1 ? 's' : ''}`;
-        out.push(`  ${padToWidth(truncateToWidth(r.key, keyW), keyW)}  ${chalk.green(cost)}  ${chalk.gray(padToWidth(sessions, sessionW))}  ${chalk.gray(padToWidth(dur, durationW))}`);
+        out.push(`  ${padToWidth(truncateToWidth(display(r), keyW), keyW)}  ${chalk.green(cost)}  ${chalk.gray(padToWidth(sessions, sessionW))}  ${chalk.gray(padToWidth(dur, durationW))}`);
     }
     console.log(out.join('\n'));
 }

package/dist/commands/output.js

@@ -18,7 +18,7 @@ export function registerOutputCommand(program) {
         .description('Productivity rollup — token burn vs shipped output (PRs, commits) across agents')
         .option('--json', 'Output the rollup as JSON')
         .option('--since <time>', 'Only sessions/commits newer than this: 1h, 24h, 7d, 4w, 1mo, 1y, or ISO date (default 7d)')
-        .option('--by <dimension>', 'Group the burn/output breakdown by: agent (default), project, or day')
+        .option('--by <dimension>', 'Group the burn/output breakdown by: agent (default), project, day, or account (the Claude org that produced each session)')
         .option('--repos-dir <dir>', 'Root scanned for git repos (default ~/src)')
         .option('--author <email...>', 'Count commits by these author emails (default: your git identities)')
         .option('--login <login...>', 'Count PRs for these GitHub logins (default: current gh user)')
@@ -42,9 +42,9 @@ Output tokens are the real generated tokens — NOT the cache-inflated total tok
 function resolveGroup(by) {
     if (by === undefined)
         return 'agent';
-    if (by === 'agent' || by === 'project' || by === 'day')
+    if (by === 'agent' || by === 'project' || by === 'day' || by === 'account')
         return by;
-    console.error(chalk.red('error: --by must be one of: agent, project, day'));
+    console.error(chalk.red('error: --by must be one of: agent, project, day, account'));
     process.exit(1);
 }
 /** Compact token formatter: 38.6M, 4.1K, 10.6B. */
@@ -188,7 +188,10 @@ function mergeMachines(machines, options) {
         for (const a of m.uncostedAgents)
             uncosted.add(a);
         for (const r of m.breakdown.rows) {
-            const cur = byKey.get(r.key) ?? { key: r.key, costUsd: 0, durationMs: 0, sessionCount: 0, tokenCount: 0, outputTokens: 0 };
+            const cur = byKey.get(r.key) ?? { key: r.key, label: r.label, costUsd: 0, durationMs: 0, sessionCount: 0, tokenCount: 0, outputTokens: 0 };
+            // Peers resolve their own labels; keep the first non-empty one so a machine that
+            // has not indexed an account yet does not blank a label another machine supplied.
+            cur.label ??= r.label;
             cur.costUsd += r.costUsd;
             cur.durationMs += r.durationMs;
             cur.sessionCount += r.sessionCount;
@@ -256,11 +259,12 @@ function renderBreakdown(rows, groupBy) {
     const outW = Math.max(...rows.map(r => formatCompact(r.outputTokens).length), 6);
     const sessW = Math.max(...rows.map(r => String(r.sessionCount).length), 3);
     const fixedW = 2 + 2 + burnW + 2 + outW + 2 + sessW + 8;
-    const keyW = Math.max(8, Math.min(Math.max(...rows.map(r => r.key.length), groupBy.length), cols - fixedW));
+    const display = (r) => r.label ?? r.key;
+    const keyW = Math.max(8, Math.min(Math.max(...rows.map(r => display(r).length), groupBy.length), cols - fixedW));
     out.push('  ' + chalk.gray(padToWidth('', keyW)) + '  ' + chalk.gray(padToWidth('burn', burnW)) + '  ' + chalk.gray(padToWidth('output', outW)) + '  ' + chalk.gray('sessions'));
     for (const r of rows) {
         out.push('  ' +
-            padToWidth(truncateToWidth(r.key, keyW), keyW) +
+            padToWidth(truncateToWidth(display(r), keyW), keyW) +
             '  ' +
             chalk.green(padToWidth(formatUsd(r.costUsd), burnW)) +
             '  ' +

package/dist/commands/routines.d.ts

@@ -39,6 +39,12 @@ export interface RoutineListGroup {
     local: boolean;
 }
 export declare function groupRoutineJobsByDevice(jobs: JobConfig[], registry: DeviceRegistry, self?: string): RoutineListGroup[];
+/**
+ * Group routines by their `projects` metadata field.
+ * Named projects come first (alphabetically), followed by All projects, Cross-project,
+ * Operations (no project), and Unknown projects (stale names).
+ */
+export declare function groupRoutineJobsByProject(jobs: JobConfig[], knownProjectNames: Set<string>): RoutineListGroup[];
 export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];
 /** Register the `agents routines` command tree. */
 export declare function registerRoutinesCommands(program: Command): void;

package/dist/commands/routines.js

@@ -14,7 +14,8 @@ import { isDaemonRunning, signalDaemonReload, startDaemon, stopDaemon, readDaemo
 import { assertSchedulerEnabled } from '../lib/device-config.js';
 import { resolveAgentName, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
 import { humanizeCron, humanizeNextRun, formatRepoLink, REPO_DISPLAY_MAX } from '../lib/routines-format.js';
-import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, HOST_STRATEGIES, } from '../lib/routines.js';
+import { listJobs as listAllJobs, deleteJob, readJob, validateJob, writeJob, setJobEnabled, listRuns, routineStats, getLatestRun, getRunDir, getJobPath, parseAtTime, hasCompletedOneShotRun, isOneShotLikeSchedule, isOneShotRoutine, isPastOneShotRoutine, jobRunsOnThisDevice, checkJobDeviceEligibility, normalizeTriggerEvent, parseHostStrategy, resolveHostStrategy, HOST_STRATEGIES, computeProjectGroup, computeProjectGroupKind, projectGroupKey, projectGroupTitle, projectGroupOrder, normalizeProjects, } from '../lib/routines.js';
+import { listProjectDefs, isSafeProjectName } from '../lib/projects.js';
 import { discoverProjectRoutinesAt, enableProjectRoutines, disableProjectRoutines, syncProjectRoutines, syncAllProjectRoutines, listEnabledProjectRoots, resolveProjectRoot, displayProjectPath, listProjectRoutineFiles, } from '../lib/routines-project.js';
 import { fireWebhookJobs, matchJobsToWebhook } from '../lib/triggers/webhook.js';
 import { getRoutinesDir } from '../lib/state.js';
@@ -217,6 +218,40 @@ export function groupRoutineJobsByDevice(jobs, registry, self = machineId()) {
     };
     return [...groups.values()].sort((a, b) => order(a) - order(b) || a.title.localeCompare(b.title));
 }
+/**
+ * Group routines by their `projects` metadata field.
+ * Named projects come first (alphabetically), followed by All projects, Cross-project,
+ * Operations (no project), and Unknown projects (stale names).
+ */
+export function groupRoutineJobsByProject(jobs, knownProjectNames) {
+    const groups = new Map();
+    const add = (key, title, job) => {
+        const existing = groups.get(key);
+        if (existing) {
+            existing.jobs.push(job);
+            return;
+        }
+        groups.set(key, { key, title, jobs: [job], local: true });
+    };
+    const orderByKey = new Map();
+    for (const job of jobs) {
+        const group = computeProjectGroupKind(job.projects, knownProjectNames);
+        const key = projectGroupKey(group);
+        orderByKey.set(key, projectGroupOrder(group));
+        add(key, projectGroupTitle(group), job);
+    }
+    // Order by the discriminated group rank (named first, then All projects,
+    // Cross-project, Operations, Unknown projects), then alphabetically by title
+    // within a rank. Buckets are keyed on the discriminant, never the label, so a
+    // project named "Operations" sorts among the named projects — not with the
+    // no-project special that shares its title.
+    const order = (group) => orderByKey.get(group.key) ?? 0;
+    return [...groups.values()].sort((a, b) => order(a) - order(b) || a.title.localeCompare(b.title));
+}
+/** commander repeatable-option collector for --project. */
+function collectProject(value, previous) {
+    return previous.concat([value]);
+}
 function renderRoutineRows({ jobs, scheduler, overdueSet, link, now, local = true }) {
     const NAME_W = 24;
     const AGENT_W = 10;
@@ -512,11 +547,11 @@ export function registerRoutinesCommands(program) {
         .command('list')
         .description('See all scheduled jobs, when they run next, and their last execution status')
         .option('--json', 'Emit machine-readable JSON instead of the table (used by the menu bar helper)')
-        .option('--group-by <field>', 'Group table output by device (default for terminal output)')
+        .option('--group-by <field>', 'Group output by field: project (default) or device', 'project')
         .option('--flat', 'Print the legacy flat table instead of grouped sections')
         .action((options) => {
-        if (options.groupBy && options.groupBy !== 'device') {
-            console.error(chalk.red(`Unsupported --group-by '${options.groupBy}'. Use: device`));
+        if (options.groupBy && options.groupBy !== 'device' && options.groupBy !== 'project') {
+            console.error(chalk.red(`Unsupported --group-by '${options.groupBy}'. Use: project (default) or device`));
             process.exit(1);
         }
         try {
@@ -548,6 +583,7 @@ export function registerRoutinesCommands(program) {
         // The menu bar helper relies on this so it never reimplements cron math.
         if (options.json) {
             const nowJson = new Date();
+            const knownProjectNames = new Set(listProjectDefs().map((p) => p.name));
             const payload = jobs.map((job) => {
                 const latestRun = localLatestRun(job);
                 const enabledDevices = devicesWithRoutineEnabled(job.name);
@@ -582,6 +618,8 @@ export function registerRoutinesCommands(program) {
                     failureReason: latestRun?.errorMessage ?? null,
                     lastRunStartedAt: latestRun?.startedAt ?? null,
                     lastRunCompletedAt: latestRun?.completedAt ?? null,
+                    projects: job.projects ?? [],
+                    projectGroup: computeProjectGroup(job.projects, knownProjectNames),
                 };
             });
             scheduler.stopAll();
@@ -597,7 +635,7 @@ export function registerRoutinesCommands(program) {
         if (options.flat) {
             renderRoutineRows({ jobs, scheduler, overdueSet, link, now });
         }
-        else {
+        else if (options.groupBy === 'device') {
             let registry = {};
             try {
                 registry = loadDevicesSync();
@@ -615,6 +653,15 @@ export function registerRoutinesCommands(program) {
                 console.log(chalk.gray('  Last Status is per-device: rows under another device show "-" — read it there with: agents routines list --device <name>'));
             }
         }
+        else {
+            // Default: group by project
+            const knownProjectNames = new Set(listProjectDefs().map((p) => p.name));
+            const groups = groupRoutineJobsByProject(jobs, knownProjectNames);
+            for (const group of groups) {
+                console.log(chalk.bold(`\n${group.title}`));
+                renderRoutineRows({ jobs: group.jobs, scheduler, overdueSet, link, now });
+            }
+        }
         if (overdueSet.size > 0) {
             console.log();
             console.log(chalk.yellow(`  ${overdueSet.size} routine(s) overdue — catch up with: agents routines catchup`));
@@ -651,6 +698,8 @@ export function registerRoutinesCommands(program) {
         .option('--no-catchup', 'Do not run this routine late if its fire is missed (daemon down/asleep). The miss is still recorded. For routines whose value expires with their slot, e.g. a 9am brief.')
         .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).')
+        .option('--project <name>', 'Associate with a named project (repeatable; use --all-projects for all)', collectProject, [])
+        .option('--all-projects', 'Associate this routine with all defined projects (sets projects: ["*"])')
         .option('--json', 'Emit machine-readable JSON with the created routine id and status')
         .action(async (nameOrPath, options) => {
         // Check if inline mode (has flags) or file mode
@@ -719,6 +768,34 @@ export function registerRoutinesCommands(program) {
             if (options.devices !== undefined) {
                 devices = await parseAndValidateDevices(options.devices);
             }
+            // Parse and validate --project / --all-projects.
+            let projects;
+            if (options.allProjects) {
+                if (options.project && options.project.length > 0) {
+                    console.error(chalk.red('--all-projects and --project are mutually exclusive'));
+                    process.exit(1);
+                }
+                projects = ['*'];
+            }
+            else if (options.project && options.project.length > 0) {
+                // Validate each name: format check then existence check against defined projects.
+                for (const name of options.project) {
+                    if (!isSafeProjectName(name)) {
+                        console.error(chalk.red(`Invalid project name "${name}": must start with a letter or digit, contain only letters, digits, dots, hyphens, or underscores`));
+                        process.exit(1);
+                    }
+                }
+                // Deduplicate at the same canonical boundary writeJob uses, so the
+                // add path and a hand-authored YAML land identical persisted forms.
+                const deduped = normalizeProjects(options.project) ?? [];
+                const knownProjectNames = new Set(listProjectDefs().map((p) => p.name));
+                const unknown = deduped.filter((n) => !knownProjectNames.has(n));
+                if (unknown.length > 0) {
+                    console.error(chalk.red(`Unknown project(s): ${unknown.join(', ')}. Define them first with: agents projects add`));
+                    process.exit(1);
+                }
+                projects = deduped;
+            }
             let hostStrategy;
             try {
                 hostStrategy = parseHostStrategy(options.placement) ?? undefined;
@@ -755,6 +832,7 @@ export function registerRoutinesCommands(program) {
                 ...(options.catchup === false ? { catchup: false } : {}),
                 ...(options.endAt ? { endAt: options.endAt } : {}),
                 ...(options.resume ? { resume: options.resume } : {}),
+                ...(projects ? { projects } : {}),
             };
             const errors = validateJob(config);
             if (errors.length > 0) {

package/dist/commands/secrets.js

@@ -2307,7 +2307,13 @@ Examples:
                     caller: `command ${cmd}`,
                     keys: keysSubset,
                     allowExpired: execOpts.allowExpired,
-                    agentOnly: true,
+                    // An explicit `secrets exec` at a real terminal is a deliberate use of
+                    // the values: an unlocked bundle runs silently, a locked one resolves
+                    // with one Touch ID sheet, then the command runs with the secrets
+                    // injected. Under an agent (AGENTS_RUNTIME) or headless (no TTY) it
+                    // stays broker-only and points at the explicit unlock command instead
+                    // of raising a sheet — so release/CI scripts never prompt.
+                    agentOnly: isHeadlessSecretsContext() || !isInteractiveTerminal(),
                 }).env;
             }
             const { spawn } = await import('child_process');

package/dist/lib/agents.d.ts

@@ -302,6 +302,47 @@ export declare function __resetAntigravityKeychainCacheForTest(): void;
  * Sync, no Keychain, no network — safe on the `agents run` hot path.
  */
 export declare function isClaudeCredentialFileBlank(base: string, platform?: NodeJS.Platform): boolean;
+/**
+ * Identity of the Claude account a version home is (or was) logged into, read
+ * straight from `.claude.json`'s `oauthAccount`.
+ *
+ * Deliberately independent of whether the credential still works. `getAccountInfo`
+ * applies a credential floor so `agents view` and rotation route around an install
+ * that would die at spawn; attribution of *history* must not. A transcript written
+ * under an org is still that org's work after the token is revoked or the home is
+ * trashed, and on Linux/Windows the floor would otherwise erase the identity of
+ * every retired home (`isClaudeCredentialFileBlank` short-circuits only on darwin).
+ */
+export interface ClaudeHomeIdentity {
+    email: string | null;
+    accountId: string | null;
+    organizationId: string | null;
+    organizationName: string | null;
+    organizationType: string | null;
+    /**
+     * Org-scoped identity — the rate-limit bucket, and the correct key to group by.
+     * Two orgs under one email (a Team seat and a personal Max plan) are separate
+     * buckets and MUST stay distinct; see `candidateIdentity` in lib/rotate.ts.
+     */
+    usageKey: string | null;
+    /** Account+org identity, narrower than `usageKey`. */
+    accountKey: string | null;
+}
+/** A version home's `.claude.json` plus the identity derived from it. */
+export interface ClaudeHomeConfig {
+    /** The config file actually read. */
+    path: string;
+    config: Record<string, any>;
+    identity: ClaudeHomeIdentity;
+}
+/**
+ * Read a Claude home's config and account identity. Returns null when the home has
+ * no readable `.claude.json`, or has one with no `oauthAccount` (never signed in).
+ *
+ * Sync because the session scanner calls it once per home on a hot path, and the
+ * file is a few KB of local JSON. No Keychain access — see `getAccountInfo`.
+ */
+export declare function readClaudeHomeConfig(base: string): ClaudeHomeConfig | null;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,

package/dist/lib/agents.js

@@ -1482,6 +1482,50 @@ export function isClaudeCredentialFileBlank(base, platform = process.platform) {
         return false;
     }
 }
+/**
+ * Read a Claude home's config and account identity. Returns null when the home has
+ * no readable `.claude.json`, or has one with no `oauthAccount` (never signed in).
+ *
+ * Sync because the session scanner calls it once per home on a hot path, and the
+ * file is a few KB of local JSON. No Keychain access — see `getAccountInfo`.
+ */
+export function readClaudeHomeConfig(base) {
+    // Claude reads/writes config at $CLAUDE_CONFIG_DIR/.claude.json when set, falling
+    // back to $HOME/.claude.json. Our shim sets CLAUDE_CONFIG_DIR to the per-version
+    // .claude dir, so prefer that file; fall back to home-level for versions ever
+    // launched without the shim (IDE extension, direct binary).
+    const configDirFile = path.join(base, '.claude', '.claude.json');
+    const homeLevelFile = path.join(base, '.claude.json');
+    const activeFile = fs.existsSync(configDirFile) ? configDirFile : homeLevelFile;
+    let config;
+    try {
+        config = JSON.parse(fs.readFileSync(activeFile, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    const oa = config.oauthAccount;
+    if (!oa)
+        return null;
+    const accountId = normalizeIdentityPart(oa.accountUuid);
+    const organizationId = normalizeIdentityPart(oa.organizationUuid);
+    return {
+        path: activeFile,
+        config,
+        identity: {
+            email: oa.emailAddress || null,
+            accountId,
+            organizationId,
+            organizationName: oa.organizationName ?? null,
+            organizationType: oa.organizationType ?? null,
+            usageKey: buildIdentityKey('claude', [['org', organizationId]]),
+            accountKey: buildIdentityKey('claude', [
+                ['account', accountId],
+                ['org', organizationId],
+            ]),
+        },
+    };
+}
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {
@@ -1506,18 +1550,16 @@ export async function getAccountInfo(agentId, home) {
     try {
         switch (agentId) {
             case 'claude': {
-                // Claude reads/writes config at $CLAUDE_CONFIG_DIR/.claude.json when set,
-                // falling back to $HOME/.claude.json. Our shim sets CLAUDE_CONFIG_DIR to
-                // the per-version .claude dir, so prefer that file; fall back to home-level
-                // for versions ever launched without the shim (IDE extension, direct binary).
-                const configDirFile = path.join(base, '.claude', '.claude.json');
-                const homeLevelFile = path.join(base, '.claude.json');
-                const activeFile = fs.existsSync(configDirFile) ? configDirFile : homeLevelFile;
-                const data = JSON.parse(await fs.promises.readFile(activeFile, 'utf-8'));
+                // Identity extraction is shared with the session scanner's account
+                // attribution — see readClaudeHomeConfig. A home with no readable config or
+                // no oauthAccount is signed out, which is what the pre-refactor code
+                // produced when JSON.parse threw or oauthAccount was absent.
+                const claudeHome = readClaudeHomeConfig(base);
+                if (!claudeHome)
+                    return { ...empty, lastActive };
+                const { config: data, identity } = claudeHome;
                 const oa = data.oauthAccount;
-                const accountId = normalizeIdentityPart(oa?.accountUuid);
-                const organizationId = normalizeIdentityPart(oa?.organizationUuid);
-                const email = oa?.emailAddress || null;
+                const { accountId, organizationId, email, accountKey, usageKey } = identity;
                 // Credential floor: a blanked credential file means this home cannot
                 // authenticate, whatever `.claude.json` still says. Report it signed out
                 // so `agents view` prompts a re-login and rotation routes around it,
@@ -1525,11 +1567,6 @@ export async function getAccountInfo(agentId, home) {
                 if (email && isClaudeCredentialFileBlank(base)) {
                     return { ...empty, lastActive };
                 }
-                const accountKey = buildIdentityKey(agentId, [
-                    ['account', accountId],
-                    ['org', organizationId],
-                ]);
-                const usageKey = buildIdentityKey(agentId, [['org', organizationId]]);
                 // Plan tier is derived from .claude.json's organizationType, which carries
                 // the TRUE tier (claude_max → "Max", claude_pro → "Pro", claude_team →
                 // "Team") and is already in-hand from the config we just read — no Keychain

package/dist/lib/routines.d.ts

@@ -227,7 +227,87 @@ export interface JobConfig {
      * RUSH-2020.
      */
     actor?: string;
+    /**
+     * Named projects this routine belongs to. Metadata-only: organises the
+     * routine under a project group in `agents routines list` and the menu bar;
+     * has no effect on scheduling or execution.
+     *
+     * Special values:
+     * - `["*"]` — routine applies to all defined projects (the "All projects" group).
+     * - A single name — routine belongs to that specific project.
+     * - Multiple names — routine spans several projects ("Cross-project" group).
+     * - Absent/empty — routine belongs to no project ("Operations" group).
+     */
+    projects?: string[];
 }
+/**
+ * Canonical form of a routine's `projects` field: drop non-string and empty
+ * entries and deduplicate while preserving first-seen order. This is the single
+ * source of truth for project-name normalization, applied at the schema
+ * boundary (`writeJob` before persistence) and at grouping (`computeProjectGroupKind`)
+ * so a hand-authored YAML with duplicates (`projects: [myapp, myapp]`) is
+ * treated identically to the canonical single-entry form everywhere.
+ *
+ * Returns `undefined` when nothing survives, so callers can omit the field.
+ */
+export declare function normalizeProjects(projects: string[] | undefined): string[] | undefined;
+/**
+ * A routine's project bucket, discriminated by `kind` so buckets are never keyed
+ * on their human display label. A named project called literally "Operations" or
+ * "Cross-project" is `{ kind: 'named', name }` and can never collide with the
+ * `operations` / `cross` special buckets that happen to share those titles.
+ */
+export type ProjectGroup = {
+    kind: 'named';
+    name: string;
+} | {
+    kind: 'all';
+} | {
+    kind: 'cross';
+} | {
+    kind: 'operations';
+} | {
+    kind: 'unknown';
+};
+/**
+ * Classify a routine's `projects` field into a discriminated {@link ProjectGroup}.
+ * Duplicates are collapsed first ({@link normalizeProjects}), so `[myapp, myapp]`
+ * is a single named project, not a "Cross-project" span.
+ *
+ * @param projects - The routine's projects array (may be undefined).
+ * @param knownProjectNames - The set of currently defined project names (from `listProjectDefs`).
+ */
+export declare function computeProjectGroupKind(projects: string[] | undefined, knownProjectNames: Set<string>): ProjectGroup;
+/** Human display title for a {@link ProjectGroup}. */
+export declare function projectGroupTitle(group: ProjectGroup): string;
+/**
+ * Stable bucket key for a {@link ProjectGroup}. Named projects key on their name
+ * under a `named:` prefix; specials key on their `kind` under a `special:` prefix.
+ * The two namespaces can never collide, so a project named "Operations" gets its
+ * own bucket separate from the no-project "Operations" special.
+ */
+export declare function projectGroupKey(group: ProjectGroup): string;
+/** Sort rank for a {@link ProjectGroup}: named projects first, then specials in a fixed order. */
+export declare function projectGroupOrder(group: ProjectGroup): number;
+/**
+ * Compute the display group label for a routine's `projects` field.
+ *
+ * Kept as the label-returning form for the JSON `projectGroup` field and any
+ * text consumer; grouping and ordering use the discriminated
+ * {@link computeProjectGroupKind}/{@link projectGroupKey} instead so buckets are
+ * never keyed on the label.
+ *
+ * @param projects - The routine's projects array (may be undefined).
+ * @param knownProjectNames - The set of currently defined project names (from `listProjectDefs`).
+ *
+ * Returns one of:
+ * - A specific project name — when `projects` has exactly one known name.
+ * - `"All projects"` — when `projects` is `["*"]`.
+ * - `"Cross-project"` — when `projects` has multiple distinct known entries.
+ * - `"Operations"` — when `projects` is absent or empty.
+ * - `"Unknown projects"` — when any entry is no longer a defined project (stale).
+ */
+export declare function computeProjectGroup(projects: string[] | undefined, knownProjectNames: Set<string>): string;
 /** Metadata for a single job execution, persisted as JSON in the run directory. */
 export interface RunMeta {
     jobName: string;