@phnx-labs/agents-cli 1.20.90 → 1.20.92

package/dist/lib/secrets/list-filter.js

@@ -0,0 +1,245 @@
+/**
+ * Filters for `agents secrets list`.
+ *
+ * The listing had no filtering at all: `--host`/`--device` pick a machine and
+ * `--json` picks a format, but nothing selected over the bundles themselves. On
+ * a fleet with fifty-odd bundles the answerable questions — which ones read with
+ * no Touch ID at all, which hold a raw literal, which have already expired, what
+ * has not been touched in three months — meant piping the table through grep, or
+ * were simply unanswerable.
+ *
+ * Everything here is pure: parsing produces a `SecretsListFilter`, and
+ * `bundleMatchesFilter` is a predicate over a bundle plus the ambient facts it
+ * cannot derive itself (which bundles the broker currently holds, and the
+ * current time). That keeps the whole surface unit-testable without a keychain.
+ *
+ * Shape follows the `agents sessions` house style: comma-separated lists, an
+ * unknown value is a loud error naming the valid set (never a silent ignore),
+ * and every axis narrows independently so they AND-compose.
+ */
+import { parseCommaSeparatedList } from '../../commands/utils.js';
+// From the leaf module, NOT discover.js — the latter imports `../sqlite.js`, so
+// reaching through it for one parser would pull node:sqlite into every `agents
+// secrets` invocation and print Node's SQLite ExperimentalWarning on stderr.
+import { parseTimeFilter } from '../session/relative-time.js';
+import { describeBundle, bundlePolicy, SECRET_TYPES, } from './bundles.js';
+/** Ref kinds a var's value can have, from `describeBundle`. */
+export const REF_KINDS = ['literal', 'keychain', 'env', 'file', 'exec'];
+const POLICIES = ['always', 'hold', 'never'];
+const BACKENDS = ['keychain', 'file', 'vault'];
+/** Default window for `--expiring` with no argument — matches the EXPIRING column. */
+export const DEFAULT_EXPIRING_DAYS = 30;
+/**
+ * Validate one comma-separated enum list. An unknown value throws and names the
+ * whole valid set — a silent ignore would let `--policy hodl` quietly return
+ * every bundle, which reads as "nothing matches that" and is worse than an error.
+ * Values are lowercased, matching `parsePolicyOpt`'s handling of policy names.
+ */
+export function parseEnumList(raw, flag, valid) {
+    const parts = parseCommaSeparatedList(raw).map((s) => s.toLowerCase());
+    if (parts.length === 0) {
+        throw new Error(`${flag} requires at least one value. Valid values: ${valid.join(', ')}`);
+    }
+    for (const p of parts) {
+        if (!valid.includes(p)) {
+            throw new Error(`Invalid value "${p}" for ${flag}. Valid values: ${valid.join(', ')}`);
+        }
+    }
+    // De-dup so `--policy hold,hold` behaves like `--policy hold`.
+    return [...new Set(parts)];
+}
+/** Parse `--expiring` — a bare flag means the default window, a value means N days. */
+function parseExpiringDays(raw) {
+    if (raw === undefined || raw === false)
+        return undefined;
+    if (raw === true || raw === '')
+        return DEFAULT_EXPIRING_DAYS;
+    const n = Number(raw);
+    // 0 is rejected rather than accepted as a no-op: the window is `0 <= d < N`,
+    // so `--expiring 0` can never match anything, not even a key expiring today.
+    // A flag that silently returns nothing is worse than one that says why.
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n < 1) {
+        throw new Error(`Invalid --expiring '${raw}'. Use a whole number of days >= 1, e.g. --expiring 7. ` +
+            'For keys that have already lapsed, use --expired.');
+    }
+    return n;
+}
+/** Build a validated filter from commander's option bag. Throws on bad input. */
+export function parseListFilters(opts, query) {
+    if (opts.held && opts.notHeld) {
+        throw new Error('--held and --not-held are mutually exclusive');
+    }
+    const filter = {};
+    const trimmedQuery = query?.trim();
+    if (trimmedQuery)
+        filter.query = trimmedQuery.toLowerCase();
+    if (opts.policy)
+        filter.policy = parseEnumList(opts.policy, '--policy', POLICIES);
+    if (opts.backend)
+        filter.backend = parseEnumList(opts.backend, '--backend', BACKENDS);
+    if (opts.type)
+        filter.type = parseEnumList(opts.type, '--type', SECRET_TYPES);
+    if (opts.kind)
+        filter.kind = parseEnumList(opts.kind, '--kind', REF_KINDS);
+    if (opts.held)
+        filter.held = true;
+    if (opts.notHeld)
+        filter.held = false;
+    if (opts.expired)
+        filter.expired = true;
+    const expiringDays = parseExpiringDays(opts.expiring);
+    if (expiringDays !== undefined)
+        filter.expiringDays = expiringDays;
+    if (opts.unused) {
+        // parseTimeFilter turns '90d' into "the epoch-ms 90 days ago"; a bundle is
+        // unused when its last_used predates that instant.
+        const cutoff = parseTimeFilter(opts.unused);
+        if (!cutoff) {
+            throw new Error(`Invalid --unused '${opts.unused}'. Use e.g. 30d, 4w, 3mo, or an ISO date.`);
+        }
+        filter.unusedBefore = cutoff;
+    }
+    return filter;
+}
+/** True when any axis is set — used to decide whether the empty state should
+ * explain itself rather than claim there are no bundles at all. */
+export function filterIsActive(f) {
+    return Object.keys(f).length > 0;
+}
+/** Whole days from now until end-of-day UTC of an ISO date. Negative once past.
+ * Mirrors the `daysUntil` used by the human render so the filter and the column
+ * can never disagree about whether something has expired. */
+function daysUntil(iso, now) {
+    const target = new Date(`${iso}T23:59:59Z`).getTime();
+    return Math.floor((target - now) / (24 * 60 * 60 * 1000));
+}
+/** Expiry tallies for one bundle: how many vars are already past, and how many
+ * fall due within `withinDays`. */
+export function bundleExpiry(b, now, withinDays = DEFAULT_EXPIRING_DAYS) {
+    let expired = 0;
+    let soon = 0;
+    for (const m of Object.values(b.meta ?? {})) {
+        if (!m.expires)
+            continue;
+        const d = daysUntil(m.expires, now);
+        if (d < 0)
+            expired++;
+        else if (d < withinDays)
+            soon++;
+    }
+    return { expired, soon };
+}
+/** Does this bundle satisfy every set axis? Pure. */
+export function bundleMatchesFilter(b, f, ctx) {
+    if (f.query) {
+        const haystack = `${b.name} ${b.description ?? ''}`.toLowerCase();
+        if (!haystack.includes(f.query))
+            return false;
+    }
+    if (f.policy && !f.policy.includes(bundlePolicy(b)))
+        return false;
+    if (f.backend && !f.backend.includes(b.backend ?? 'keychain'))
+        return false;
+    if (f.held !== undefined) {
+        // A lapsed entry is not held — same liveness rule the POLICY column uses.
+        const exp = ctx.held.get(b.name);
+        const isHeld = exp !== undefined && exp > ctx.now;
+        if (isHeld !== f.held)
+            return false;
+    }
+    if (f.type) {
+        const types = Object.values(b.meta ?? {}).map((m) => m.type).filter(Boolean);
+        if (!types.some((t) => f.type.includes(t)))
+            return false;
+    }
+    if (f.kind) {
+        const kinds = describeBundle(b).map((e) => e.kind);
+        if (!kinds.some((k) => f.kind.includes(k)))
+            return false;
+    }
+    if (f.expired || f.expiringDays !== undefined) {
+        const { expired, soon } = bundleExpiry(b, ctx.now, f.expiringDays ?? DEFAULT_EXPIRING_DAYS);
+        if (f.expired && expired === 0)
+            return false;
+        if (f.expiringDays !== undefined && soon === 0)
+            return false;
+    }
+    if (f.unusedBefore !== undefined) {
+        // Never used counts as unused — it is the strongest form of the answer.
+        if (b.last_used && new Date(b.last_used).getTime() >= f.unusedBefore)
+            return false;
+    }
+    return true;
+}
+/** Sort fields for `--sort`. `name` is the default and matches `listBundles()`. */
+export const SORT_FIELDS = ['name', 'used', 'created', 'updated', 'expiry'];
+export function parseSortField(raw) {
+    if (!raw)
+        return 'name';
+    const v = raw.toLowerCase();
+    if (!SORT_FIELDS.includes(v)) {
+        throw new Error(`Invalid --sort '${raw}'. Valid values: ${SORT_FIELDS.join(', ')}`);
+    }
+    return v;
+}
+/** Epoch-ms of a bundle's soonest expiry, or Infinity when nothing expires — so
+ * `--sort expiry` puts the most urgent first and never-expiring bundles last. */
+function soonestExpiry(b) {
+    let soonest = Infinity;
+    for (const m of Object.values(b.meta ?? {})) {
+        if (!m.expires)
+            continue;
+        const t = new Date(`${m.expires}T23:59:59Z`).getTime();
+        if (t < soonest)
+            soonest = t;
+    }
+    return soonest;
+}
+/** Sort a copy. Time fields are most-recent-first (the useful direction for
+ * "what did I touch lately"); `expiry` is soonest-first; ties fall back to name
+ * so the order is stable. */
+export function sortBundles(bundles, field) {
+    const stamp = (iso) => (iso ? new Date(iso).getTime() : 0);
+    const byName = (a, z) => a.name.localeCompare(z.name);
+    const out = [...bundles];
+    if (field === 'name')
+        return out.sort(byName);
+    out.sort((a, z) => {
+        if (field === 'expiry') {
+            const d = soonestExpiry(a) - soonestExpiry(z);
+            return d !== 0 ? d : byName(a, z);
+        }
+        const key = field === 'used' ? 'last_used' : field === 'created' ? 'created_at' : 'updated_at';
+        const d = stamp(z[key]) - stamp(a[key]);
+        return d !== 0 ? d : byName(a, z);
+    });
+    return out;
+}
+/** Human summary of the active filters, for the empty state. `sessions` only
+ * echoes --project/--all on a miss, which leaves you guessing which flag emptied
+ * the list; naming every active axis is the difference between "nothing matched"
+ * and knowing what to relax. */
+export function describeFilter(f) {
+    const parts = [];
+    if (f.query)
+        parts.push(`matching "${f.query}"`);
+    if (f.policy)
+        parts.push(`policy ${f.policy.join('/')}`);
+    if (f.backend)
+        parts.push(`backend ${f.backend.join('/')}`);
+    if (f.type)
+        parts.push(`type ${f.type.join('/')}`);
+    if (f.kind)
+        parts.push(`kind ${f.kind.join('/')}`);
+    if (f.held === true)
+        parts.push('currently held');
+    if (f.held === false)
+        parts.push('not currently held');
+    if (f.expired)
+        parts.push('with an expired key');
+    if (f.expiringDays !== undefined)
+        parts.push(`expiring within ${f.expiringDays}d`);
+    if (f.unusedBefore !== undefined)
+        parts.push('unused since the given cutoff');
+    return parts.join(', ');
+}

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

