@phnx-labs/agents-cli 1.22.6 → 1.22.8

package/dist/lib/rotate.js

@@ -13,6 +13,8 @@ import { getProjectRunConfigs } from './run-config.js';
 import { emit } from './events.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
 import { readAccountHeadroom } from './fleet-cache.js';
+import { machineId } from './machine-id.js';
+import { readAuthHealthCache, authCacheKey, isDeadVerdict } from './auth-health.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });
@@ -65,8 +67,14 @@ export function setGlobalRunStrategy(agent, strategy) {
     meta.run[agent] = { ...(meta.run[agent] ?? {}), strategy };
     writeMeta(meta);
 }
+/**
+ * Whether an account may be rotated INTO right now. Defined in terms of
+ * {@link readinessFromCandidate} so the router's pick gate and the pre-flight
+ * warning can never disagree: an account is eligible iff its readiness is
+ * `ready` — signed in, not server-revoked, and not out of usage.
+ */
 function isRotationEligible(candidate) {
-    return candidate.signedIn && hasUsageAvailable(candidate);
+    return readinessFromCandidate(candidate).ready;
 }
 /**
  * Whether a version home can actually authenticate a launch.
@@ -146,6 +154,13 @@ export function readinessFromCandidate(candidate) {
     if (!candidate.signedIn) {
         return { ready: false, reason: 'signed_out', email: candidate.email };
     }
+    // A token the daemon's live probe saw rejected (401/403 -> `revoked`) will fail
+    // auth at spawn no matter how much usage headroom it has. Exclude it BEFORE the
+    // usage gate so rotation never routes into a doomed login. Fail-open: any other
+    // (or null) verdict does not gate — see `RotateCandidate.authVerdict`.
+    if (candidate.authVerdict !== null && isDeadVerdict(candidate.authVerdict)) {
+        return { ready: false, reason: 'revoked', email: candidate.email };
+    }
     if (hasUsageAvailable(candidate)) {
         return { ready: true };
     }
@@ -495,6 +510,12 @@ export function formatNoHealthyHarnessError(summaries, nowMs = Date.now()) {
 }
 export async function collectRunCandidates(agent) {
     const versions = listInstalledVersions(agent);
+    // Read the local auth-health probe cache once (cache-only, no network — the
+    // daemon is the sole writer). A `revoked` verdict for a (host, agent, version)
+    // excludes that account from the pick; a missing row is fail-open. Keyed by the
+    // LOCAL host — routing decides which local version to launch.
+    const authCache = readAuthHealthCache();
+    const localHost = machineId();
     const rows = await Promise.all(versions.map(async (version) => {
         const home = getVersionHomePath(agent, version);
         const info = await getAccountInfo(agent, home);
@@ -510,6 +531,7 @@ export async function collectRunCandidates(agent) {
         // lives — see isLaunchableSignedIn. Do not reuse the active-home fallback
         // identity for routing, or empty version homes look healthy and die at spawn.
         const launchable = isLaunchableSignedIn(info.signedIn, credentialPresence(agent, home));
+        const authVerdict = authCache[authCacheKey(localHost, agent, version)]?.verdict ?? null;
         return {
             agent,
             version,
@@ -521,6 +543,7 @@ export async function collectRunCandidates(agent) {
             usageStatus: launchable ? info.usageStatus : null,
             plan: launchable ? info.plan : null,
             signedIn: launchable,
+            authVerdict,
             lastActive: info.lastActive,
         };
     }));

package/dist/lib/routines.d.ts

@@ -239,6 +239,8 @@ export interface RunMeta {
     pid: number | null;
     /** Process birth time (epoch ms) recorded at spawn for pid-reuse detection. */
     spawnedAt?: number;
+    /** Configured execution deadline persisted for daemon-restart recovery. */
+    timeoutMs?: number;
     /**
      * `missed` is not an execution outcome — it is the record that a scheduled
      * fire never happened (the daemon was down, asleep, or wedged when it came

package/dist/lib/runner.d.ts

@@ -23,6 +23,9 @@ export interface RunResult {
     meta: RunMeta;
     reportPath: string | null;
 }
+export declare class RoutineAlreadyRunningError extends Error {
+    constructor(jobName: string, runId: string);
+}
 /** Agents the daemon can actually run, derived from the command table above
  * so the `--agent` help and any validation can never drift from it. */
 export declare const ROUTINE_AGENT_IDS: readonly string[];

