@prohost/cli 0.10.0 → 0.10.2

package/dist/usage/command.js

@@ -11,12 +11,14 @@ import process from 'node:process';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_ACCOUNT_LABEL, loadAccounts, runtimeName } from '../agent/accounts.js';
+import { baseUrlProblem } from '../agent/base-url.js';
 import { daemonEnvironment } from '../agent/command.js';
 import { maskSecret, prohostHome } from '../agent/credentials.js';
 import { buildSystemdUnit, installLaunchdDaemon, launchdLabel, launchdPlistPath, uninstallLaunchdDaemon, } from '../agent/daemon.js';
 import { acquireRunLock } from '../agent/lock.js';
 import { ensurePrivateDir, resolveUsageKey, saveUsageCredentials, usageStateDir } from './config.js';
 import { accountConfigDir, discoverAccounts } from './discovery.js';
+import { PipedKeyTooLongError, promptHiddenKey, readPipedKey } from './key-input.js';
 import { RETENTION_DAYS, dayKey, loadScanState, localTotals, pendingDays } from './scanner.js';
 import { UsageService, loadStatus, runUsageLoop, scanStatePath } from './service.js';
 const defaultIO = {
@@ -83,21 +85,77 @@ export function renderDiscovery(result, env, dryRun) {
         lines.push(row('!', s.label, s.runtime, s.dir, `skipped: ${s.reason}`));
     return lines;
 }
+/**
+ * The key `connect` should store, in order: `--key -` (stdin, or a hidden
+ * prompt at a terminal), a literal `--key <value>` (warned about), then
+ * `$PROHOST_API_KEY`, then piped stdin, then — at a terminal, with no
+ * credential to fall back on — a hidden prompt. `undefined` means "none given";
+ * `null` means a usage error that has already been printed.
+ */
+async function connectKey(flags, io, env) {
+    const stdin = io.stdin ?? process.stdin;
+    const prompt = () => promptHiddenKey(stdin, (text) => process.stderr.write(text));
+    const literal = flagString(flags, 'key');
+    if (literal === '-') {
+        const key = stdin.isTTY ? await prompt() : await readPipedKey(stdin);
+        if (!key)
+            io.err('✗ --key - got no key. Pipe one in (pbpaste | prohost usage connect --key -) or type it at the prompt.');
+        return key ?? null;
+    }
+    if (literal) {
+        io.err('! --key <value> leaves the key in your shell history and the process list. ' +
+            'Next time pipe it instead: pbpaste | prohost usage connect --key -');
+        return literal.trim();
+    }
+    if (env.PROHOST_API_KEY)
+        return env.PROHOST_API_KEY.trim();
+    if (!stdin.isTTY)
+        return readPipedKey(stdin);
+    // At a terminal: prompt only when there is nothing to fall back on, so a
+    // connected machine (or one with a paired agent) is not asked again.
+    if (resolveUsageKey(env))
+        return undefined;
+    return prompt();
+}
 async function connectCommand(flags, io) {
     const env = io.env ?? process.env;
     if (flags.key === true) {
-        io.err('--key needs a value. Create a key with the usage:write scope in ProhostAI → Settings → API keys.');
+        io.err('--key needs a value. Use --key - to read it from stdin (pbpaste | prohost usage connect --key -), ' +
+            'or leave --key off to be prompted. Create a key with the usage:write scope in ProhostAI → Settings → API keys.');
+        return 1;
+    }
+    if (flags['base-url'] === true) {
+        io.err('--base-url needs a value, e.g. --base-url https://connect.prohost.ai');
+        return 1;
+    }
+    // Checked before any key is read or stored: the key goes to this URL.
+    const baseUrl = flagString(flags, 'base-url');
+    const problem = baseUrl ? baseUrlProblem(baseUrl) : undefined;
+    if (problem) {
+        io.err(`✗ --base-url rejected: ${problem}`);
+        return 1;
+    }
+    let key;
+    try {
+        key = await connectKey(flags, io, env);
+    }
+    catch (err) {
+        if (!(err instanceof PipedKeyTooLongError))
+            throw err;
+        io.err('✗ The piped input is not an API key (no line ended within 4096 characters). Nothing was saved.');
         return 1;
     }
-    const key = flagString(flags, 'key') ?? env.PROHOST_API_KEY;
+    if (key === null)
+        return 1;
     if (key) {
-        const file = saveUsageCredentials({ apiKey: key.trim(), baseUrl: flagString(flags, 'base-url') }, env);
-        io.out(`✓ Saved key ${maskSecret(key.trim())} to ${file} (owner-only).`);
+        const file = saveUsageCredentials({ apiKey: key, baseUrl }, env);
+        io.out(`✓ Saved key ${maskSecret(key)} to ${file} (owner-only).`);
     }
     else {
         const existing = resolveUsageKey(env);
         if (!existing) {
-            io.err('✗ No API key. Pass --key <key> (scope usage:write) or set $PROHOST_API_KEY. ' +
+            io.err('✗ No API key. Run prohost usage connect at a terminal to be prompted, pipe one in with --key -, ' +
+                'or set $PROHOST_API_KEY (scope usage:write). ' +
                 'A machine with a paired agent can skip this — its credential is used.');
             return 1;
         }
@@ -112,6 +170,26 @@ async function connectCommand(flags, io) {
     io.out('Report now and every 5 minutes: prohost usage start   (or keep it running: prohost usage install-daemon)');
     return 0;
 }
+/**
+ * The stored key, when it can be sent: present, and its base URL is https://
+ * (or loopback http://). Prints why not and returns `null` otherwise.
+ */
+function usableKey(env, io) {
+    const key = resolveUsageKey(env);
+    if (!key) {
+        io.err('✗ Not connected. Run: prohost usage connect');
+        return null;
+    }
+    const problem = baseUrlProblem(key.baseUrl);
+    if (problem) {
+        io.err(`✗ Refusing to send the API key: the stored API base URL is unusable. ${problem} ` +
+            (key.source === 'agent'
+                ? 'Re-pair the agent with an https:// --base-url.'
+                : 'Reconnect: prohost usage connect --key - --base-url https://…'));
+        return null;
+    }
+    return key;
+}
 function discoverCommand(flags, io) {
     const env = io.env ?? process.env;
     const dryRun = flags['dry-run'] === true;
@@ -121,10 +199,8 @@ function discoverCommand(flags, io) {
 }
 async function startCommand(flags, io) {
     const env = io.env ?? process.env;
-    if (!resolveUsageKey(env)) {
-        io.err('✗ Not connected. Run: prohost usage connect --key <api key>');
+    if (!usableKey(env, io))
         return 1;
-    }
     // Its own lock, under $PROHOST_HOME/usage — `agent run` holds the home's.
     const stateDir = ensurePrivateDir(usageStateDir(env));
     const lock = acquireRunLock({ ...env, PROHOST_HOME: stateDir });
@@ -163,10 +239,8 @@ function cliEntrypoint() {
 }
 function installCommand(flags, io) {
     const env = io.env ?? process.env;
-    if (!resolveUsageKey(env)) {
-        io.err('✗ Not connected. Run: prohost usage connect --key <api key>');
+    if (!usableKey(env, io))
         return 1;
-    }
     const workdir = ensurePrivateDir(usageStateDir(env));
     const spec = {
         label: usageLaunchdLabel(prohostHome(env)),
@@ -233,8 +307,9 @@ function statusCommand(io) {
     const env = io.env ?? process.env;
     const key = resolveUsageKey(env);
     io.out(key
-        ? `Connected   ${maskSecret(key.apiKey)} → ${key.baseUrl}${key.source === 'agent' ? '  (paired agent credential)' : ''}`
-        : 'Connected   no — run: prohost usage connect --key <api key>');
+        ? `Connected   ${maskSecret(key.apiKey)} → ${key.baseUrl}${key.source === 'agent' ? '  (paired agent credential)' : ''}` +
+            `${baseUrlProblem(key.baseUrl) ? '  (not https:// — nothing is sent)' : ''}`
+        : 'Connected   no — run: prohost usage connect');
     const plist = launchdPlistPath(usageLaunchdLabel(prohostHome(env)));
     io.out(`Daemon      ${os.platform() === 'darwin' ? (existsSync(plist) ? `installed (${tildify(plist, env)})` : 'not installed') : 'see systemd'}`);
     const status = loadStatus(env);

package/dist/usage/key-input.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Reading an API key for `prohost usage connect` without putting it on the
+ * command line, where it would land in shell history and the process list.
+ *
+ * Two safe paths: piped stdin (`pbpaste | prohost usage connect --key -`) and,
+ * at a terminal, a prompt that does not echo what is typed or pasted.
+ */
+/** The slice of `process.stdin` this module uses, so tests can pass a stream. */
+export interface KeyStdin extends AsyncIterable<string | Buffer> {
+    isTTY?: boolean;
+    setRawMode?(mode: boolean): unknown;
+    setEncoding(encoding: BufferEncoding): unknown;
+    on(event: 'data', listener: (chunk: string | Buffer) => void): unknown;
+    removeListener(event: 'data', listener: (chunk: string | Buffer) => void): unknown;
+    resume(): unknown;
+    pause(): unknown;
+}
+/** Longer than any ProhostAI key; a pipe that runs past it is not a key. */
+export declare const MAX_PIPED_KEY_CHARS = 4096;
+export declare class PipedKeyTooLongError extends Error {
+}
+/**
+ * The first non-empty line of piped stdin, trimmed; `undefined` when there is
+ * none. Returns as soon as that line ends, so a producer that keeps the pipe
+ * open does not hang `connect`, and stops reading past
+ * {@link MAX_PIPED_KEY_CHARS}.
+ *
+ * @throws PipedKeyTooLongError when no line ends within the limit.
+ */
+export declare function readPipedKey(stdin: KeyStdin): Promise<string | undefined>;
+/**
+ * Prompt for a key at a terminal without echoing it. Resolves with the
+ * trimmed key, or `undefined` when nothing was entered or the user pressed
+ * Ctrl-C. The prompt goes to `write` (stderr), keeping stdout clean.
+ */
+export declare function promptHiddenKey(stdin: KeyStdin, write: (text: string) => void, prompt?: string): Promise<string | undefined>;

package/dist/usage/key-input.js

@@ -0,0 +1,79 @@
+/**
+ * Reading an API key for `prohost usage connect` without putting it on the
+ * command line, where it would land in shell history and the process list.
+ *
+ * Two safe paths: piped stdin (`pbpaste | prohost usage connect --key -`) and,
+ * at a terminal, a prompt that does not echo what is typed or pasted.
+ */
+/** Longer than any ProhostAI key; a pipe that runs past it is not a key. */
+export const MAX_PIPED_KEY_CHARS = 4096;
+export class PipedKeyTooLongError extends Error {
+}
+/**
+ * The first non-empty line of piped stdin, trimmed; `undefined` when there is
+ * none. Returns as soon as that line ends, so a producer that keeps the pipe
+ * open does not hang `connect`, and stops reading past
+ * {@link MAX_PIPED_KEY_CHARS}.
+ *
+ * @throws PipedKeyTooLongError when no line ends within the limit.
+ */
+export async function readPipedKey(stdin) {
+    let pending = '';
+    for await (const chunk of stdin) {
+        pending += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        let newline = pending.search(/\r?\n/);
+        while (newline !== -1) {
+            // Measured before trimming: padding counts toward the bound too.
+            const raw = pending.slice(0, newline);
+            if (raw.length > MAX_PIPED_KEY_CHARS)
+                throw new PipedKeyTooLongError('piped input is not a key');
+            const line = raw.trim();
+            if (line)
+                return line;
+            pending = pending.slice(newline).replace(/^\r?\n/, '');
+            newline = pending.search(/\r?\n/);
+        }
+        if (pending.length > MAX_PIPED_KEY_CHARS)
+            throw new PipedKeyTooLongError('piped input is not a key');
+    }
+    if (pending.length > MAX_PIPED_KEY_CHARS)
+        throw new PipedKeyTooLongError('piped input is not a key');
+    return pending.trim() || undefined;
+}
+const ENTER = new Set(['\r', '\n', '\u0004']); // Return, or Ctrl-D
+const CTRL_C = '\u0003';
+const BACKSPACE = new Set(['\u007f', '\b']);
+/**
+ * Prompt for a key at a terminal without echoing it. Resolves with the
+ * trimmed key, or `undefined` when nothing was entered or the user pressed
+ * Ctrl-C. The prompt goes to `write` (stderr), keeping stdout clean.
+ */
+export function promptHiddenKey(stdin, write, prompt = 'API key (usage:write scope; input hidden): ') {
+    return new Promise((resolve) => {
+        let value = '';
+        const finish = (result) => {
+            stdin.removeListener('data', onData);
+            stdin.setRawMode?.(false);
+            stdin.pause();
+            write('\n');
+            resolve(result);
+        };
+        const onData = (chunk) => {
+            for (const ch of typeof chunk === 'string' ? chunk : chunk.toString('utf8')) {
+                if (ENTER.has(ch))
+                    return finish(value.trim() || undefined);
+                if (ch === CTRL_C)
+                    return finish(undefined);
+                if (BACKSPACE.has(ch))
+                    value = value.slice(0, -1);
+                else if (ch >= ' ')
+                    value += ch;
+            }
+        };
+        write(prompt);
+        stdin.setRawMode?.(true);
+        stdin.setEncoding('utf8');
+        stdin.on('data', onData);
+        stdin.resume();
+    });
+}

package/dist/usage/project.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The project a session's working directory belongs to: its repository's name.
+ *
+ * A session can run in the repository root, a subdirectory (`iosApp`,
+ * `Sources`) or a git worktree with a branch-like name
+ * (`.worktrees/backend-service/fix-agent-delete-memory-aware`). All of them
+ * are the one repository, so the project is the basename of the MAIN
+ * repository's root:
+ *
+ * 1. Walk up from the directory to the nearest ancestor holding `.git`.
+ * 2. A `.git` directory: that ancestor is the root.
+ * 3. A `.git` file is a linked worktree (or a submodule): its `gitdir:` names
+ *    `<repo>/.git/worktrees/<name>`, whose `commondir` leads back to
+ *    `<repo>/.git`. A submodule's gitdir has neither, so it is its own project.
+ * 4. A directory that no longer exists (a removed worktree) is recognised by
+ *    its layout — `…/.worktrees/<repo>/<name>` or `…/<repo>/.claude/worktrees/<name>`
+ *    — and is otherwise named by its basename.
+ *
+ * Only the basename ever leaves this module, never the path. Results are
+ * cached per directory: the scanner asks once per log line, and the answer is
+ * a few `stat`s the first time and a map lookup after — never a `git` child
+ * process.
+ *
+ * The walk does what `git` itself does, so a directory under a dotfiles
+ * repository at `~` is attributed to it.
+ */
+/** Forget every cached answer (tests; a long-running process never needs it). */
+export declare function clearProjectCache(): void;
+/** The repository name of a session's working directory, or `null` when it names none. */
+export declare function projectName(cwd: unknown): string | null;

package/dist/usage/project.js

@@ -0,0 +1,138 @@
+/**
+ * The project a session's working directory belongs to: its repository's name.
+ *
+ * A session can run in the repository root, a subdirectory (`iosApp`,
+ * `Sources`) or a git worktree with a branch-like name
+ * (`.worktrees/backend-service/fix-agent-delete-memory-aware`). All of them
+ * are the one repository, so the project is the basename of the MAIN
+ * repository's root:
+ *
+ * 1. Walk up from the directory to the nearest ancestor holding `.git`.
+ * 2. A `.git` directory: that ancestor is the root.
+ * 3. A `.git` file is a linked worktree (or a submodule): its `gitdir:` names
+ *    `<repo>/.git/worktrees/<name>`, whose `commondir` leads back to
+ *    `<repo>/.git`. A submodule's gitdir has neither, so it is its own project.
+ * 4. A directory that no longer exists (a removed worktree) is recognised by
+ *    its layout — `…/.worktrees/<repo>/<name>` or `…/<repo>/.claude/worktrees/<name>`
+ *    — and is otherwise named by its basename.
+ *
+ * Only the basename ever leaves this module, never the path. Results are
+ * cached per directory: the scanner asks once per log line, and the answer is
+ * a few `stat`s the first time and a map lookup after — never a `git` child
+ * process.
+ *
+ * The walk does what `git` itself does, so a directory under a dotfiles
+ * repository at `~` is attributed to it.
+ */
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+const MAX_PROJECT_CHARS = 120;
+/** Directories remembered; far more than one machine's sessions ever name. */
+const MAX_CACHED = 5000;
+/** Deepest walk up from a directory looking for `.git`. */
+const MAX_ANCESTORS = 64;
+const cache = new Map();
+/** Forget every cached answer (tests; a long-running process never needs it). */
+export function clearProjectCache() {
+    cache.clear();
+}
+/** The repository name of a session's working directory, or `null` when it names none. */
+export function projectName(cwd) {
+    if (typeof cwd !== 'string' || !cwd.trim())
+        return null;
+    const dir = cwd.trim().replace(/[\\/]+$/, '');
+    if (!dir)
+        return null;
+    const cached = cache.get(dir);
+    if (cached !== undefined)
+        return cached;
+    const base = path.basename(resolveProjectRoot(dir));
+    const name = base ? base.slice(0, MAX_PROJECT_CHARS) : null;
+    if (cache.size >= MAX_CACHED)
+        cache.clear();
+    cache.set(dir, name);
+    return name;
+}
+/** The directory whose basename names the project. */
+function resolveProjectRoot(dir) {
+    if (!isDirectory(dir))
+        return removedWorktreeRepo(dir) ?? dir;
+    let current = dir;
+    for (let depth = 0; depth < MAX_ANCESTORS; depth += 1) {
+        const root = repoRootAt(current);
+        if (root)
+            return root;
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dir;
+}
+/** The main repository root when `dir` holds a `.git`; `undefined` when it holds none. */
+function repoRootAt(dir) {
+    const dotGit = path.join(dir, '.git');
+    let stat;
+    try {
+        stat = statSync(dotGit);
+    }
+    catch {
+        return undefined;
+    }
+    if (stat.isDirectory())
+        return dir;
+    if (!stat.isFile())
+        return undefined;
+    const gitDir = readGitDir(dotGit);
+    return (gitDir && mainRepoOf(gitDir)) ?? dir;
+}
+/** The `gitdir:` a `.git` file points at, resolved against the file's directory. */
+function readGitDir(dotGitFile) {
+    try {
+        const match = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotGitFile, 'utf8'));
+        return match?.[1] ? path.resolve(path.dirname(dotGitFile), match[1]) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A linked worktree's main repository root, from its gitdir; `undefined` for a submodule. */
+function mainRepoOf(gitDir) {
+    let common;
+    try {
+        const relative = readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim();
+        if (relative)
+            common = path.resolve(gitDir, relative);
+    }
+    catch {
+        // No commondir: read the conventional `<repo>/.git/worktrees/<name>` layout.
+        const match = /^(.*)[\\/]\.git[\\/]worktrees[\\/][^\\/]+$/.exec(gitDir);
+        if (match?.[1])
+            return match[1];
+    }
+    if (!common)
+        return undefined;
+    // `<repo>/.git` → `<repo>`; a bare `<repo>.git` common dir names the repo itself.
+    if (path.basename(common) === '.git')
+        return path.dirname(common);
+    return common.replace(/\.git$/, '') || common;
+}
+/** The repository a removed worktree path belonged to, from the two layouts agents use. */
+function removedWorktreeRepo(dir) {
+    const sep = '[\\\\/]';
+    const claude = new RegExp(`^(.*?)${sep}\\.claude${sep}worktrees${sep}[^\\\\/]+(?:${sep}.*)?$`).exec(dir);
+    if (claude?.[1])
+        return claude[1];
+    const sibling = new RegExp(`${sep}\\.worktrees${sep}([^\\\\/]+)${sep}[^\\\\/]+(?:${sep}.*)?$`).exec(dir);
+    if (sibling?.[1])
+        return sibling[1];
+    return undefined;
+}
+function isDirectory(dir) {
+    try {
+        return statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/usage/scanner.d.ts

@@ -2,7 +2,9 @@
  * Token totals from the session logs Claude Code and Codex already write.
  *
  * Aggregates only: tokens per (local day, account, runtime, model, project),
- * where the project is the basename of the working directory the log names.
+ * where the project is the name of the repository the log's working directory
+ * belongs to — a worktree or a subdirectory counts as its repository (see
+ * `project.ts`).
  * No prompt, reply, tool call or file path ever leaves this module — lines are
  * parsed for their usage counters and nothing else is kept.
  *
@@ -21,9 +23,19 @@
  * Incremental: a cursor per file (byte offset, size, mtime) lives in the scan
  * state, so each pass reads only what was appended. The first pass looks back
  * {@link RETENTION_DAYS} days. Every (day, account) a pass changes is marked dirty and is
- * re-sent whole — the server replaces a day's rows, so a resend is harmless.
+ * re-sent whole, and the upload names it as complete: the server replaces that
+ * day's rows for the account and deletes any it no longer carries, so a resend
+ * is harmless and a renamed project leaves no stale row behind.
+ *
+ * State version 2 changed project attribution (repository, not directory). A
+ * version-1 state is discarded and every log in the window read again; its
+ * per-(day, account) totals are kept as {@link ScanState.legacy}. Those pairs'
+ * server rows still carry per-directory projects, so the uploader sends them
+ * only to a server that replaces a day whole, and only when the rebuild
+ * found at least what version 1 had counted (see `service.ts`).
  */
 import type { AccountRuntime } from '../agent/accounts.js';
+export { projectName } from './project.js';
 /** How far back the first scan looks, and how long totals are kept locally. */
 export declare const RETENTION_DAYS = 30;
 /** Most rows in one `POST /v1/usage/token-totals`. */
@@ -54,7 +66,7 @@ interface CodexCursor {
 }
 type Cursor = ClaudeCursor | CodexCursor;
 export interface ScanState {
-    version: 1;
+    version: 2;
     files: Record<string, Cursor>;
     /** Bucket key ({@link bucketKey}) → totals. */
     buckets: Record<string, Totals>;
@@ -64,11 +76,19 @@ export interface ScanState {
     dirty: string[];
     /** Pending pair → consecutive uploads the server only partly accepted. */
     strikes: Record<string, number>;
+    /**
+     * Pair → what the version-1 state had counted for it, for pairs whose
+     * server rows may still carry per-directory projects. An entry goes once
+     * the pair is replaced whole on the server, or is given up on.
+     */
+    legacy: Record<string, Totals>;
 }
 /** A dirty entry: one account's rows for one day. */
 export declare function pendingKey(day: string, accountKey: string): string;
 /** The day of a dirty entry. */
 export declare function pendingDay(entry: string): string;
+/** The account key of a dirty entry. */
+export declare function pendingAccount(entry: string): string;
 /** Days with anything pending, sorted. */
 export declare function pendingDays(state: ScanState): string[];
 export interface TokenRow {
@@ -93,14 +113,23 @@ export interface ScanSummary {
     touchedDays: string[];
 }
 export declare function emptyScanState(): ScanState;
+/**
+ * Load the scan state. A version-1 state (per-directory projects) is replaced
+ * by an empty one that re-reads every log, keeping its per-pair totals as
+ * {@link ScanState.legacy}.
+ */
 export declare function loadScanState(file: string): ScanState;
+/**
+ * Whether a re-attributed pair's rebuild counted less than version 1 had — a
+ * log rewritten or removed since, or a file that fell out of the window. Its
+ * server rows are then left as they are: mis-attributed, but the right total.
+ */
+export declare function rebuildFellShort(rebuilt: Totals, legacy: Totals): boolean;
 export declare function saveScanState(file: string, state: ScanState): void;
 /** `YYYY-MM-DD` of an instant in a time zone (the machine's by default). */
 export declare function dayKey(ms: number, timeZone?: string): string;
 /** Bucket identity. JSON so it round-trips; the day is first so it can be read cheaply. */
 export declare function bucketKey(day: string, accountKey: string, runtime: AccountRuntime, model: string, project: string | null): string;
-/** Basename of a working directory — the repo or folder name, never the path. */
-export declare function projectName(cwd: unknown): string | null;
 /**
  * One incremental pass over every account's logs. Mutates and returns
  * ``state``; the caller persists it.
@@ -110,8 +139,20 @@ export declare function scanUsage(accounts: ScanAccount[], state: ScanState, opt
 export declare function rowsForDays(state: ScanState, days: Iterable<string>): TokenRow[];
 /** The rows for the given `day|accountKey` pairs, in upload shape. */
 export declare function rowsForPending(state: ScanState, pairs: Iterable<string>): TokenRow[];
-/** Split rows into upload batches. */
-export declare function batches<T>(rows: T[], size?: number): T[][];
+/** One `POST /v1/usage/token-totals` body's rows, and what it says about each (day, account) pair. */
+export interface UploadBatch {
+    rows: TokenRow[];
+    /** Pairs whose first row is here: sent as `completeDays`, so the server replaces each one whole. */
+    complete: string[];
+    /** Pairs whose last row is here: done once this batch is taken. */
+    last: string[];
+}
+/**
+ * Split rows into upload batches without splitting a (day, account) pair,
+ * so each body carries every row of the pairs it names complete. A pair
+ * larger than a batch is sent over consecutive batches: complete in the
+ * first (the server clears its rows, then stores these), added to by the rest.
+ */
+export declare function uploadBatches(rows: TokenRow[], size?: number): UploadBatch[];
 /** Local totals per account since ``fromDay`` (inclusive), for `usage status`. */
 export declare function localTotals(state: ScanState, fromDay: string): Map<string, Totals>;
-export {};