@phnx-labs/agents-cli 1.22.6 → 1.22.8

package/dist/commands/projects.js

@@ -23,13 +23,13 @@ import { getActiveSessions } from '../lib/session/active.js';
 import { gatherRemoteActive } from '../lib/session/remote-active.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { factoryProjectsPath } from '../lib/auto-dispatch.js';
-import { formatFleetWorkspaces, parseRemoteProbe, probeProjectWorkspaces, workspaceTargetsForDef, } from '../lib/project-probe.js';
+import { formatFleetWorkspaces, parseRemoteProbe, probeProjectWorkspaces, workspaceTargetsForDef, workspaceWarnings, } from '../lib/project-probe.js';
 import { listProjectDefs, loadProjectDef, writeProjectDef, removeProjectDef, projectDefPath, isSafeProjectName, } from '../lib/projects.js';
-import { rollupSessionsByProject, isDeadStatus, liveDeadSplit, enrichProjectSignals, formatProjectMembers, } from '../lib/project-status.js';
+import { rollupSessionsByProject, withDefaultMachine, isDeadStatus, liveDeadSplit, enrichProjectSignals, formatProjectMembersByHost, formatProjectWarnings, } from '../lib/project-status.js';
 import { fetchLinearProjectCounts } from '../lib/linear-project-counts.js';
 import { listLinearProjects, pickLinearProject } from '../lib/linear-projects.js';
 import { checkRepoSlug } from '../lib/project-doctor.js';