@@ -0,0 +1,53 @@
+/**
+ * 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.
+ */
+export type BashCategory = 'vcs' | 'build-test' | 'install' | 'remote' | 'http' | 'media' | 'upscaling' | 'metadata' | 'probe' | 'search' | 'shell' | 'wait' | 'other';
+export interface BashToolInfo {
+    category: BashCategory;
+    signal: 'high' | 'mid' | 'low';
+    action: string;
+    aliases?: string[];
+}
+export interface BashCommandInfo {
+    tool: string;
+    category: BashCategory;
+    subcommand: string;
+    action: string;
+    summary: string;
+    signal: 'high' | 'mid' | 'low';
+}
+export declare function unwrapCommand(cmd: string): string;
+/**
+ * Split a possibly-compound Bash command into simple commands, then tokenize each
+ * with shlex. Returns an empty array for empty input.
+ */
+export declare function tokenizeBash(cmd: string): string[][];
+/**
+ * Classify the first simple command in a Bash string. Returns coarse metadata
+ * (tool name, category, subcommand, human action) used for summaries and
+ * activity logging. Unknown executables fall back to `other`.
+ */
+export declare function classifyBashCommand(command: string): BashCommandInfo;
+/**
+ * Stable bucket key for grouping similar Bash commands in summaries. Commands run
+ * through a remote wrapper (ssh/scp/rsync) get an `ssh→` prefix on the inner key,
+ * so `ssh host "git push"` buckets as `ssh→git push`, distinct from a local push.
+ */
+export declare function bucketKey(command: string): string;
+/**
+ * Detect high-signal Bash-driven milestones (video renders, upscales, metadata
+ * edits, git commits/pushes/worktrees, PR opens). Returns null for routine
+ * commands.
+ */
+export declare function detectBashMilestone(command: string): {
+    event: string;
+    detail: string;
+} | null;
+/**
+ * Human-readable category label for renderers.
+ */
+export declare function categoryLabel(category: BashCategory): string;