package/dist/lib/runner.js

@@ -17,7 +17,7 @@ import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
-import { resolveJobPrompt, parseTimeout, writeRunMeta, getRunDir, checkJobDeviceEligibility, finalizeRunMeta, } from './routines.js';
+import { resolveJobPrompt, parseTimeout, writeRunMeta, listRuns, getJobRunsDir, getRunDir, checkJobDeviceEligibility, finalizeRunMeta, } from './routines.js';
 import { getRunsDir } from './state.js';
 import { prepareJobHome, buildSpawnEnv, getJobHomePath } from './sandbox.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
@@ -26,7 +26,9 @@ import { normalizeMode, resolveHeadlessMode, buildExecEnv, detectRateLimit, dete
 import { resolveActor } from './actor.js';
 import { loadTask as loadHostTask } from './hosts/tasks.js';
 import { reconcileTask as reconcileHostTask } from './hosts/reconcile.js';
-import { backgroundSpawnOptions } from './platform/process.js';
+import { backgroundSpawnOptions, killTree } from './platform/process.js';
+import lockfile from 'proper-lockfile';
+import { ensureLockTarget } from './fs-atomic.js';
 import { walkForFiles } from './fs-walk.js';
 import { getBinaryPath, isVersionInstalled, resolveVersion } from './versions.js';
 import { getConfiguredRunStrategy, resolveRunVersion, resolveAccountVersion, rotationFailoverChain, readinessFromCandidate, formatNoHealthyAccountError, } from './rotate.js';
@@ -34,6 +36,66 @@ import { readAuthHealth, isDeadVerdict } from './auth-health.js';
 import { machineId } from './machine-id.js';
 import { isSelfUpdatingAgent } from './agents.js';
 import { expandLocalHome, getProjectRoot } from './project-root.js';
+export class RoutineAlreadyRunningError extends Error {
+    constructor(jobName, runId) {
+        super(`Routine '${jobName}' already has a running execution (${runId})`);
+        this.name = 'RoutineAlreadyRunningError';
+    }
+}
+const ROUTINE_LAUNCH_LOCK_STALE_MS = 30_000;
+const ROUTINE_LAUNCH_LOCK_WAIT_MS = 10_000;
+function activeRoutineRun(config) {
+    const timeoutMs = parseTimeout(config.timeout) || 10 * 60 * 1000;
+    const now = Date.now();
+    const runs = listRuns(config.name);
+    for (let i = runs.length - 1; i >= 0; i--) {
+        const run = runs[i];
+        if (run.status !== 'running')
+            continue;
+        if (run.pid && isPidOurs(run.pid, run.spawnedAt))
+            return run;
+        if (!run.pid) {
+            const startedAt = Date.parse(run.startedAt);
+            if (Number.isFinite(startedAt) && now - startedAt < (run.timeoutMs ?? timeoutMs))
+                return run;
+        }
+    }
+    return null;
+}
+async function withRoutineLaunchClaim(config, launch) {
+    const target = path.join(getJobRunsDir(config.name), '.launch-claim');
+    ensureLockTarget(target, '', 0o700);
+    const release = await lockfile.lock(target, {
+        stale: ROUTINE_LAUNCH_LOCK_STALE_MS,
+        retries: {
+            retries: Math.ceil(ROUTINE_LAUNCH_LOCK_WAIT_MS / 100),
+            factor: 1,
+            minTimeout: 100,
+            maxTimeout: 100,
+        },
+    });
+    try {
+        const active = activeRoutineRun(config);
+        if (active)
+            throw new RoutineAlreadyRunningError(config.name, active.runId);
+        return await launch();
+    }
+    finally {
+        await release();
+    }
+}
+function terminateRoutineTree(pid) {
+    if (!pid)
+        return;
+    if (process.platform === 'win32') {
+        killTree(pid);
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch { /* already exited */ }
+}
 /** CLI command templates per agent, with {prompt} as a placeholder. */
 const AGENT_COMMANDS = {
     claude: ['claude', '-p', '--verbose', '{prompt}', '--output-format', 'stream-json', '--permission-mode', 'plan'],
@@ -1086,6 +1148,9 @@ export async function executeJobDetached(config, hooks) {
         process.stderr.write(`[agents] daemon: skipping '${config.name}' — ${eligibility.message}\n`);
         throw new Error(eligibility.message);
     }
+    return withRoutineLaunchClaim(config, () => executeJobDetachedClaimed(config, hooks));
+}
+async function executeJobDetachedClaimed(config, hooks) {
     // Placement (hostStrategy / bare host:) — dispatch off-box and return; the
     // monitor finalizes host: runs, cloud runs stay terminal when dispatch ends.
     // Either way the in-process onFinish hook does not fire for off-box routines
@@ -1161,6 +1226,7 @@ export async function executeJobDetached(config, hooks) {
         ...(config.workflow ? { workflow: config.workflow } : {}),
         pid: null,
         spawnedAt: Date.now(),
+        timeoutMs: parseTimeout(config.timeout) || 10 * 60 * 1000,
         status: 'running',
         startedAt: new Date().toISOString(),
         completedAt: null,
@@ -1195,10 +1261,13 @@ export async function executeJobDetached(config, hooks) {
         env: spawnEnv,
     });
     let settled = false;
+    let timeoutTimer;
     const settle = (status, exitCode, errorMessage) => {
         if (settled)
             return;
         settled = true;
+        if (timeoutTimer)
+            clearTimeout(timeoutTimer);
         finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
         archiveRoutineTranscripts(meta, runDir, overlayHome);
@@ -1212,6 +1281,10 @@ export async function executeJobDetached(config, hooks) {
         // can read report.md (RUSH-2030). Best-effort; never breaks finalization.
         safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);
     };
+    timeoutTimer = setTimeout(() => {
+        terminateRoutineTree(child.pid ?? null);
+        settle('timeout', null, 'exceeded configured timeout');
+    }, meta.timeoutMs);
     child.on('exit', (code) => {
         let logText = '';
         try {
@@ -1249,7 +1322,7 @@ export async function executeJobDetached(config, hooks) {
     catch { /* fd already closed */ }
     meta.pid = child.pid || null;
     writeRunMeta(meta);
-    return meta;
+    return { ...meta };
 }
 /**
  * Detached (fire-and-forget) execution for a command-mode routine. Mirrors the
@@ -1288,6 +1361,7 @@ function executeCommandJobDetached(config, hooks) {
         command: config.command,
         pid: null,
         spawnedAt: Date.now(),
+        timeoutMs: parseTimeout(config.timeout) || 10 * 60 * 1000,
         status: 'running',
         startedAt: new Date().toISOString(),
         completedAt: null,
@@ -1302,17 +1376,24 @@ function executeCommandJobDetached(config, hooks) {
     // fire-and-forget call, so the exit event fires here. (monitorRunningJobs no
     // longer force-fails command jobs; it reads exit-code only on the restart edge.)
     let settled = false;
+    let timeoutTimer;
     const settle = (status, exitCode, errorMessage) => {
         if (settled)
             return;
         settled = true;
+        if (timeoutTimer)
+            clearTimeout(timeoutTimer);
         finalizeRunMeta(meta, status, exitCode, errorMessage ? { errorMessage } : undefined);
         writeRunMeta(meta);
-        timer.end({ status, exitCode, runId, ...(errorMessage ? { error: errorMessage } : {}) });
+        timer.end({ status, exitCode: exitCode ?? undefined, runId, ...(errorMessage ? { error: errorMessage } : {}) });
         // Finish notification (RUSH-2030). For command routines the threshold only
         // surfaces failures, decided in routine-notify.ts. Best-effort.
         safeHook(hooks?.onFinish ? () => hooks.onFinish(meta) : undefined);
     };
+    timeoutTimer = setTimeout(() => {
+        terminateRoutineTree(child.pid ?? null);
+        settle('timeout', null, 'exceeded configured timeout');
+    }, meta.timeoutMs);
     child.on('exit', (code) => settle(code === 0 ? 'completed' : 'failed', code ?? 1));
     child.on('error', (err) => {
         settle('failed', 1, err.message);
@@ -1325,7 +1406,7 @@ function executeCommandJobDetached(config, hooks) {
     catch { /* fd already closed */ }
     meta.pid = child.pid || null;
     writeRunMeta(meta);
-    return meta;
+    return { ...meta };
 }
 function extractAndSaveReport(stdoutPath, agentType, runDir) {
     try {
@@ -1508,8 +1589,10 @@ export function monitorRunningJobs() {
                 // parse or extract. Reap them on pid liveness alone.
                 const isCommandRun = Boolean(meta.command) || !meta.agent;
                 const wallClockMs = Date.now() - Date.parse(meta.startedAt);
-                if (Number.isFinite(wallClockMs) && wallClockMs > MAX_WALL_CLOCK_MS) {
-                    finalizeRunMeta(meta, 'timeout', null, { errorMessage: 'exceeded max wall clock' });
+                const timeoutMs = meta.timeoutMs ?? MAX_WALL_CLOCK_MS;
+                if (Number.isFinite(wallClockMs) && wallClockMs > timeoutMs) {
+                    terminateRoutineTree(meta.pid);
+                    finalizeRunMeta(meta, 'timeout', null, { errorMessage: 'exceeded configured timeout' });
                     writeRunMeta(meta);
                     if (!isCommandRun) {
                         extractAndSaveReport(stdoutPath, meta.agent, runDirPath);

package/dist/lib/secrets/audit.js

@@ -19,7 +19,7 @@
  *
  * The event vocabulary, all audit-level and non-milestone (so they surface in
  * `agents events` and the persisted audit trail, but are NOT required in the
- * curated `agents activity` / `agents feed` surfaces):
+ * curated `agents feed` surface):
  *  - `secrets.get`      — a value was READ (exec inject, export, `view --reveal`,
  *                         raw `get <item>`, remote resolve, sync push,
  *                         `run --secrets`, and every other bundle read).

package/dist/lib/secrets/index.d.ts

@@ -121,6 +121,7 @@ export declare function withRawKeychainServiceNames<T>(fn: () => T): T;
  * the re-key migration and tests; runtime callers go through the primitives,
  * which apply this transparently. */
 export declare function hashedServiceName(item: string, key: Buffer): string;
+export declare function readHmacKeyRecord(): HmacKeyRecord | null;
 /**
  * Heal a `hmackey` item that an OLD helper (pre the metadata/hmackey no-ACL
  * migration fix) re-stamped with a biometry ACL. Such an item makes EVERY hashed

package/dist/lib/secrets/index.js

@@ -235,7 +235,7 @@ function parseHmacKeyRecord(raw) {
     }
     return null;
 }
-function readHmacKeyRecord() {
+export function readHmacKeyRecord() {
     // HMAC_KEY_ITEM is exempt from the transform, so this routes to the helper
     // (or the test backend) under its literal name. The item is no-ACL, so the
     // read is silent — attest that to the storm guard so a headless hashed-name
@@ -247,7 +247,30 @@ function readHmacKeyRecord() {
     catch {
         return null;
     }
-    return parseHmacKeyRecord(raw);
+    const record = parseHmacKeyRecord(raw);
+    // Converge a stale-ACL'd hmackey to silent, on the HOT read path. An old helper
+    // (pre the metadata/hmackey no-ACL migration fix) re-stamped this
+    // contractually-no-ACL item with a biometry ACL, so the read just above pops the
+    // generic "Agents CLI needs to authenticate" sheet on EVERY hashed lookup — the
+    // `agents devices list` stats probe the SessionStart hook runs, and every other
+    // background hashed read. `maybeAutoRekey`'s one-shot heal only fires on a
+    // cleartext-bundle resolve and is bypassed for the hmackey/hashed-name path
+    // (prepareServiceName returns early for HMAC_KEY_ITEM before maybeAutoRekey), so
+    // it never converged exactly these reads and the machine prompted forever.
+    // Re-store the record no-ACL once per machine here (the read that produced it has
+    // already happened — and already prompted if the item was ACL'd); every
+    // subsequent read, in this process and all future ones, is silent.
+    if (record && !record.healedNoAcl) {
+        try {
+            healHmacKeyNoAclOnce(record);
+            record.healedNoAcl = true;
+        }
+        catch {
+            // A failed no-ACL re-store leaves the item still ACL'd (a still-prompting
+            // read) rather than a silent wrong state; the next process retries.
+        }
+    }
+    return record;
 }
 function writeHmacKeyRecord(rec) {
     // JSON.stringify drops undefined fields (used to clear pendingDeletes).
@@ -423,19 +446,10 @@ function maybeAutoRekey() {
         return;
     const st = resolveHashState();
     if (st.active) {
-        // Heal an already-active machine whose hmackey was re-stamped ACL'd by an old
-        // helper (its read popped the generic Touch ID sheet on every hashed lookup).
-        // Runs once per machine; mutate the local so a later finishPendingDeletes write
-        // preserves the healed flag.
-        if (st.record && !st.record.healedNoAcl) {
-            try {
-                healHmacKeyNoAclOnce(st.record);
-                st.record.healedNoAcl = true;
-            }
-            catch {
-                /* next process retries */
-            }
-        }
+        // The stale-ACL'd-hmackey heal now runs on the hot read path
+        // (readHmacKeyRecord), which the resolveHashState() above just went through —
+        // so st.record is already healed here regardless of how this machine reached
+        // "hashing active". Nothing to do but finish any pending deletes.
         if (st.record?.pendingDeletes?.length) {
             try {
                 finishPendingDeletes(st.record);

package/dist/lib/secrets/remote.d.ts

@@ -46,7 +46,7 @@ export declare function resolveHostSshTarget(nameOrAlias: string): Promise<strin
  * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
  * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
  * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
- * fleet-wide `--device` vocabulary (see `agents activity`, `agents run --device`)
+ * fleet-wide `--device` vocabulary (see `agents run --device`, `agents feed --host`)
  * works on the secrets remote commands too. Empty when none is set.
  */
 export declare function parseHostsOption(opts: {

package/dist/lib/secrets/remote.js

@@ -77,7 +77,7 @@ export async function resolveHostSshTarget(nameOrAlias) {
  * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
  * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
  * works. `--device`/`--devices` resolve identically to `--host`/`--hosts` so the
- * fleet-wide `--device` vocabulary (see `agents activity`, `agents run --device`)
+ * fleet-wide `--device` vocabulary (see `agents run --device`, `agents feed --host`)
  * works on the secrets remote commands too. Empty when none is set.
  */
 export function parseHostsOption(opts) {

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

@@ -58,6 +58,8 @@ export interface ActiveSession {
     pid?: number;
     sessionId?: string;
     cwd?: string;
+    /** Project/repo key derived from cwd, when known. */
+    project?: string | null;
     /** User-given name from /rename command. */
     label?: string;
     /** Durable `agents run --name` launch handle, when the run was named. */

package/dist/lib/session/bash-command.d.ts

@@ -1,9 +1,8 @@
 /**
  * Parses the raw command strings agents pass to Bash tool calls into structured
  * metadata: the executable, category, subcommand, and a display summary. Used by
- * session rendering and the activity-log hook so `agents sessions` and
- * `agents activity` can summarize what actually happened instead of printing a
- * wall of shell.
+ * session rendering and the activity-log hook so `agents sessions` can
+ * summarize what actually happened instead of printing a wall of shell.
  */
 export type BashCategory = 'vcs' | 'build-test' | 'install' | 'remote' | 'http' | 'media' | 'upscaling' | 'metadata' | 'probe' | 'search' | 'shell' | 'wait' | 'other';
 export interface BashToolInfo {

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

@@ -12,7 +12,14 @@ 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 = 30;
+export declare const SCHEMA_VERSION = 31;
+/**
+ * Bump to force `agents sessions backfill resources` to re-derive every
+ * session's skill/slash-command tallies on its next run (resource_scan_ledger
+ * rows with a lower version are treated as stale — the same mechanism
+ * TOOL_INDEX_VERSION gives the tool backfill).
+ */
+export declare const RESOURCE_INDEX_VERSION = 1;
 /** Raw row shape returned from the sessions table. */
 export interface SessionRow {
     id: string;
@@ -75,6 +82,8 @@ export interface QueryOptions {
     /** Match any session whose cwd equals this or is a descendant of it. */
     cwdPrefix?: string;
     project?: string;
+    /** Only sessions recorded on this machine (host), case-insensitive. */
+    machine?: string;
     /** Match the full session id or short id, case-insensitively (exact). */
     idExact?: string;
     /** Match sessions whose id or short id begins with this (case-insensitive prefix). */
@@ -324,6 +333,88 @@ export declare function queryAffinityRollup(options: {
 export declare function queryUsageRollup(options: QueryOptions & {
     groupBy: UsageRollupGroup;
 }): UsageRollupRow[];
+/** One aggregated resource (skill or slash-command) in a usage-stats rollup. */
+export interface ResourceStatRow {
+    /** 'skill' or 'command' (singular, as stored in session_resource_usage.kind). */
+    kind: string;
+    /** Stored resource name — bare, or `plugin:short` for a plugin-owned resource. */
+    name: string;
+    /** Owning plugin, or null for a flat (non-namespaced) resource. */
+    plugin: string | null;
+    /** DotAgents layer or plugin marketplace the resource resolved to at write time. */
+    source: string | null;
+    /** Distinct sessions that invoked this resource within the filter window. */
+    sessions: number;
+    /** Total invocations (sum of per-session counts) within the window. */
+    invocations: number;
+}
+/**
+ * Roll up skill / slash-command usage from session_resource_usage, joined to
+ * `sessions` for attribution so the same filter shape as querySessions
+ * (agent / project / since / machine) narrows WHICH sessions count. Grouped by
+ * resource identity (kind + name + plugin + source) and ordered by invocation
+ * volume — the read side of "which skills/commands do I actually use, and which
+ * are dead weight". `order: 'bottom'` ranks least-used first (the one-time
+ * skills); `limit` caps the returned rows.
+ *
+ * The signal only captures EXPLICIT invocations (slash commands and `Skill`
+ * tool calls). An auto-triggered skill (loaded by description match) emits no
+ * event, so it reads as zero here — a 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.
+ *
+ * `kind` / `pluginFilter` filter the RESOURCE rows directly (r.kind / r.plugin),
+ * distinct from QueryOptions.skill / QueryOptions.plugin, which filter SESSIONS
+ * — deliberately not routed through buildSessionWhere so `--plugin rush` shows
+ * only rush's resources rather than every resource used by a rush-touching
+ * session.
+ */
+export declare function queryResourceUsageStats(options: QueryOptions & {
+    kind?: 'skill' | 'command';
+    pluginFilter?: string;
+    order?: 'top' | 'bottom';
+    limit?: number;
+}): ResourceStatRow[];
+/**
+ * Coverage of the resource-usage signal: how many distinct sessions carry any
+ * row in session_resource_usage vs. the total indexed. A low ratio means the
+ * historical backfill (`agents sessions backfill resources`) hasn't run — the
+ * stats surface uses this to tell the user their zero-counts may just be
+ * un-scanned history, not genuine non-use.
+ */
+export declare function resourceUsageCoverage(): {
+    covered: number;
+    total: number;
+};
+/** Outcome of a resource-usage backfill run. */
+export interface ResourceBackfillResult {
+    /** 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;
+}
+/**
+ * One-shot historical backfill of session_resource_usage (#12). The normal
+ * incremental scan writes resource usage only for sessions whose transcript it
+ * (re)parses; a session indexed before this feature shipped keeps a fresh
+ * scan_ledger row and is never re-derived, so its skill/slash-command tallies
+ * were never recorded. This walks the session index, re-parses each transcript
+ * FROM BYTE 0 (parseSession fully materializes — no resumable cursor, so
+ * claude/codex re-derive their tallies from scratch), writes the usage, and
+ * stamps resource_scan_ledger so reruns skip completed transcripts — the same
+ * independent-ledger shape `agents sessions backfill tools` uses.
+ *
+ * Harness-agnostic: parseSession + extractSkills/extractSlashCommands cover
+ * every agent uniformly, so there is no per-harness branch to keep in parity.
+ * Synthetic rows without a transcript (OpenClaw channels/cron) are skipped.
+ */
+export declare function backfillResourceUsage(filter?: QueryOptions, onProgress?: (done: number, total: number) => void): ResourceBackfillResult;
 /** Who spawned a team: the orchestrator session, from its transcript. */
 export interface TeamSpawner {
     sessionId: string;