-import { readFocusAreas } from '../lib/project-focus.js';
+import { formatFocusAreas, readFocusAreas } from '../lib/project-focus.js';
 import { formatVerdict, scheduleVerdict } from '../lib/project-schedule.js';
 import { buildFactoryImportCandidates, buildLinearImportCandidates, validateImportOpts, } from '../lib/project-import.js';
 /** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
@@ -232,7 +232,7 @@ export function formatMilestoneLines(milestones, next, nowMs, limit) {
     // an earlier one and hide the actual next behind "+N more", which is the one
     // thing this row exists to say. Identity is name+targetDate: two milestones
     // can share a name, and matching on name alone labelled the wrong row.
-    const key = (m) => `${m.name}${m.targetDate ?? ''}`;
+    const key = (m) => `${m.name}${m.targetDate ?? ''}`;
     const lead = next ? milestones.filter((m) => key(m) === key(next)).slice(0, 1) : [];
     const others = next ? milestones.filter((m) => key(m) !== key(next)) : milestones;
     const ordered = [...lead, ...others];
@@ -291,7 +291,12 @@ function statusBar(r) {
  * artifact log and git focus, and skips just the network calls (`gh`, Linear).
  */
 async function enrichProjectsForRender(defs, all, opts) {
-    const roll = rollupSessionsByProject(all, [...(await getActiveSessions()), ...(opts.extraSessions ?? [])]);
+    // Local getActiveSessions() leaves `machine` unset (the sessions renderer
+    // falls back to this box). Host-grouped agents need an explicit stamp so
+    // under `--fleet` this box does not render as `@local` next to peers that
+    // carry real device ids.
+    const local = withDefaultMachine(await getActiveSessions(), machineId());
+    const roll = rollupSessionsByProject(all, [...local, ...(opts.extraSessions ?? [])]);
     const remote = new Map();
     const linear = new Map();
     // Local git, no API, no rate limit — measured 0.23s over a 897-commit week.
@@ -317,7 +322,12 @@ milestoneLimit = 1,
 /** Directories the window's work landed in, from local git. */
 focus = [], 
 /** `view` mode: the caller prints the stored definition in full afterwards. */
-detail = false) {
+detail = false, 
+/**
+ * Workspace probe rows used only for the warnings footer. May be the full
+ * `--fleet` set or a local-only probe so drift is never silent by default.
+ */
+warnWorkspaces = []) {
     // The headline counts LIVE agents. It used to be every matched session, which
     // read `39 agents` on a project where 19 had crashed. `planPct` used to sit
     // here too and is gone: it summed each session's latest checklist snapshot,
@@ -330,15 +340,18 @@ detail = false) {
     if (split.dead > 0) {
         // Wreckage is worth a number of its own — 19 crashed sessions is a thing to
         // go fix, not a throughput signal to fold into the headline.
-        const detail = split.deadByStatus.map((d) => `${d.n} ${d.status}`).join(', ');
-        console.log(`  ${chalk.dim('dead')}     ${chalk.yellow(`${split.dead} finished or lost`)} ${chalk.dim(`(${detail})`)}`);
+        const deadDetail = split.deadByStatus.map((d) => `${d.n} ${d.status}`).join(', ');
+        console.log(`  ${chalk.dim('dead')}     ${chalk.yellow(`${split.dead} finished or lost`)} ${chalk.dim(`(${deadDetail})`)}`);
     }
-    // Live only. The roster used to list every matched session, so a card headed
-    // `23 live` went on to show `crashed ×25` — the corpses the `dead` row above
-    // already accounts for, counted twice and contradicting the headline.
+    // Live only, grouped by host when machine stamps exist so "who is on which
+    // box" is visible. Flat collapse hid that when harness×status matched across hosts.
     const liveMembers = r?.members.filter((m) => !isDeadStatus(m.status)) ?? [];
-    if (liveMembers.length)
-        console.log(`  ${chalk.dim('agents')}   ${formatProjectMembers(liveMembers)}`);
+    if (liveMembers.length) {
+        const agentLines = formatProjectMembersByHost(liveMembers);
+        agentLines.forEach((line, i) => {
+            console.log(`  ${chalk.dim((i === 0 ? 'agents' : '').padEnd(7))}  ${line}`);
+        });
+    }
     const ships = [];
     if (remote?.mergedPrs) {
         ships.push(chalk.green(`${remote.mergedPrs}${remote.mergedPrsTruncated ? '+' : ''} merged (${remote.windowDays}d)`));
@@ -357,13 +370,15 @@ detail = false) {
     for (const line of formatMilestoneLines(linear?.milestones ?? [], linear?.nextMilestone, nowMs, milestoneLimit)) {
         console.log(line);
     }
-    // What the dates prove — never an invented "on track". See project-schedule.ts.
+    // Informational schedule only. Warn-level verdicts land in the footer so the
+    // bottom of the card is the one place you look for "what needs attention".
     const verdict = linear?.milestones?.length ? formatVerdict(scheduleVerdict(linear.milestones, nowMs)) : undefined;
-    if (verdict) {
-        console.log(`  ${chalk.dim('schedule')} ${verdict.warn ? chalk.yellow(verdict.text) : verdict.text}`);
+    if (verdict && !verdict.warn) {
+        console.log(`  ${chalk.dim('schedule')} ${verdict.text}`);
     }
     if (focus.length) {
-        console.log(`  ${chalk.dim('focus')}    ${focus.map((f) => `${f.path} ${chalk.dim(String(f.touches))}`).join(chalk.dim('  ·  '))}`);
+        const windowDays = remote?.windowDays ?? 7;
+        console.log(`  ${chalk.dim('focus')}    ${formatFocusAreas(focus, windowDays)}`);
     }
     if (r && r.tickets.length) {
         console.log(`  ${chalk.dim('tickets')}  ${r.tickets.slice(0, 8).join(' · ')}${r.tickets.length > 8 ? ' …' : ''}`);
@@ -384,14 +399,29 @@ detail = false) {
     const repos = [def.repo, ...(def.repos ?? []).map((x) => x.slug)].filter(Boolean);
     if (repos.length)
         console.log(`  ${chalk.dim('repos')}    ${[...new Set(repos)].join(' · ')}`);
-    // A def whose `repo` disagrees with the checkout's origin reads PR and release
-    // counts from a DIFFERENT repository — both slugs resolve, so nothing errors
-    // and the wrong numbers look right. Say it here, with the fix attached.
+    // Warnings footer — critical (🔴) then continue (⚠️). Sources: repo slug
+    // mismatch, workspace drift/dirty/missing, schedule that cannot measure.
+    const warnings = [];
     const mismatch = def.root ? checkRepoSlug(def, originSlug(expandLocalHome(def.root))) : undefined;
     if (mismatch) {
-        console.log(`  ${chalk.yellow('!')}        ${chalk.yellow(mismatch.message)}`);
-        console.log(`  ${' '.repeat(8)}${chalk.gray(mismatch.remediation)}`);
+        warnings.push({ severity: 'critical', text: mismatch.message, remediation: mismatch.remediation });
+    }
+    for (const w of workspaceWarnings(warnWorkspaces)) {
+        warnings.push(w);
     }
+    if (verdict?.warn) {
+        warnings.push({ severity: 'continue', text: verdict.text });
+    }
+    if (split.dead > 0 && (split.deadByStatus.find((d) => d.status === 'crashed')?.n ?? 0) > 0) {
+        const crashed = split.deadByStatus.find((d) => d.status === 'crashed').n;
+        warnings.push({
+            severity: crashed >= 10 ? 'critical' : 'continue',
+            text: `${crashed} crashed session${crashed === 1 ? '' : 's'} on this project`,
+            remediation: 'inspect with agents sessions --active / clean up stuck worktrees',
+        });
+    }
+    for (const line of formatProjectWarnings(warnings))
+        console.log(line);
     // `view` prints these in full (path + purpose, label + URL) right below, so
     // the compact one-line summaries would just say the same thing twice.
     if (!detail && def.goals?.length) {
@@ -417,7 +447,8 @@ export function registerProjectsCommands(program) {
       agents projects add rush --repo phnx-labs/rush --path apps/web
       agents projects list
       agents projects status              # progress card for every project
-      agents projects status rush --json  # one project, machine-readable
+      agents projects status rush         # one project (same body as view/show)
+      agents projects view rush           # alias of status <name>
       agents projects status --fleet      # + per-device workspace drift over SSH
       agents projects link rush --linear  # bind the Linear project (auto-suggest)
       agents run --project rush           # land an agent in the project
@@ -522,56 +553,8 @@ export function registerProjectsCommands(program) {
         console.log(chalk.gray(`  ${target}`));
         console.log(chalk.gray(`  root ${def.root}${def.repo ? `  ·  repo ${def.repo}` : ''}`));
     });
-    // ---- show ----
-    projects
-        .command('view <name>')
-        .alias('show')
-        .description('Everything about one project: the full status card, every milestone, and the stored definition.')
-        .option('--json', 'Machine-readable output')
-        .option('--window <days>', 'Window for merged PRs, artifacts, and focus areas', '7')
-        .option('--no-remote', 'Skip the GitHub and Linear lookups; definition only')
-        .action(async (name, opts) => {
-        const def = loadProjectDef(name);
-        if (!def) {
-            console.error(chalk.red(`No project named "${name}". List them: agents projects list`));
-            process.exit(1);
-        }
-        // `view` is `status` for one project PLUS the stored definition and every
-        // milestone. It used to render its own short list — root, repos, a raw
-        // Linear id, issues — so opening a single project told you LESS than the
-        // roll-up did: no agents, no ships, no focus, no schedule verdict.
-        const windowDays = Math.max(1, Number.parseInt(opts.window ?? '7', 10) || 7);
-        const nowMs = Date.now();
-        const all = listProjectDefs();
-        const { roll, remote, linear, focus } = await enrichProjectsForRender([def], all, {
-            windowDays,
-            nowMs,
-            skipRemote: opts.remote === false,
-        });
-        const r = roll.get(def.name);
-        const sig = remote.get(def.name);
-        const counts = linear.get(def.name);
-        if (opts.json) {
-            console.log(JSON.stringify({
-                ...def,
-                linear: { ...def.linear, ...(counts ?? {}) },
-                schedule: counts?.milestones?.length ? scheduleVerdict(counts.milestones, nowMs) : null,
-                live: r ? liveDeadSplit(r.byStatus).live : 0,
-                dead: r ? liveDeadSplit(r.byStatus).dead : 0,
-                byStatus: r?.byStatus ?? {},
-                members: r?.members ?? [],
-                openPrs: r?.openPrs ?? [],
-                tickets: r?.tickets ?? [],
-                mergedPrs: sig?.mergedPrs ?? 0,
-                latestRelease: sig?.latestRelease ?? null,
-                artifacts: sig?.artifacts ?? 0,
-                focus: focus.get(def.name) ?? [],
-            }, null, 2));
-            return;
-        }
-        // The same card `status` prints, with every milestone instead of the next.
-        renderCard(def, r, sig, undefined, counts, nowMs, Number.POSITIVE_INFINITY, focus.get(def.name) ?? [], true);
-        // Then what only `view` shows: the stored definition, in full.
+    /** Print the YAML-side fields that sit under the shared card in `view` mode. */
+    function printProjectDefinition(def, name) {
         console.log();
         if (def.root)
             console.log(`  ${chalk.dim('root')}     ${def.root}`);
@@ -593,38 +576,17 @@ export function registerProjectsCommands(program) {
         for (const d of def.docs ?? [])
             console.log(`  ${chalk.dim('doc')}      ${d}`);
         console.log(chalk.gray(`  ${projectDefPath(name)}`));
-    });
-    // ---- edit ----
-    projects
-        .command('edit <name>')
-        .description('Open the project YAML in $EDITOR (it is hand-editable regardless).')
-        .action((name) => {
-        const target = projectDefPath(name);
-        if (!fs.existsSync(target)) {
-            console.error(chalk.red(`No project named "${name}". Create it: agents projects add ${name}`));
-            process.exit(1);
-        }
-        const editor = process.env.VISUAL || process.env.EDITOR || 'vi';
-        // $EDITOR commonly carries args ("code --wait") — split like monitors/routines do.
-        const parts = editor.split(/\s+/).filter(Boolean);
-        const res = spawnSync(parts[0], [...parts.slice(1), target], { stdio: 'inherit' });
-        process.exit(res.status ?? 0);
-    });
-    // ---- status ----
-    projects
-        .command('status [name]')
-        .description('Progress rollup: agents, plan %, merged/open PRs, tickets, and artifacts per project.')
-        .option('--json', 'Machine-readable output')
-        .option('--window <days>', 'Window for merged PRs and artifacts', '7')
-        .option('--no-remote', 'Skip the GitHub lookup (merged-PR count); faster, offline')
-        .option('--fleet', 'Also dial every fleet device for workspace presence, branch, and drift (one SSH per peer)')
-        .action(async (name, opts) => {
+    }
+    async function runProjectCard(name, opts, mode) {
+        const detail = mode === 'view';
         const all = listProjectDefs();
         // Named lookup goes through the strict single-def loader so a broken
         // <name>.yaml surfaces its validation error instead of "No project named".
         const defs = name ? [loadProjectDef(name)].filter((d) => d !== undefined) : all;
         if (name && !defs.length) {
-            console.error(chalk.red(`No project named "${name}".`));
+            console.error(chalk.red(detail
+                ? `No project named "${name}". List them: agents projects list`
+                : `No project named "${name}".`));
             process.exit(1);
         }
         if (!defs.length) {
@@ -639,7 +601,8 @@ export function registerProjectsCommands(program) {
         // --fleet: probe each shown def's workspace paths (root + repos[].path)
         // locally and on every peer in one parallel SSH round, and widen the
         // live-session rollup to the whole fleet via the existing sessions
-        // fan-out. Both are opt-in — they dial the fleet.
+        // fan-out. Both are opt-in — they dial the fleet. `view` accepts the flag
+        // too so the two verbs stay interchangeable once a name is given.
         const fleetTargets = opts.fleet ? [...new Set(defs.flatMap(workspaceTargetsForDef))] : [];
         let fleetWs = [];
         let fleetSkipped = [];
@@ -673,28 +636,41 @@ export function registerProjectsCommands(program) {
             const targets = new Set(workspaceTargetsForDef(d));
             return fleetWs.filter((s) => targets.has(s.path));
         };
+        /** Local-only workspace probe for the warnings footer when --fleet is off. */
+        const localWsCache = new Map();
+        const localWsFor = (d) => {
+            const cached = localWsCache.get(d.name);
+            if (cached)
+                return cached;
+            const self = machineId();
+            const rows = probeProjectWorkspaces(workspaceTargetsForDef(d)).map((s) => ({ ...s, host: self }));
+            localWsCache.set(d.name, rows);
+            return rows;
+        };
         if (opts.json) {
             if (fleetSkipped.length > 0)
                 process.stderr.write(formatFleetSkippedNote(fleetSkipped));
+            // `view` used to nest the def fields at the top level and omit plan /
+            // worktrees / windowDays; keep one machine shape for both verbs so a
+            // consumer that switches `status`↔`view` does not re-learn the schema.
             console.log(JSON.stringify(defs.map((d) => {
                 const r = roll.get(d.name);
                 const rem = remote.get(d.name);
+                const counts = linear.get(d.name);
                 return {
-                    name: d.name,
+                    ...(detail ? d : { name: d.name }),
                     agents: r?.agents ?? 0,
                     byStatus: r?.byStatus ?? {},
                     members: r?.members ?? [],
                     plan: r?.plan ?? { done: 0, total: 0 },
-                    schedule: linear.get(d.name)?.milestones?.length
-                        ? scheduleVerdict(linear.get(d.name).milestones, nowMs)
-                        : null,
+                    schedule: counts?.milestones?.length ? scheduleVerdict(counts.milestones, nowMs) : null,
                     focus: focus.get(d.name) ?? [],
                     live: r ? liveDeadSplit(r.byStatus).live : 0,
                     dead: r ? liveDeadSplit(r.byStatus).dead : 0,
                     openPrs: r?.openPrs ?? [],
                     mergedPrs: rem?.mergedPrs ?? 0,
                     latestRelease: rem?.latestRelease ?? null,
-                    linear: linear.get(d.name) ?? null,
+                    linear: detail ? { ...d.linear, ...(counts ?? {}) } : (counts ?? null),
                     tickets: r?.tickets ?? [],
                     worktrees: r?.worktrees ?? 0,
                     artifacts: rem?.artifacts ?? 0,
@@ -706,11 +682,50 @@ export function registerProjectsCommands(program) {
             }), null, 2));
             return;
         }
+        // Compact rollup shows the next milestone; `view` shows every declared one.
+        const milestoneLimit = detail ? Number.POSITIVE_INFINITY : 1;
         for (const d of defs) {
-            renderCard(d, roll.get(d.name), remote.get(d.name), opts.fleet ? fleetFor(d) : undefined, linear.get(d.name), nowMs, 1, focus.get(d.name) ?? []);
+            renderCard(d, roll.get(d.name), remote.get(d.name), opts.fleet ? fleetFor(d) : undefined, linear.get(d.name), nowMs, milestoneLimit, focus.get(d.name) ?? [], detail, 
+            // Always feed workspace rows into the warnings footer — full fleet when
+            // --fleet, otherwise a local-only probe so behind/dirty is never silent.
+            opts.fleet ? fleetFor(d) : localWsFor(d));
+            if (detail)
+                printProjectDefinition(d, d.name);
         }
         if (fleetSkipped.length > 0)
             process.stdout.write(formatFleetSkippedNote(fleetSkipped));
+    }
+    projects
+        .command('status [name]')
+        .alias('view')
+        .alias('show')
+        .description('Progress card for every project, or one named project (aliases: view, show). Named form also prints every milestone and the stored definition.')
+        .option('--json', 'Machine-readable output')
+        .option('--window <days>', 'Window for merged PRs, artifacts, and focus areas', '7')
+        .option('--no-remote', 'Skip the GitHub and Linear lookups; faster, offline')
+        .option('--fleet', 'Also dial every fleet device for workspace presence, branch, and drift (one SSH per peer)')
+        .action(async (name, opts) => {
+        // Named invocation = `view` depth (all milestones + definition). Unnamed
+        // stays the scannable multi-project rollup. `view`/`show` are commander
+        // aliases of this same command, so there is only one implementation.
+        const mode = name ? 'view' : 'status';
+        await runProjectCard(name, opts, mode);
+    });
+    // ---- edit ----
+    projects
+        .command('edit <name>')
+        .description('Open the project YAML in $EDITOR (it is hand-editable regardless).')
+        .action((name) => {
+        const target = projectDefPath(name);
+        if (!fs.existsSync(target)) {
+            console.error(chalk.red(`No project named "${name}". Create it: agents projects add ${name}`));
+            process.exit(1);
+        }
+        const editor = process.env.VISUAL || process.env.EDITOR || 'vi';
+        // $EDITOR commonly carries args ("code --wait") — split like monitors/routines do.
+        const parts = editor.split(/\s+/).filter(Boolean);
+        const res = spawnSync(parts[0], [...parts.slice(1), target], { stdio: 'inherit' });
+        process.exit(res.status ?? 0);
     });
     // ---- probe (hidden; the peer half of `status --fleet`) ----
     projects

package/dist/commands/routines.js

@@ -628,8 +628,8 @@ export function registerRoutinesCommands(program) {
         .option('-t, --timeout <timeout>', 'Kill the agent if it runs longer than this (e.g., 10m, 2h, 3d, 1w; max 1w)', '10m')
         .option('--timezone <tz>', 'Interpret schedule in this timezone (e.g., America/Los_Angeles)')
         .option('--devices <names>', 'Fleet allowlist (comma-separated): only listed devices schedule and fire this routine. Omit for unrestricted.')
-        .option('--run-on <name>', 'Execute the job body on this machine over SSH (a registered host, device, capability tag, or user@host). Sets hostStrategy=host. Placement, not eligibility — see --devices. Auto-pins devices to THIS machine unless --devices is given.')
-        .option('--placement <strategy>', `Where the job body runs: ${HOST_STRATEGIES.join('|')} (default: local, or host when --run-on is set). Not the same as --host (which manages routines on a remote machine).`)
+        .option('--run-on <name>', 'BODY placement: execute the job body on this machine over SSH (registered host, device, capability tag, or user@host). Sets hostStrategy=host. Not eligibility — see --devices. Auto-pins devices to THIS machine unless --devices is given. Same model as agents run --where device:<name> (docs/00-concepts.md#placement).')
+        .option('--placement <strategy>', `BODY placement strategy: ${HOST_STRATEGIES.join('|')} (default: local, or host when --run-on is set). Maps to the shared Placement model (local|device|fleet|cloud). Not the same as --host (which manages routines on a remote machine).`)
         .option('--run-cwd <dir>', 'Working directory on the --run-on host (--remote-cwd is taken by the remote-management passthrough)')
         .option('--at <time>', 'One-shot mode: run once at this time (e.g., "14:30" or "2026-02-24 09:00"), then disable')
         .option('--on <source:event>', 'Webhook trigger instead of/in addition to a schedule: github:pull_request or linear:Issue')

package/dist/commands/run-account-picker.js

@@ -36,6 +36,8 @@ function disabledReason(candidate) {
         return undefined;
     if (readiness.reason === 'signed_out')
         return 'logged out';
+    if (readiness.reason === 'revoked')
+        return 'needs re-login';
     if (readiness.reason === 'out_of_credits')
         return 'out of credits';
     const windows = candidate.usageSnapshot?.windows ?? [];

package/dist/commands/secrets.js

@@ -2071,7 +2071,7 @@ Examples:
         .action(async (bundleName, opts) => {
         try {
             // `--device` is an alias for `--host` (fleet vocabulary parity with
-            // `agents activity`/`run --device`); fold it into the host list up front so
+            // `agents run --device`); fold it into the host list up front so
             // every downstream branch sees one resolved target list.
             if (opts.device?.length)
                 opts.host = [...(opts.host ?? []), ...opts.device];

package/dist/commands/sessions-backfill.d.ts

@@ -28,5 +28,38 @@ interface ToolBackfillOptions {
 }
 export declare function backfillToolsLocal(options: ToolBackfillOptions, oneBatch?: boolean): Promise<ToolBackfillMachineResult>;
 export declare function runToolsBackfill(options: ToolBackfillOptions): Promise<ToolBackfillEnvelope>;
+interface ResourceBackfillOptions {
+    agent?: string;
+    project?: string;
+    since?: string;
+    until?: string;
+    teams?: boolean;
+    json?: boolean;
+}
+export interface ResourceBackfillEnvelope {
+    schemaVersion: 1;
+    kind: 'resources-backfill';
+    generatedAt: string;
+    machine: string;
+    /** Sessions considered (matched the filter, had a real transcript). */
+    scanned: number;
+    /** Sessions (re)parsed and written this run. */
+    updated: number;
+    /** Sessions already current at this extractor version, skipped. */
+    skipped: number;
+    /** Sessions whose transcript could not be stat'd or parsed. */
+    failed: number;
+    /** Total session_resource_usage rows written across updated sessions. */
+    resourceRows: number;
+}
+/**
+ * Populate session_resource_usage for historical sessions on THIS machine.
+ * Local-only by design: the resource signal is derived from each machine's own
+ * transcripts, and the index is machine-local, so there is no cross-machine
+ * merge to do — run it on each box (or over `agents ssh`). Ensures the session
+ * index is complete first (discoverSessions), then re-derives usage gated by the
+ * resource_scan_ledger so reruns skip completed transcripts.
+ */
+export declare function runResourceBackfill(options: ResourceBackfillOptions): Promise<ResourceBackfillEnvelope>;
 export declare function registerSessionsBackfillCommand(sessionsCmd: Command): void;
 export {};

package/dist/commands/sessions-backfill.js

@@ -1,11 +1,12 @@
 import chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
-import { discoverSessions } from '../lib/session/discover.js';
+import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { machineId } from '../lib/session/sync/config.js';
 import { SESSION_AGENTS } from '../lib/session/types.js';
 import { ensureToolIndex, readToolIndexCoverage } from '../lib/session/tool-index.js';
 import { NO_FANOUT_ENV } from '../lib/session/remote-active.js';
+import { backfillResourceUsage } from '../lib/session/db.js';
 const BACKFILL_REMOTE_TIMEOUT_MS = 10 * 60_000;
 function parseAgent(value) {
     if (!value)
@@ -138,6 +139,48 @@ export async function runToolsBackfill(options) {
         machines,
     };
 }
+/**
+ * Populate session_resource_usage for historical sessions on THIS machine.
+ * Local-only by design: the resource signal is derived from each machine's own
+ * transcripts, and the index is machine-local, so there is no cross-machine
+ * merge to do — run it on each box (or over `agents ssh`). Ensures the session
+ * index is complete first (discoverSessions), then re-derives usage gated by the
+ * resource_scan_ledger so reruns skip completed transcripts.
+ */
+export async function runResourceBackfill(options) {
+    const { agent, version } = parseAgent(options.agent);
+    // Make sure every matching transcript is indexed before we re-derive usage.
+    await discoverSessions({
+        agent,
+        version,
+        project: options.project,
+        since: options.since,
+        until: options.until,
+        all: true,
+        unbounded: true,
+        skipExistenceCheck: true,
+        excludeTeamOrigin: !options.teams,
+    });
+    const filter = { excludeTeamOrigin: !options.teams };
+    if (agent)
+        filter.agent = agent;
+    if (version)
+        filter.version = version;
+    if (options.project)
+        filter.project = options.project;
+    if (options.since)
+        filter.sinceMs = parseTimeFilter(options.since);
+    if (options.until)
+        filter.untilMs = parseTimeFilter(options.until);
+    const result = backfillResourceUsage(filter);
+    return {
+        schemaVersion: 1,
+        kind: 'resources-backfill',
+        generatedAt: new Date().toISOString(),
+        machine: machineId(),
+        ...result,
+    };
+}
 export function registerSessionsBackfillCommand(sessionsCmd) {
     const backfill = sessionsCmd.command('backfill').description('Populate derived session data explicitly.');
     const tools = backfill.command('tools').description('Parse historical tool calls once into the local SQLite index.');
@@ -183,4 +226,43 @@ export function registerSessionsBackfillCommand(sessionsCmd) {
             process.exitCode = 1;
         }
     });
+    const resources = backfill.command('resources').description('Derive historical skill/slash-command usage once into the local SQLite index.');
+    setHelpSections(resources, {
+        examples: `
+      # Fold every historical session on this machine into the usage index
+      agents sessions backfill resources
+
+      # Narrow the historical work
+      agents sessions backfill resources --agent claude --since 30d
+
+      # Machine-readable summary
+      agents sessions backfill resources --json
+    `,
+        notes: `
+      - Populates session_resource_usage for sessions indexed before the usage signal shipped. New/changed sessions are recorded on their normal scan; this is the one-shot catch-up read by \`agents sessions stats\`.
+      - Local-only: the signal is derived per machine from its own transcripts. Run it on each box (or over \`agents ssh <host> agents sessions backfill resources\`).
+      - Reruns skip transcripts already current (resource_scan_ledger); bump the extractor version to force a full re-derive.
+      - Only slash commands and \`Skill\` tool calls are recorded — auto-triggered skills emit no signal.
+    `,
+    });
+    resources.action(async (_options, command) => {
+        const options = command.optsWithGlobals();
+        try {
+            const envelope = await runResourceBackfill(options);
+            if (options.json)
+                process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+            else {
+                console.log(`${envelope.machine}: derived usage for ${envelope.updated.toLocaleString()} session${envelope.updated === 1 ? '' : 's'} ` +
+                    `(${envelope.resourceRows.toLocaleString()} resource row${envelope.resourceRows === 1 ? '' : 's'}); ` +
+                    `${envelope.skipped.toLocaleString()} already current, ${envelope.scanned.toLocaleString()} scanned.`);
+                if (envelope.failed > 0) {
+                    console.log(chalk.yellow(`${envelope.failed.toLocaleString()} transcript${envelope.failed === 1 ? '' : 's'} could not be parsed; rerun to retry.`));
+                }
+            }
+        }
+        catch (error) {
+            console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+            process.exitCode = 1;
+        }
+    });
 }

package/dist/commands/sessions-stats.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `agents sessions stats` — precomputed resource-usage insights.
+ *
+ * The read side of #12: which skills and slash-commands do you actually invoke,
+ * and which installed ones are dead weight? The write side already exists —
+ * every scanned transcript's skill/`Skill`-tool + slash-command tallies land in
+ * `session_resource_usage` at index time — so this is a cheap SQLite rollup, no
+ * re-scan of history. A both-ends view: the most-invoked resources, and the
+ * installed-but-never-invoked ones.
+ *
+ * Signal caveat, surfaced in help and output: only EXPLICIT invocations count
+ * (slash commands + `Skill` tool calls). An auto-triggered skill (loaded by
+ * description match) emits no event and reads as zero — "0" means "never
+ * explicitly invoked", not "never loaded". Skill invocations are recorded for
+ * Claude and Kimi (the `Skill`-tool harnesses); slash-commands are Claude-only;
+ * other harnesses contribute nothing.
+ */
+import type { Command } from 'commander';
+/** One installed resource, keyed the same way session_resource_usage stores it. */
+export interface InstalledResource {
+    kind: 'skill' | 'command';
+    name: string;
+    plugin: string | null;
+    source: string | null;
+}
+/**
+ * The both-ends "dead weight" set: installed resources whose identity
+ * (kind + name — name already embeds `plugin:short`, so it matches the stored
+ * invoked name) never appears in the invoked rows. Sorted kind then name.
+ * Pure set-difference so it is unit-testable without touching the filesystem.
+ */
+export declare function diffZeroInvoked(installed: InstalledResource[], invoked: Array<{
+    kind: string;
+    name: string;
+}>): InstalledResource[];
+export declare function registerSessionsStatsCommand(sessionsCmd: Command): void;