@phnx-labs/agents-cli 1.22.18 → 1.22.20

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;

package/dist/lib/routines.js

@@ -12,6 +12,7 @@ import * as yaml from 'yaml';
 import { Cron } from 'croner';
 import { getRoutinesDir, getSystemRoutinesDir, getRunsDir, ensureAgentsDir, getProjectRoutinesDir } from './state.js';
 import { safeJoin, isSafeSegmentName } from './paths.js';
+import { isSafeProjectName } from './projects.js';
 import { atomicWriteFileSync } from './fs-atomic.js';
 import { ALL_AGENT_IDS } from './agents.js';
 import { machineId, normalizeHost } from './machine-id.js';
@@ -54,6 +55,93 @@ export function normalizeTriggerEvent(input) {
     };
     return aliases[key] ?? null;
 }
+/**
+ * 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 function normalizeProjects(projects) {
+    if (!Array.isArray(projects) || projects.length === 0)
+        return undefined;
+    const out = [...new Set(projects.filter((p) => typeof p === 'string' && p !== ''))];
+    return out.length === 0 ? undefined : out;
+}
+/**
+ * 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 function computeProjectGroupKind(projects, knownProjectNames) {
+    const norm = normalizeProjects(projects);
+    if (!norm)
+        return { kind: 'operations' };
+    if (norm.length === 1 && norm[0] === '*')
+        return { kind: 'all' };
+    const hasUnknown = norm.some((p) => p !== '*' && !knownProjectNames.has(p));
+    if (hasUnknown)
+        return { kind: 'unknown' };
+    if (norm.length === 1)
+        return { kind: 'named', name: norm[0] };
+    return { kind: 'cross' };
+}
+/** Human display title for a {@link ProjectGroup}. */
+export function projectGroupTitle(group) {
+    switch (group.kind) {
+        case 'named': return group.name;
+        case 'all': return 'All projects';
+        case 'cross': return 'Cross-project';
+        case 'operations': return 'Operations';
+        case 'unknown': return 'Unknown projects';
+    }
+}
+/**
+ * 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 function projectGroupKey(group) {
+    return group.kind === 'named' ? `named:${group.name}` : `special:${group.kind}`;
+}
+/** Sort rank for a {@link ProjectGroup}: named projects first, then specials in a fixed order. */
+export function projectGroupOrder(group) {
+    switch (group.kind) {
+        case 'named': return 0;
+        case 'all': return 1;
+        case 'cross': return 2;
+        case 'operations': return 3;
+        case 'unknown': return 4;
+    }
+}
+/**
+ * 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 function computeProjectGroup(projects, knownProjectNames) {
+    return projectGroupTitle(computeProjectGroupKind(projects, knownProjectNames));
+}
 /**
  * Finalize a run record with a terminal status, computing `duration` from
  * `startedAt` and the completion timestamp. Keeps failure-reason population
@@ -386,6 +474,15 @@ export function writeJob(config) {
     if (output.catchup === true || output.catchup === undefined)
         delete output.catchup;
     delete output.devices;
+    // Persist projects in canonical form: deduplicated, first-seen order, field
+    // omitted when nothing survives. This is the schema boundary, so a routine
+    // written from any path (add, edit, enable/disable re-write) lands canonical
+    // regardless of how the caller assembled the array.
+    const normProjects = normalizeProjects(output.projects);
+    if (normProjects)
+        output.projects = normProjects;
+    else
+        delete output.projects;
     let existingText = null;
     if (ymlExists || yamlExists) {
         try {
@@ -627,6 +724,29 @@ export function validateJob(config) {
     if (config.catchup !== undefined && typeof config.catchup !== 'boolean') {
         errors.push('catchup must be a boolean (false to skip running a missed fire late)');
     }
+    if (config.projects !== undefined) {
+        if (!Array.isArray(config.projects)) {
+            errors.push('projects must be an array of project names (or ["*"] for all projects)');
+        }
+        else if (config.projects.length === 1 && config.projects[0] === '*') {
+            // ["*"] is valid: "all projects" sentinel
+        }
+        else if (config.projects.includes('*')) {
+            errors.push('projects: "*" (all projects) must be the sole entry');
+        }
+        else {
+            for (const p of config.projects) {
+                if (typeof p !== 'string' || p.trim() === '') {
+                    errors.push('each entry in projects must be a non-empty project name');
+                    break;
+                }
+                if (!isSafeProjectName(p)) {
+                    errors.push(`invalid project name "${p}": must start with a letter or digit, contain only letters, digits, dots, hyphens, or underscores`);
+                    break;
+                }
+            }
+        }
+    }
     return errors;
 }
 /** Validate a job trigger block, returning a list of human-readable errors. */