package/dist/lib/session/bash-command.js

@@ -0,0 +1,364 @@
+import { split as shlexSplit } from 'shlex';
+const TOOL_REGISTRY = {
+    // VCS
+    git: { category: 'vcs', signal: 'mid', action: 'working in git' },
+    gh: { category: 'vcs', signal: 'mid', action: 'using GitHub CLI' },
+    // Build / test
+    bun: { category: 'build-test', signal: 'mid', action: 'running bun' },
+    npm: { category: 'build-test', signal: 'mid', action: 'running npm' },
+    pnpm: { category: 'build-test', signal: 'mid', action: 'running pnpm' },
+    yarn: { category: 'build-test', signal: 'mid', action: 'running yarn' },
+    vitest: { category: 'build-test', signal: 'mid', action: 'running vitest' },
+    jest: { category: 'build-test', signal: 'mid', action: 'running jest' },
+    mocha: { category: 'build-test', signal: 'mid', action: 'running mocha' },
+    pytest: { category: 'build-test', signal: 'mid', action: 'running pytest' },
+    cargo: { category: 'build-test', signal: 'mid', action: 'running cargo' },
+    go: { category: 'build-test', signal: 'mid', action: 'running go' },
+    tsc: { category: 'build-test', signal: 'mid', action: 'running tsc' },
+    tsx: { category: 'build-test', signal: 'mid', action: 'running tsx' },
+    node: { category: 'build-test', signal: 'low', action: 'running node' },
+    python: { category: 'build-test', signal: 'low', action: 'running python', aliases: ['python3'] },
+    make: { category: 'build-test', signal: 'mid', action: 'running make' },
+    // Install
+    brew: { category: 'install', signal: 'mid', action: 'installing with brew' },
+    pip: { category: 'install', signal: 'mid', action: 'installing with pip', aliases: ['pip3'] },
+    apt: { category: 'install', signal: 'mid', action: 'installing with apt' },
+    apk: { category: 'install', signal: 'mid', action: 'installing with apk' },
+    // Remote
+    ssh: { category: 'remote', signal: 'mid', action: 'using ssh' },
+    scp: { category: 'remote', signal: 'mid', action: 'using scp' },
+    rsync: { category: 'remote', signal: 'mid', action: 'using rsync' },
+    // HTTP
+    curl: { category: 'http', signal: 'mid', action: 'fetching with curl' },
+    wget: { category: 'http', signal: 'mid', action: 'fetching with wget' },
+    // Media
+    ffmpeg: { category: 'media', signal: 'high', action: 'using ffmpeg' },
+    ffprobe: { category: 'media', signal: 'mid', action: 'probing media' },
+    magick: { category: 'media', signal: 'mid', action: 'using ImageMagick' },
+    convert: { category: 'media', signal: 'mid', action: 'converting images' },
+    composite: { category: 'media', signal: 'mid', action: 'compositing images' },
+    montage: { category: 'media', signal: 'mid', action: 'montaging images' },
+    identify: { category: 'media', signal: 'mid', action: 'identifying images' },
+    // Upscaling
+    realesrgan: {
+        category: 'upscaling',
+        signal: 'high',
+        action: 'upscaling with realesrgan',
+        aliases: ['realesrgan-ncnn-vulkan'],
+    },
+    waifu2x: {
+        category: 'upscaling',
+        signal: 'high',
+        action: 'upscaling with waifu2x',
+        aliases: ['waifu2x-caffe', 'waifu2x-converter-cpp'],
+    },
+    swin2sr: { category: 'upscaling', signal: 'high', action: 'upscaling with swin2sr' },
+    resdet: { category: 'upscaling', signal: 'mid', action: 'detecting upscale' },
+    // Metadata
+    id3v2: { category: 'metadata', signal: 'mid', action: 'editing id3 tags' },
+    exiftool: { category: 'metadata', signal: 'mid', action: 'editing exif metadata' },
+    metaflac: { category: 'metadata', signal: 'mid', action: 'editing flac metadata' },
+    vorbiscomment: { category: 'metadata', signal: 'mid', action: 'editing vorbis comments' },
+    // Shell
+    rm: { category: 'shell', signal: 'low', action: 'removing files' },
+    mv: { category: 'shell', signal: 'low', action: 'moving files' },
+    cp: { category: 'shell', signal: 'low', action: 'copying files' },
+    mkdir: { category: 'shell', signal: 'low', action: 'making directories' },
+    touch: { category: 'shell', signal: 'low', action: 'touching files' },
+    echo: { category: 'shell', signal: 'low', action: 'echoing' },
+    printf: { category: 'shell', signal: 'low', action: 'printing' },
+    chmod: { category: 'shell', signal: 'low', action: 'changing permissions' },
+    ln: { category: 'shell', signal: 'low', action: 'linking files' },
+    awk: { category: 'shell', signal: 'low', action: 'running awk' },
+    sed: { category: 'shell', signal: 'low', action: 'running sed' },
+    tee: { category: 'shell', signal: 'low', action: 'teeing output' },
+    xargs: { category: 'shell', signal: 'low', action: 'running xargs' },
+    // Probes
+    ls: { category: 'probe', signal: 'low', action: 'listing files' },
+    cat: { category: 'probe', signal: 'low', action: 'reading files' },
+    head: { category: 'probe', signal: 'low', action: 'reading files' },
+    tail: { category: 'probe', signal: 'low', action: 'reading files' },
+    wc: { category: 'probe', signal: 'low', action: 'counting' },
+    stat: { category: 'probe', signal: 'low', action: 'statting files' },
+    file: { category: 'probe', signal: 'low', action: 'inspecting files' },
+    which: { category: 'probe', signal: 'low', action: 'locating binaries' },
+    tree: { category: 'probe', signal: 'low', action: 'listing files' },
+    pwd: { category: 'probe', signal: 'low', action: 'printing pwd' },
+    // Search
+    grep: { category: 'search', signal: 'low', action: 'searching' },
+    rg: { category: 'search', signal: 'low', action: 'searching with ripgrep' },
+    ag: { category: 'search', signal: 'low', action: 'searching with the silver searcher' },
+    fd: { category: 'search', signal: 'low', action: 'searching files' },
+    find: { category: 'search', signal: 'low', action: 'finding files' },
+    // Wait
+    sleep: { category: 'wait', signal: 'low', action: 'sleeping' },
+    wait: { category: 'wait', signal: 'low', action: 'waiting' },
+};
+/**
+ * Two-level tools (bucket key includes the subcommand) mapped to the flags that
+ * consume the *following* token as their value, per tool. The subcommand scan
+ * skips both a value flag and its argument, so `git -C /repo commit` → `commit`
+ * and `kubectl -n prod get` → `get`. Missing a value flag mis-reads the value as
+ * the subcommand; over-listing one only drops the subcommand (a safe tool-only
+ * bucket), so err toward listing. A tool with no such leading flags maps to an
+ * empty set. TWO_LEVEL_TOOLS is derived from these keys so the two never drift.
+ */
+const VALUE_FLAGS = {
+    git: new Set(['-C', '-c', '--git-dir', '--work-tree']),
+    gh: new Set(['-R', '--repo']),
+    bun: new Set(['--cwd']),
+    npm: new Set(['--prefix', '-w', '--workspace']),
+    pnpm: new Set(['--filter', '-C', '--dir']),
+    yarn: new Set(['--cwd']),
+    cargo: new Set(['--manifest-path']),
+    docker: new Set(['-H', '--host', '-c', '--context', '--config', '-l', '--log-level']),
+    kubectl: new Set(['-n', '--namespace', '--kubeconfig', '--context', '--cluster', '--user', '-s', '--server', '--as', '--token', '--cache-dir', '--request-timeout']),
+    rush: new Set(),
+    openclaw: new Set(),
+};
+/** Tools whose bucket key includes the second token (subcommand). */
+const TWO_LEVEL_TOOLS = new Set(Object.keys(VALUE_FLAGS));
+/** Remote wrappers whose bucket key carries an `ssh→` prefix on the inner command. */
+const REMOTE_WRAPPERS = new Set(['ssh', 'scp', 'rsync']);
+const ALIAS_MAP = new Map();
+for (const [name, info] of Object.entries(TOOL_REGISTRY)) {
+    ALIAS_MAP.set(name, name);
+    for (const alias of info.aliases ?? []) {
+        ALIAS_MAP.set(alias, name);
+    }
+}
+export function unwrapCommand(cmd) {
+    const s = cmd.trim();
+    // ssh host command
+    const ssh = s.match(/^ssh\s+\S+\s+["']?(.+?)["']?\s*(?:\|.*)?$/);
+    if (ssh)
+        return unwrapCommand(ssh[1]);
+    // VAR=value prefix (value may be a single- or double-quoted string with spaces)
+    const env = s.match(/^([A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)\s+)+(.+)$/);
+    if (env)
+        return unwrapCommand(env[2]);
+    // sudo / time prefix (value-taking flags like `-u user` consume their argument)
+    const prefix = s.match(/^(?:sudo|time)(?:\s+(?:-[uUgGhpCrtDR]\s+\S+|-\S+))*\s+(.+)$/);
+    if (prefix)
+        return unwrapCommand(prefix[1]);
+    // cd foo && command
+    const cd = s.match(/^cd\s+\S+\s*&&\s*(.+)$/);
+    if (cd)
+        return unwrapCommand(cd[1]);
+    // npx / bunx
+    const npx = s.match(/^(?:npx|bunx)\s+(?:-\S+\s+)*(.+)$/);
+    if (npx)
+        return unwrapCommand(npx[1]);
+    return s;
+}
+function splitOnOperators(cmd) {
+    const parts = [];
+    let current = '';
+    let quote = null;
+    let escaped = false;
+    let i = 0;
+    while (i < cmd.length) {
+        const ch = cmd[i];
+        if (escaped) {
+            current += ch;
+            escaped = false;
+            i += 1;
+            continue;
+        }
+        if (ch === '\\') {
+            current += ch;
+            escaped = true;
+            i += 1;
+            continue;
+        }
+        if (quote) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            i += 1;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            current += ch;
+            quote = ch;
+            i += 1;
+            continue;
+        }
+        if (cmd.slice(i, i + 2) === '&&' || cmd.slice(i, i + 2) === '||') {
+            if (current.trim())
+                parts.push(current.trim());
+            current = '';
+            i += 2;
+            continue;
+        }
+        if (ch === '|' || ch === ';') {
+            if (current.trim())
+                parts.push(current.trim());
+            current = '';
+            i += 1;
+            continue;
+        }
+        current += ch;
+        i += 1;
+    }
+    if (current.trim())
+        parts.push(current.trim());
+    return parts;
+}
+/**
+ * Split a possibly-compound Bash command into simple commands, then tokenize each
+ * with shlex. Returns an empty array for empty input.
+ */
+export function tokenizeBash(cmd) {
+    const unwrapped = unwrapCommand(cmd);
+    const segments = splitOnOperators(unwrapped);
+    const out = [];
+    for (const seg of segments) {
+        try {
+            const tokens = shlexSplit(seg);
+            if (tokens.length)
+                out.push(tokens);
+        }
+        catch {
+            // If shlex can't parse, fall back to whitespace split.
+            const tokens = seg.split(/\s+/).filter(Boolean);
+            if (tokens.length)
+                out.push(tokens);
+        }
+    }
+    return out;
+}
+/**
+ * First non-flag token after the executable — its subcommand. Skips leading
+ * flags, and skips the argument of a value-taking flag for that tool (see
+ * VALUE_FLAGS) so e.g. `git -C /repo commit` resolves to `commit`, not `-C`, and
+ * `kubectl -n prod get` resolves to `get`, not `prod`.
+ */
+function scanSubcommand(tokens, tool) {
+    const valueFlags = VALUE_FLAGS[tool];
+    let i = 1;
+    while (i < tokens.length) {
+        const t = tokens[i];
+        if (t.startsWith('-')) {
+            i += valueFlags?.has(t) ? 2 : 1;
+            continue;
+        }
+        return t.toLowerCase();
+    }
+    return '';
+}
+/**
+ * Classify the first simple command in a Bash string. Returns coarse metadata
+ * (tool name, category, subcommand, human action) used for summaries and
+ * activity logging. Unknown executables fall back to `other`.
+ */
+export function classifyBashCommand(command) {
+    const simpleCommands = tokenizeBash(command);
+    if (!simpleCommands.length) {
+        return { tool: 'other', category: 'other', subcommand: '', action: 'running command', summary: '', signal: 'low' };
+    }
+    const tokens = simpleCommands[0];
+    if (!tokens.length) {
+        return { tool: 'other', category: 'other', subcommand: '', action: 'running command', summary: '', signal: 'low' };
+    }
+    const first = tokens[0];
+    const baseRaw = first.replace(/^[./]+/, '').toLowerCase();
+    const base = baseRaw.endsWith('.exe') ? baseRaw.slice(0, -4) : baseRaw;
+    const canonical = ALIAS_MAP.get(base);
+    const info = canonical ? TOOL_REGISTRY[canonical] : undefined;
+    if (!info) {
+        // Unknown executable. A known two-level tool that isn't in the registry
+        // (docker/kubectl/rush/openclaw) still surfaces its subcommand so bucketing
+        // stays useful; the category stays honestly 'other'.
+        const subcommand = TWO_LEVEL_TOOLS.has(base) ? scanSubcommand(tokens, base) : '';
+        const summary = subcommand ? `${base} ${subcommand}` : base;
+        return { tool: base, category: 'other', subcommand, action: 'running command', summary, signal: 'low' };
+    }
+    const subcommand = canonical && TWO_LEVEL_TOOLS.has(canonical) ? scanSubcommand(tokens, canonical) : '';
+    const safeCanonical = canonical || base;
+    const summary = subcommand ? `${safeCanonical} ${subcommand}` : safeCanonical;
+    return {
+        tool: safeCanonical,
+        category: info.category,
+        subcommand,
+        action: info.action,
+        summary,
+        signal: info.signal,
+    };
+}
+/**
+ * Stable bucket key for grouping similar Bash commands in summaries. Commands run
+ * through a remote wrapper (ssh/scp/rsync) get an `ssh→` prefix on the inner key,
+ * so `ssh host "git push"` buckets as `ssh→git push`, distinct from a local push.
+ */
+export function bucketKey(command) {
+    const info = classifyBashCommand(command);
+    const base = !info.tool
+        ? 'other'
+        : info.subcommand && TWO_LEVEL_TOOLS.has(info.tool)
+            ? `${info.tool} ${info.subcommand}`
+            : info.tool;
+    const first = command.trim().split(/\s+/)[0]?.toLowerCase() ?? '';
+    return REMOTE_WRAPPERS.has(first) ? `ssh→${base}` : base;
+}
+/**
+ * Detect high-signal Bash-driven milestones (video renders, upscales, metadata
+ * edits, git commits/pushes/worktrees, PR opens). Returns null for routine
+ * commands.
+ */
+export function detectBashMilestone(command) {
+    const info = classifyBashCommand(command);
+    const lower = (command || '').toLowerCase();
+    if (info.category === 'upscaling') {
+        return { event: 'image.upscaled', detail: info.action };
+    }
+    if (info.tool === 'ffmpeg') {
+        const hasOutput = /\s+\S+\.\w{2,5}\s*$/.test(command || '');
+        if (hasOutput || lower.includes('-c:v') || lower.includes('-codec') || lower.includes('libx264')) {
+            return { event: 'video.rendered', detail: 'ffmpeg render' };
+        }
+        return { event: 'video.converted', detail: 'ffmpeg' };
+    }
+    if (info.category === 'metadata') {
+        return { event: 'metadata.edited', detail: info.action };
+    }
+    if (info.tool === 'git') {
+        if (info.subcommand === 'commit')
+            return { event: 'commit.created', detail: 'git commit' };
+        if (info.subcommand === 'push')
+            return { event: 'pushed', detail: 'git push' };
+        if (info.subcommand === 'worktree') {
+            if (lower.includes('worktree add'))
+                return { event: 'worktree.created', detail: 'git worktree add' };
+            if (lower.includes('worktree remove'))
+                return { event: 'worktree.removed', detail: 'git worktree remove' };
+        }
+    }
+    if (info.tool === 'gh' && info.subcommand === 'pr') {
+        if (lower.includes('pr create'))
+            return { event: 'pr.opened', detail: 'gh pr create' };
+        if (lower.includes('pr merge'))
+            return { event: 'pr.merged', detail: 'gh pr merge' };
+    }
+    return null;
+}
+/**
+ * Human-readable category label for renderers.
+ */
+export function categoryLabel(category) {
+    switch (category) {
+        case 'vcs': return 'Version control';
+        case 'build-test': return 'Build / test';
+        case 'install': return 'Install';
+        case 'remote': return 'Remote';
+        case 'http': return 'HTTP';
+        case 'media': return 'Media';
+        case 'upscaling': return 'Upscaling';
+        case 'metadata': return 'Metadata';
+        case 'probe': return 'Probes';
+        case 'search': return 'Search';
+        case 'shell': return 'Shell';
+        case 'wait': return 'Wait';
+        default: return 'Other';
+    }
+}