Module cli_prune 

Which installed provider CLIs can go, decided by disuse and never by version number (docs/specs/SPEC_RUNTIME_MENU_REMAINING_GAPS_2026_10_01.md §5).

shared/cli/<provider>/<pin>/ is shared by every AgentMux version and channel on the machine, and they can run at the same time: an older build pins an older CLI, so “everything but the newest” would pull a CLI out from under a live agent. A directory is removable only when ALL hold:

• it is not the current pin of any provider in this build’s registry;
• nothing has used it for max_idle (see record_use);
• no live controller’s command and no running process’s command line mentions it (a scan that FAILS means “in use”: see InUse);
• the install lock can be taken without waiting.

Legacy per-version folders (instances/v<version>/cli/<provider>) go by the same rules, except that their age is their install time and the running version’s own folder is never touched.

Nothing here runs by itself: plan_prune only reads, and prune is called by whoever decides it is time (§5.8 is an open owner decision on automatic vs opt-in).

Structs

Candidate

InUse

What is running right now, as text to search for install paths in.

Plan

Report

Run

The outcome of one run.

Enums

Keep

Constants

DEFAULT_MAX_IDLE

The default line (spec §5.4): 30 days without use.

LAST_USED_MARKER

Touched whenever an install is handed out; only its mtime matters.

RECORD_USE_EVERY

How often record_use actually writes: the marker is on the path that resolves a CLI for every spawn, so it must stay cheap.

Functions

current_pins

(provider, pin) of every provider in this build’s registry that has a pin.

dir_size 🔒

Total size of the files under dir, never following a symlink.

gather_in_use

What running things mention, for plan_prune / prune: the commands of every block that records one (live_commands: open panes AND panes restored from a layout, which hold the absolute CLI path until they mount) and every running process’s command line.

last_activity 🔒

The latest sign of life: the newest of the last-used marker and the install marker; the directory’s own mtime when neither exists.

plan_prune

Decide what could be removed. Reads only; nothing is touched.

prune

Remove what plan_prune found, re-checking each directory at the last moment: in_use is asked again (a CLI may have started since the plan), and a shared install’s lock must be free. The completion marker goes FIRST, so a directory half removed by a crash is already “not an install” and the next install into it clears the rest.

record_use

Note that dir was just used. Best effort, throttled to RECORD_USE_EVERY by the marker’s own mtime; an error is ignored (a failure to record can only make the directory look older, and the other guards still apply).

run

Plan, and unless dry_run, carry out, a prune. dry_run is the caller’s explicit choice to delete: nothing in AgentMux calls this with false except a user action.

safe_children 🔒

Immediate subdirectories of dir as (name, path), skipping symlinks and unsafe names (reported through kept).

scan_process_commands

The running processes’ command lines. Unix: ps; Windows is not scanned (None, so nothing is pruned there until it is).