package/dist/lib/session/claude-accounts.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Which Claude account produced a transcript.
+ *
+ * A Claude `.jsonl` records `sessionId`, `cwd`, `version`, `gitBranch` and per-message
+ * `usage`, but carries **no account identity** — no `accountUuid`, no
+ * `organizationUuid`, no email. What agents-cli does have is the version layout: every
+ * installed version gets its own home with its own `.claude.json` (`CLAUDE_CONFIG_DIR`
+ * is swapped per version, see lib/exec.ts), so a home identifies an account.
+ *
+ * This matters because the default run strategy is `balanced` (lib/rotate.ts), which
+ * sprays sessions across every signed-in account. Before this module the scanner
+ * resolved ONE email process-globally and stamped it on every Claude session, so a
+ * machine with several accounts reported all of its history under whichever one
+ * happened to resolve first.
+ *
+ * Grouping is keyed on the **org** (`usageKey`), never the email: two orgs under one
+ * email (a Team seat and a personal Max plan) are separate quota buckets and must stay
+ * distinct — the same invariant `candidateIdentity` enforces in lib/rotate.ts.
+ *
+ * ## Evidence tiers
+ *
+ * Attribution is a pure function of (path, recorded version). It performs no per-file
+ * I/O and does not need the transcript to still exist, which is what lets the v33
+ * migration backfill already-indexed rows without re-parsing anything.
+ *
+ * 1. **The path names a home we can identify.** Strongest: the file physically lives in
+ *    that home, including a retired `trash/` snapshot, which keeps its `.claude.json`.
+ * 1b. **The path names a home that exists but is signed out.** Dark, named after that
+ *    home. The location proves which config dir Claude used, so this deliberately beats
+ *    a recorded version — attributing it to some other version's account would be a
+ *    guess dressed as evidence.
+ * 2. **The path is outside every known home, and the row records a version.** Resolve
+ *    that version's own home. Covers the mutable `~/.claude` symlink and the routine
+ *    archives under `<historyDir>/runs` that `readRoutineArchiveMeta` feeds in. The
+ *    symlink's target moves with `agents use`, so "whatever it points at now" is weak
+ *    evidence for old rows: on the machine this was developed against only 684 of 1,334
+ *    such rows came from the version the symlink currently names, and 322 came from
+ *    versions belonging to a *different* org.
+ * 3. **Under the symlink with no recorded version at all.** Its current target is the
+ *    only evidence there is, and the bucket says so via `evidence`. A version that IS
+ *    recorded but resolves to no home stops at tier 2 and stays dark — it never
+ *    reaches here.
+ * 4. **None of the above.** An explicitly dark bucket, labelled with why. Never folded
+ *    into a real account and never dropped.
+ *
+ * ## Harness scope: Claude only, deliberately
+ *
+ * Attribution is implemented for Claude and no other harness. It depends on the
+ * per-version home carrying an `oauthAccount` in `.claude.json`, which is what makes a
+ * home equal an account. The other harnesses do have per-version credential files
+ * (`CREDENTIAL_FILE_SEGMENTS` in lib/agents.ts), so the mechanism generalizes — codex
+ * stores an `auth.json` JWT, gemini a `google_accounts.json` — but each needs its own
+ * identity extractor and its own notion of a quota bucket, and none of them has the
+ * two-orgs-one-email problem that motivated keying on the org here.
+ *
+ * Until that lands, a non-Claude session has a NULL `account_key` and rolls up under
+ * `unattributed:<agent>` — named after its harness rather than implying we tried and
+ * failed. `--by account` on `agents cost` / `agents output` therefore reports Claude
+ * accounts plus one bucket per other harness.
+ */
+/** The account a transcript is attributed to. */
+export interface ClaudeAccountBucket {
+    /**
+     * Stable grouping key. For an attributed bucket this is the org-scoped `usageKey`
+     * (e.g. `claude:org=<uuid>`). For an unattributed one it is `unattributed:<reason>`
+     * so distinct dark sources never merge into each other or into a real account.
+     */
+    key: string;
+    /** True when the key came from a real `oauthAccount`. */
+    attributed: boolean;
+    email: string | null;
+    orgName: string | null;
+    /** "Team", "Max", "Pro", … derived from `organizationType`. */
+    plan: string | null;
+    /** Display string: org and email, or the reason a bucket is dark. */
+    label: string;
+    /** Which evidence tier produced this attribution. */
+    evidence: 'version-home' | 'recorded-version' | 'symlink-target' | 'none';
+}
+interface HomeEntry {
+    /** Literal path prefix a transcript must start with to belong to this home. */
+    prefix: string;
+    bucket: ClaudeAccountBucket;
+}
+/** Resolver over the Claude homes present on this machine. */
+export interface ClaudeAccountIndex {
+    /** Version- and trash-home prefixes, longest first. Excludes the `~/.claude` symlink. */
+    entries: HomeEntry[];
+    /**
+     * Config-dir prefixes of homes that exist but carry no `oauthAccount`. Kept
+     * separately from `entries` so a transcript living in a signed-out home is reported
+     * against THAT home rather than falling through to its recorded version: the file's
+     * location is what proves which config dir Claude was pointed at.
+     */
+    darkHomes: Array<{
+        prefix: string;
+        version: string | null;
+    }>;
+    /**
+     * Claude CLI version → the account that version ran as. `'ambiguous'` when retired
+     * snapshots of one version disagree and no live home settles it, which is reported
+     * as dark rather than guessed.
+     */
+    byVersion: Map<string, ClaudeAccountBucket | 'ambiguous'>;
+    /** Whatever `~/.claude` points at right now; tier-3 evidence only. */
+    symlinkBucket: ClaudeAccountBucket | null;
+    /** Literal prefix of the live symlinked config dir. */
+    symlinkPrefix: string;
+}
+/**
+ * Enumerate every Claude home that could own an indexed transcript. Includes retired
+ * `trash/` snapshots: they keep their `.claude.json`, so a transcript indexed before
+ * its version was rotated out stays attributable.
+ */
+export declare function buildClaudeAccountIndex(): ClaudeAccountIndex;
+/**
+ * The account bucket a transcript belongs to. `recordedVersion` is the Claude CLI
+ * version stored on the session row (`sessions.version`), which is what disambiguates
+ * rows sitting under the mutable `~/.claude` symlink.
+ *
+ * Never returns null: a transcript that matches no known home resolves to an
+ * explicitly dark bucket rather than being dropped or folded into a real account.
+ * Backup mirrors (`<historyDir>/backups/claude/<stamp>/projects/…`) carry no
+ * `.claude.json` of their own, so they resolve by recorded version like any other
+ * out-of-home path, and go dark only when that version names no home.
+ */
+export declare function resolveClaudeAccount(index: ClaudeAccountIndex, filePath: string, recordedVersion?: string | null): ClaudeAccountBucket;
+export {};

package/dist/lib/session/claude-accounts.js

@@ -0,0 +1,244 @@
+/**
+ * Which Claude account produced a transcript.
+ *
+ * A Claude `.jsonl` records `sessionId`, `cwd`, `version`, `gitBranch` and per-message
+ * `usage`, but carries **no account identity** — no `accountUuid`, no
+ * `organizationUuid`, no email. What agents-cli does have is the version layout: every
+ * installed version gets its own home with its own `.claude.json` (`CLAUDE_CONFIG_DIR`
+ * is swapped per version, see lib/exec.ts), so a home identifies an account.
+ *
+ * This matters because the default run strategy is `balanced` (lib/rotate.ts), which
+ * sprays sessions across every signed-in account. Before this module the scanner
+ * resolved ONE email process-globally and stamped it on every Claude session, so a
+ * machine with several accounts reported all of its history under whichever one
+ * happened to resolve first.
+ *
+ * Grouping is keyed on the **org** (`usageKey`), never the email: two orgs under one
+ * email (a Team seat and a personal Max plan) are separate quota buckets and must stay
+ * distinct — the same invariant `candidateIdentity` enforces in lib/rotate.ts.
+ *
+ * ## Evidence tiers
+ *
+ * Attribution is a pure function of (path, recorded version). It performs no per-file
+ * I/O and does not need the transcript to still exist, which is what lets the v33
+ * migration backfill already-indexed rows without re-parsing anything.
+ *
+ * 1. **The path names a home we can identify.** Strongest: the file physically lives in
+ *    that home, including a retired `trash/` snapshot, which keeps its `.claude.json`.
+ * 1b. **The path names a home that exists but is signed out.** Dark, named after that
+ *    home. The location proves which config dir Claude used, so this deliberately beats
+ *    a recorded version — attributing it to some other version's account would be a
+ *    guess dressed as evidence.
+ * 2. **The path is outside every known home, and the row records a version.** Resolve
+ *    that version's own home. Covers the mutable `~/.claude` symlink and the routine
+ *    archives under `<historyDir>/runs` that `readRoutineArchiveMeta` feeds in. The
+ *    symlink's target moves with `agents use`, so "whatever it points at now" is weak
+ *    evidence for old rows: on the machine this was developed against only 684 of 1,334
+ *    such rows came from the version the symlink currently names, and 322 came from
+ *    versions belonging to a *different* org.
+ * 3. **Under the symlink with no recorded version at all.** Its current target is the
+ *    only evidence there is, and the bucket says so via `evidence`. A version that IS
+ *    recorded but resolves to no home stops at tier 2 and stays dark — it never
+ *    reaches here.
+ * 4. **None of the above.** An explicitly dark bucket, labelled with why. Never folded
+ *    into a real account and never dropped.
+ *
+ * ## Harness scope: Claude only, deliberately
+ *
+ * Attribution is implemented for Claude and no other harness. It depends on the
+ * per-version home carrying an `oauthAccount` in `.claude.json`, which is what makes a
+ * home equal an account. The other harnesses do have per-version credential files
+ * (`CREDENTIAL_FILE_SEGMENTS` in lib/agents.ts), so the mechanism generalizes — codex
+ * stores an `auth.json` JWT, gemini a `google_accounts.json` — but each needs its own
+ * identity extractor and its own notion of a quota bucket, and none of them has the
+ * two-orgs-one-email problem that motivated keying on the org here.
+ *
+ * Until that lands, a non-Claude session has a NULL `account_key` and rolls up under
+ * `unattributed:<agent>` — named after its harness rather than implying we tried and
+ * failed. `--by account` on `agents cost` / `agents output` therefore reports Claude
+ * accounts plus one bucket per other harness.
+ */
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+import { readClaudeHomeConfig } from '../agents.js';
+import { getAgentsDir, getHistoryDir } from '../state.js';
+const HOME = os.homedir();
+const VERSIONS_ROOTS = [getHistoryDir(), getAgentsDir()];
+/** `claude_team` → "Team", `claude_max` → "Max". Mirrors lib/agents.ts's label logic. */
+function planFromOrgType(orgType) {
+    if (!orgType)
+        return null;
+    const m = /^claude_(.+)$/.exec(orgType);
+    if (!m)
+        return orgType;
+    return m[1].charAt(0).toUpperCase() + m[1].slice(1);
+}
+function bucketForHome(home, evidence) {
+    const cfg = readClaudeHomeConfig(home);
+    if (!cfg)
+        return null;
+    const { email, organizationName: orgName, usageKey, accountKey, organizationType } = cfg.identity;
+    // No org uuid means no quota bucket to key on. Fall back to the narrower account key,
+    // then the email — an identity we cannot key is not one we should guess at.
+    const key = usageKey ?? accountKey ?? (email ? `claude:email=${email}` : null);
+    if (!key)
+        return null;
+    return {
+        key,
+        attributed: true,
+        email,
+        orgName,
+        plan: planFromOrgType(organizationType),
+        label: orgName && email ? `${orgName} <${email}>` : (orgName ?? email ?? key),
+        evidence,
+    };
+}
+/** A dark bucket, labelled by why it is dark so two dark sources never merge. */
+function unattributed(reason) {
+    return {
+        key: `unattributed:${reason}`,
+        attributed: false,
+        email: null,
+        orgName: null,
+        plan: null,
+        label: `unattributed (${reason})`,
+        evidence: 'none',
+    };
+}
+function listDirs(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() || e.isSymbolicLink())
+            .map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Enumerate every Claude home that could own an indexed transcript. Includes retired
+ * `trash/` snapshots: they keep their `.claude.json`, so a transcript indexed before
+ * its version was rotated out stays attributable.
+ */
+export function buildClaudeAccountIndex() {
+    const entries = [];
+    const darkHomes = [];
+    const liveByVersion = new Map();
+    const trashByVersion = new Map();
+    const addHome = (home, version, retired) => {
+        const bucket = bucketForHome(home, 'version-home');
+        if (!bucket) {
+            // The home exists on disk but has no usable identity. Record its prefix so
+            // resolution can name it instead of guessing from a recorded version.
+            if (fs.existsSync(path.join(home, '.claude'))) {
+                darkHomes.push({ prefix: path.join(home, '.claude'), version });
+            }
+            return;
+        }
+        entries.push({ prefix: path.join(home, '.claude'), bucket });
+        if (!version)
+            return;
+        if (retired) {
+            const list = trashByVersion.get(version) ?? [];
+            list.push(bucket);
+            trashByVersion.set(version, list);
+        }
+        else {
+            liveByVersion.set(version, bucket);
+        }
+    };
+    for (const root of VERSIONS_ROOTS) {
+        const versionsBase = path.join(root, 'versions', 'claude');
+        for (const version of listDirs(versionsBase)) {
+            addHome(path.join(versionsBase, version, 'home'), version, false);
+        }
+    }
+    // Retired homes: <historyDir>/trash/versions/claude/<version>/<timestamp>/home
+    const trashBase = path.join(getHistoryDir(), 'trash', 'versions', 'claude');
+    for (const version of listDirs(trashBase)) {
+        for (const stamp of listDirs(path.join(trashBase, version))) {
+            addHome(path.join(trashBase, version, stamp, 'home'), version, true);
+        }
+    }
+    // A live home is authoritative for its version. Otherwise the retired snapshots
+    // decide, but only when they agree — disagreement is reported, not resolved.
+    const byVersion = new Map();
+    for (const [version, list] of trashByVersion) {
+        const keys = new Set(list.map((b) => b.key));
+        byVersion.set(version, keys.size === 1 ? { ...list[0], evidence: 'recorded-version' } : 'ambiguous');
+    }
+    for (const [version, bucket] of liveByVersion) {
+        byVersion.set(version, { ...bucket, evidence: 'recorded-version' });
+    }
+    // Longest prefix first so a nested home beats a shorter ancestor.
+    entries.sort((a, b) => b.prefix.length - a.prefix.length);
+    darkHomes.sort((a, b) => b.prefix.length - a.prefix.length);
+    return {
+        entries,
+        darkHomes,
+        byVersion,
+        symlinkBucket: bucketForHome(HOME, 'symlink-target'),
+        symlinkPrefix: path.join(HOME, '.claude'),
+    };
+}
+/** Version segment of a versions/ or trash/ path, for labelling dark buckets. */
+function versionFromPath(filePath) {
+    const m = /[/\\]versions[/\\]claude[/\\]([^/\\]+)[/\\]/.exec(filePath);
+    return m ? m[1] : null;
+}
+/**
+ * The account bucket a transcript belongs to. `recordedVersion` is the Claude CLI
+ * version stored on the session row (`sessions.version`), which is what disambiguates
+ * rows sitting under the mutable `~/.claude` symlink.
+ *
+ * Never returns null: a transcript that matches no known home resolves to an
+ * explicitly dark bucket rather than being dropped or folded into a real account.
+ * Backup mirrors (`<historyDir>/backups/claude/<stamp>/projects/…`) carry no
+ * `.claude.json` of their own, so they resolve by recorded version like any other
+ * out-of-home path, and go dark only when that version names no home.
+ */
+export function resolveClaudeAccount(index, filePath, recordedVersion) {
+    // Tier 1 — the file physically lives in a home we can identify.
+    for (const entry of index.entries) {
+        if (filePath.startsWith(entry.prefix + path.sep))
+            return entry.bucket;
+    }
+    // Tier 1b — it lives in a home that exists but is signed out. The location proves
+    // which config dir Claude used, so this beats any recorded version: reporting it
+    // against a *different* version's account would be a guess dressed as evidence.
+    for (const dark of index.darkHomes) {
+        if (filePath.startsWith(dark.prefix + path.sep)) {
+            return unattributed(dark.version ? `signed-out home ${dark.version}` : 'signed-out home');
+        }
+    }
+    // Tier 2 — outside every known home. The recorded version names the home that ran,
+    // which covers both the mutable ~/.claude symlink and the routine/run archives under
+    // <historyDir>/runs that readRoutineArchiveMeta feeds through this same path.
+    if (recordedVersion) {
+        const byVersion = index.byVersion.get(recordedVersion);
+        if (byVersion === 'ambiguous') {
+            return unattributed(`ambiguous history for version ${recordedVersion}`);
+        }
+        if (byVersion)
+            return byVersion;
+        // Recorded but unresolvable — the version was uninstalled and its trash snapshot
+        // pruned. Stay dark. Falling through to the symlink's current target would move
+        // these rows onto whichever account happens to be default now, which is the
+        // inference tier 2 exists to avoid.
+        return unattributed(`no home for version ${recordedVersion}`);
+    }
+    // Tier 3 — under the live symlink with no recorded version at all. Its current
+    // target is the only evidence that exists. A recorded-but-unresolvable version
+    // returned dark from tier 2 above and never arrives here.
+    if (filePath.startsWith(index.symlinkPrefix + path.sep) && index.symlinkBucket) {
+        return index.symlinkBucket;
+    }
+    const version = versionFromPath(filePath);
+    if (version)
+        return unattributed(`signed-out home ${version}`);
+    if (filePath.includes(`${path.sep}backups${path.sep}claude${path.sep}`)) {
+        return unattributed('backup mirror');
+    }
+    return unattributed('unknown home');
+}

package/dist/lib/session/db.d.ts

@@ -12,7 +12,7 @@ import { type IndexedToolCall } from './tool-calls.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/05-sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 32;
+export declare const SCHEMA_VERSION = 33;
 /**
  * Bump to force `agents sessions backfill resources` to re-derive every
  * session's skill/slash-command tallies on its next run (resource_scan_ledger
@@ -30,6 +30,8 @@ export interface SessionRow {
     routine_run_id: string | null;
     version: string | null;
     account: string | null;
+    account_key: string | null;
+    account_org: string | null;
     mode: string | null;
     timestamp: string;
     last_activity: string | null;
@@ -297,8 +299,16 @@ export declare function querySessions(options?: QueryOptions): SessionMeta[];
 export declare function countSessions(options?: QueryOptions): number;
 /** One grouped row in a cost/duration rollup. */
 export interface UsageRollupRow {
-    /** Grouping key value: the agent id, project name, or ISO date (YYYY-MM-DD). */
+    /**
+     * Grouping key value: the agent id, project name, ISO date (YYYY-MM-DD), or
+     * account identity (`claude:org=<uuid>` / `unattributed:<reason>`).
+     */
     key: string;
+    /**
+     * Human label for the key when it is not itself readable — an org uuid is an
+     * identity, not something to show a user. Absent when `key` reads fine on its own.
+     */
+    label?: string;
     costUsd: number;
     durationMs: number;
     sessionCount: number;
@@ -307,7 +317,7 @@ export interface UsageRollupRow {
     outputTokens: number;
 }
 /** What to group a usage rollup by. */
-export type UsageRollupGroup = 'agent' | 'project' | 'day';
+export type UsageRollupGroup = 'agent' | 'project' | 'day' | 'account';
 /**
  * Smart-launch affinity priors: group sessions by origin machine, harness, or
  * joint (machine + agent). Ordered by launch count desc.