Experience-Driven Black-Box Cost Control for Coding Agents
Python agentic-aiagentic-codingai-codingai-coding-assistantanthropicartificial-intelligenceclaude-codecodexcoding-agentcoding-agentscost-optimizationcost-reductiondeveloper-toolsgithub-copilotllmopen-sourceopenaiproductivitytoken-optimization
command mismatch fixed
Aaron3ff1eff03e65
diff --git a/README.md b/README.mdindex 1b822ec..742b3c7 100644--- a/README.md+++ b/README.md@@ -70,65 +70,95 @@ The paper evaluates these mechanisms with Claude Code, Codex and the Copilot CLIWeb-Bench and two security benchmarks; [`experiments/`](experiments/README.md) reruns theSWE-Bench and Web-Bench experiments.-## Supported agents--| Agent | Install |-|---|---|-| Claude Code | `claude plugin marketplace add /path/to/TokenEconomizer`<br>`claude plugin install tokeneconomizer@tokeneconomizer` |-| Codex | `codex plugin marketplace add /path/to/TokenEconomizer`<br>`codex plugin add tokeneconomizer@tokeneconomizer`, then trust its hooks when Codex asks |-| Copilot CLI | `copilot plugin marketplace add /path/to/TokenEconomizer`<br>`copilot plugin install tokeneconomizer@tokeneconomizer` |-| Pi | `pi install git:github.com/microsoft/TokenEconomizer` |--**Any plan or login works.** The plugin runs inside your agent's own sessions and never handles-credentials, so it works with whatever your agent is signed in with: a Claude subscription or an-Anthropic API key for Claude Code, a ChatGPT plan or an OpenAI API key for Codex, a Copilot-subscription or a bring-your-own-key provider for the Copilot CLI, and any provider Pi is set up-with. It needs no API key of its own.--Claude Code, Codex and the Copilot CLI install from a clone of this repository, through their-own plugin commands; Pi installs the package straight from GitHub, as any Pi package does. You-need Python 3.10 or newer on `PATH`, and nothing else. Plugins load when a session starts, so-start a new one. **[`plugin/README.md`](plugin/README.md)** walks through each agent: the first-run, its commands, updating, uninstalling, Copilot with your own model key, and troubleshooting.-## Quick start-```bash-git clone https://github.com/microsoft/TokenEconomizer.git-claude plugin marketplace add ./TokenEconomizer-claude plugin install tokeneconomizer@tokeneconomizer-```--Then, in a new Claude Code session inside one of your repositories:--```text-/tokeneconomizer:toolprune refresh-catalog # once on this machine: record the tools a session loads-```--Work as usual; the plugin needs nothing from you. To see what it is doing:--| Command | What it shows or does |-|---|---|-| `/tokeneconomizer:status` | what it learned in this repository, what it did, and what your sessions cost |-| `/tokeneconomizer:microskills` | the facts it injects at session start, and those still forming |-| `/tokeneconomizer:toolprune` | the proposed deny list and its evidence; `… apply` accepts it, `… restore` undoes it |-| `/tokeneconomizer:config` | the settings: what is on, and every value in effect |--On Codex, ask for them or name the skill (`$tokeneconomizer-status`, `-microskills`,-`-toolprune`, `-config`); on Pi they are `/te <command>`. On any agent they are also free from a-terminal inside the repository, as `~/.tokeneconomizer/bin/te <command>`.+You need one of the four agents, signed in any way it supports, and Python 3.10 or newer on+`PATH`. The plugin runs inside your agent's own sessions and never handles credentials, so any+plan or login works (a Claude subscription or Anthropic API key, a ChatGPT plan or OpenAI API+key, a Copilot subscription or your own model key, any provider Pi is set up with), and it needs+no API key of its own.++### Install++Steps 1 and 2 run in your shell; steps 4 and 5 are typed into the agent, in a new session+started inside one of your repositories.++| | Claude Code | Codex | Copilot CLI | Pi |+|---|---|---|---|---|+| **1. Get it** | `git clone https://github.com/microsoft/TokenEconomizer.git` | same as Claude Code | same as Claude Code | nothing to clone |+| **2. Install** | `claude plugin marketplace add "$PWD/TokenEconomizer"`<br>`claude plugin install tokeneconomizer@tokeneconomizer` | `codex plugin marketplace add "$PWD/TokenEconomizer"`<br>`codex plugin add tokeneconomizer@tokeneconomizer` | `copilot plugin marketplace add "$PWD/TokenEconomizer"`<br>`copilot plugin install tokeneconomizer@tokeneconomizer` | `pi install git:github.com/microsoft/TokenEconomizer` |+| **3. Start a session** | trust the folder when asked (**Yes, I trust this folder**) | **Trust and continue** for the folder, then at **Hooks need review** choose **Trust all and continue**; the hooks run from the next session on | **Yes, and remember this folder for future sessions** | nothing to approve |+| **4. Check it** | `/tokeneconomizer:status`, allowing its script if asked | `$tokeneconomizer:status` | `/tokeneconomizer:status`, choosing **Yes** to run its script | `/te status` |+| **5. Once per machine** | `/tokeneconomizer:toolprune refresh-catalog` | not needed | `/tokeneconomizer:toolprune refresh-catalog` | not needed |+| **Update** | `git pull` in the clone | `git pull` in the clone, then `codex plugin add tokeneconomizer@tokeneconomizer` again | `git pull` in the clone | `pi update --extensions` |++Run step 2 where you ran step 1. The marketplace path must be absolute (the Copilot CLI reads+`./TokenEconomizer` as the name of a GitHub repository), and the clone must stay where it is:+Claude Code, Codex and the Copilot CLI run the plugin from it. Pi can install from the clone too,+as `pi install ./TokenEconomizer`. Step 4 prints a short status block. Step 5 records which tools+a session loads, with no model call, so that tool pruning sees all of them; repeat it after the+agent updates. Uninstalling, Copilot with your own model key, and troubleshooting are in+**[`plugin/README.md`](plugin/README.md)**, which walks through each agent.++### Supported versions++The commands in this section were checked on these versions:++| Agent | Checked on | Older versions |+|---|---|---|+| Claude Code | 2.1.306, 2.1.300 | not supported |+| Codex | 0.163.0, 0.153.1 | not supported (before 0.141.0, Codex does not run the plugin's hooks at all) |+| Copilot CLI | 1.0.101, 1.0.83 | not supported |+| Pi | 1.3.0, 1.2.0 | 0.99.x: instead of step 2, start each session with `pi --extension /path/to/TokenEconomizer/plugin/pi/tokeneconomizer.ts`; older: not supported |++### Everyday commands++Work as usual; the plugin needs nothing from you. To see what it does, or to change it:++| To | Claude Code | Codex | Copilot CLI | Pi |+|---|---|---|---|---|+| see what it learned and did, and what sessions cost | `/tokeneconomizer:status` | `$tokeneconomizer:status` | `/tokeneconomizer:status` | `/te status` |+| see the facts it injects, and those forming | `/tokeneconomizer:microskills` | `$tokeneconomizer:microskills` | `/tokeneconomizer:microskills` | `/te microskills` |+| review the proposed deny list | `/tokeneconomizer:toolprune` | `$tokeneconomizer:toolprune` | `/tokeneconomizer:toolprune` | not used: Pi loads four tools |+| accept it, from the next session | `/tokeneconomizer:toolprune apply` | `$tokeneconomizer:toolprune apply` | `/tokeneconomizer:toolprune apply` | — |+| undo it | `/tokeneconomizer:toolprune restore` | `$tokeneconomizer:toolprune restore` | `/tokeneconomizer:toolprune restore` | — |+| show every setting in effect | `/tokeneconomizer:config` | `$tokeneconomizer:config` | `/tokeneconomizer:config` | `/te config` |+| turn a mechanism off in this repository | `/tokeneconomizer:config set loopguard=off` | `$tokeneconomizer:config set loopguard=off` | `/tokeneconomizer:config set loopguard=off` | `/te config set loopguard=off` |+| ... or in every repository | `/tokeneconomizer:config set loopguard=off --global` | `$tokeneconomizer:config set loopguard=off --global` | `/tokeneconomizer:config set loopguard=off --global` | `/te config set loopguard=off --global` |+| put a setting back to its default | `/tokeneconomizer:config unset loopguard` | `$tokeneconomizer:config unset loopguard` | `/tokeneconomizer:config unset loopguard` | `/te config unset loopguard` |+| list every repository it keeps state for | `/tokeneconomizer:repos` | `$tokeneconomizer:repos` | `/tokeneconomizer:repos` | `/te repos` |+| **from a terminal**, inside the repository | `~/.tokeneconomizer/bin/te --host claude status` | `~/.tokeneconomizer/bin/te --host codex status` | `~/.tokeneconomizer/bin/te --host copilot status` | `~/.tokeneconomizer/bin/te --host pi status` |+| check the installation (terminal only) | `~/.tokeneconomizer/bin/te --host claude doctor` | `~/.tokeneconomizer/bin/te --host codex doctor` | `~/.tokeneconomizer/bin/te --host copilot doctor` | `~/.tokeneconomizer/bin/te --host pi doctor` |++Inside an agent, each command is one model turn. Codex has no plugin slash commands, so there they+are skills, named like the slash commands: type `$tokeneconomizer` and pick one. (A question in+plain words may be answered from the plugin's files without running the command; naming the skill+runs it.) A Codex command that changes something (`config set`, `toolprune apply`, ...) writes+outside Codex's sandbox, so Codex asks first: choose **Yes, proceed**. The Copilot CLI runs slash+commands in its interactive mode only, and asks before each: choose **Yes**. From a terminal every+command is free: put any of the ones above after `te --host <agent>` (`te --host codex toolprune+apply`, `te --host pi repos`; settings are shared by every agent, so `te config set loopguard=off+--global` needs none). From a plain terminal, `te` without `--host` means the agent that last worked+in the repository. The launcher in `~/.tokeneconomizer/bin` is written by the first session.## Settings+The three mechanisms are `microskills`, `toolprune` and `loopguard`; each takes `on` or `off`,+and each has numbers you can tune with the same `config set` command (in Claude Code's form here;+each agent's is in the table above):+```text-/tokeneconomizer:config set loopguard=off # one mechanism off, in this repository-/tokeneconomizer:config set toolprune=off --global # ... or in every repository-/tokeneconomizer:config set microskills_max_facts=2 # tune one: inject at most two facts+/tokeneconomizer:config set microskills_max_facts=2 # inject at most two facts+/tokeneconomizer:config set toolprune_evidence=10 # propose after ten unused sessions+/tokeneconomizer:config set loopguard=stop # stop stuck headless turns (Claude, Pi)```-The paid helpers -- an LLM fact proposer and a judge for the loop guard -- are off unless you set-`paid=true`; they run through your own agent's CLI, on the same plan or login as your sessions.-Every setting, its default and its environment variable: [Settings](plugin/README.md#settings).+For one session only, set an environment variable when you start the agent:+`TE_DISABLE=1 claude` turns the whole plugin off, and `TE_LOOPGUARD=off codex` (likewise+`TE_MICROSKILLS`, `TE_TOOLPRUNE`) one mechanism. The paid helpers -- an LLM fact proposer and a+judge for the loop guard -- are off unless you set `paid=true`; they run through your own agent's+CLI, on the same plan or login as your sessions. Every setting, its default and its environment+variable: [Settings](plugin/README.md#settings).## What it does on each agentdiff --git a/docs/PLUGIN.md b/docs/PLUGIN.mdindex 87379e2..c234543 100644--- a/docs/PLUGIN.md+++ b/docs/PLUGIN.md@@ -124,6 +124,16 @@ isolated `CODEX_HOME`, `--dangerously-bypass-hook-trust`; 2026-09-30):…), which listed every command twice in its skill picker beside `codex-skills/`. The slashcommands therefore live in `slash-commands/`, which the Claude Code and Copilot manifests nameand Codex does not read (verified 2026-10-17).+* Codex lists a plugin's skills under the plugin's name, `tokeneconomizer:<skill>` (every release+ from 0.131.0, the first with `codex plugin add`, to 0.163.0), and in `codex exec` a `$` mention+ matches only that full name: `$tokeneconomizer-status`, the name these guides once gave, reached+ no skill. The skills are therefore named after the commands, so `$tokeneconomizer:status` reads+ as `/tokeneconomizer:status` does on the other agents (verified 2026-10-21, with arguments:+ `$tokeneconomizer:config set loopguard=off --global`). Releases before 0.141.0 install the+ plugin but never run its hooks (tried: 0.131.0, 0.135.0, 0.140.0).+ A question in plain words is a weaker route: on `gpt-5.4-mini`, *"what has TokenEconomizer+ learned here?"* ran the skill's command in none of six `codex exec` runs, under either naming+ (the model read the plugin's state files instead), so the guides name the skill.Hooks are **trust-gated**: skipped until approved in `/hooks` (stored as`[hooks.state.<key>].trusted_hash`), unless the run passes `--dangerously-bypass-hook-trust`.@@ -306,13 +316,67 @@ needed sessions that edited different files and, once injected, decayed (the folwhat the session was given); a Codex install copy had no package; side calls failed silentlyand left sessions in Claude Code's history; `te` without `--host` showed Claude Code's state.+**Again as a new user, interactively, 2026-10-21** -- one fresh home for all four agents (Claude+Code 2.1.306, Codex 0.163.0, Copilot CLI 1.0.101, Pi 1.3.0; every model through OpenRouter),+the main README's Quick start typed as written. `git clone https://github.com/microsoft/…` and+`pi install git:github.com/microsoft/…` ran unchanged, a `url.insteadOf` in the new user's+`~/.gitconfig` pointing them at a local repository of the tree. Each agent then ran in its own+terminal UI: the first-run prompts, every Everyday command, the Update row, and a session that+ended and was folded and priced. What the run showed:++* Claude Code asks a new user to trust the folder (**Yes, I trust this folder**); its default+ auto mode then ran the plugin's script with no prompt.+* Codex asks for the folder (**Trust and continue**), then **Hooks need review**: **Review+ hooks**, **Trust all and continue**, or continue without them. Its default sandbox keeps+ `~/.tokeneconomizer` read-only, and `$tokeneconomizer:config set …` failed with a traceback+ until the skills that change state asked to leave the sandbox (`sandbox_permissions:+ require_escalated`); Codex now asks the user, and `te` refuses a change it could only half+ make. `/exit` keeps a session open to `codex resume` and sends no `SessionEnd`, so such a+ session is folded at a later session start once quiet; `codex debug prompt-input` sends a+ `SessionEnd` for a thread that never started, which the plugin now ignores.+* Copilot offers **Yes, and remember this folder for future sessions**, which a deny list in+ `.github/copilot` needs. It substituted a slash command's arguments into `$ARGUMENTS`, yet the+ model ran `config show` for `config set loopguard=off` three times: the command's text said+ "use `show` when no arguments were given" and "do not run `set` … unless those words appear in+ the arguments above". Rewritten to name the typed arguments plainly, it ran what was typed.+* Pi announced `pi update --extensions` itself when the repository moved on, and `/te` answered+ in its terminal UI with no model call.+## 4. State and privacyAll state is local, under `$TOKENECONOMIZER_HOME` (default `~/.tokeneconomizer`), one directoryper repository and host: the mechanisms' own state, `ledger.jsonl` (one priced record per-session), `events.jsonl` (every injection, nudge, stop), and per-session guard state. A-repository is identified by its `origin` remote, so worktrees and re-clones share what was-learned. Uninstalling the plugin leaves this directory; delete it to forget. Like the agents'+session), `events.jsonl` (every injection, nudge, stop), and per-session guard state.+Uninstalling the plugin leaves this directory; delete it to forget. `te repos` lists what it+holds.++Which repository a session belongs to (`plugin/paths.py`, `plugin/repos.py`):++* **One key per repository.** A checkout with an `origin` remote is identified by the remote, so+ every clone, worktree and re-clone shares what was learned, whatever its folder is called; one+ without a remote by its main checkout's path (its worktrees share it); a directory outside any+ checkout by itself. A `.git` counts only as git counts it -- a directory holding `HEAD`, or a+ `gitdir:` file naming one that exists -- and the walk up from a session's directory stops at+ the home directory, so a versioned (or stray, empty) `~/.git` is the repository of sessions+ started in `~` and of nothing below it. `GIT_CEILING_DIRECTORIES` is honoured as git does.+* **One repository per session.** A hook's `cwd` is where the agent is now (Claude Code's+ follows its `cd`), so the first hook of a session pins it (`sessions/<host>/<id>.json`) and+ every later hook, and the fold it hands off, uses the repository it started in -- where the+ agent files its own session log. `te status` run inside a session says so when the two differ.+* **Deny lists stay per checkout.** The clones of a repository share its evidence and proposal,+ but each has its own settings file, so `untool_applied.json` records what was added per file.+* **State from earlier keys is carried over.** Up to 0.1.0 a checkout's folder name was part of+ the key, any `.git` entry made a checkout, and a session was recorded wherever the agent was.+ The first time a checkout is seen (`index.json`) the state under its earlier keys is sent+ where it belongs, and once after an upgrade a background `te repos migrate` does the same for+ every directory: each recorded session goes to the repository the first directory in its log+ resolves to now, sessions whose directory is gone stay put, and a directory none of whose+ sessions resolves to it any more is merged whole -- its learned state too, if it learned from+ more sessions than the destination. Learned state is not additive, so the other side's+ sessions are folded again from their logs where those still exist; a session folded under two+ keys counts once, at its later fold. Nothing is deleted: a merged directory moves to+ `merged/`, displaced learned state to `premerge-*`. `te repos merge KEY [INTO]` joins two by+ hand, for state whose checkouts are gone. Like the agents'own session logs it is derived from, it is private to you: the plugin creates it `0700` and itsfiles `0600`, and tightens a looser one it finds.diff --git a/plugin/README.md b/plugin/README.mdindex 3495ede..856139e 100644--- a/plugin/README.md+++ b/plugin/README.md@@ -13,11 +13,13 @@ behaviour of each agent are in [`docs/PLUGIN.md`](../docs/PLUGIN.md).## Before you start-- [ ] Your agent installed and signed in, any way it supports (a subscription or an API key)+- [ ] Your agent installed and signed in, any way it supports (a subscription or an API key), at a+ version the commands were checked on ([Supported versions](../README.md#supported-versions))- [ ] Python 3.10 or newer on `PATH` (or set `TE_PYTHON=/path/to/python3.10+`)- [ ] Access to this repository on GitHub- [ ] Copilot CLI only: the repository's folder trusted by Copilot (it asks the first time you- start it there); Copilot ignores a folder's `.github/copilot` settings otherwise+ start it there: choose **Yes, and remember this folder for future sessions**); Copilot ignores a+ folder's `.github/copilot` settings otherwiseNo extra API key is needed. Plugins load when a session starts, so start a new session afterinstalling. Claude Code, Codex and the Copilot CLI install from a clone of this repository:@@ -69,8 +71,9 @@ The rules go into this repository's `.claude/settings.local.json`, which the plugit, and it never touches deny rules you wrote. `/tokeneconomizer:toolprune restore` undoes it.Each slash command is one model turn. The same commands are free from a terminal, as-`~/.tokeneconomizer/bin/te <command>` run inside the repository ([Commands](#commands)). For one-session without installing anything: `claude --plugin-dir /path/to/TokenEconomizer/plugin`.+`~/.tokeneconomizer/bin/te --host claude <command>` run inside the repository+([Commands](#commands)). For one session without installing anything:+`claude --plugin-dir /path/to/TokenEconomizer/plugin`.**Update.** `git pull` in the clone, then start a new session (or `/reload-plugins`). Claude Coderuns a plugin added from a local folder from that folder. If `/tokeneconomizer:status` still@@ -93,16 +96,22 @@ codex plugin marketplace add /path/to/TokenEconomizercodex plugin add tokeneconomizer@tokeneconomizer```-**2. Approve its hooks.** Start `codex` in a repository. Codex asks whether to trust the project,-then shows **Hooks need review**: choose **Trust all**. Hooks run from the next session on (the-session in which you approve gets no session-start injection). To approve later: `/hooks`.--**3. Check it.** Ask Codex *"what has TokenEconomizer learned here?"*, or name the skill:-`$tokeneconomizer-status`. Codex has no plugin slash commands; the plugin's commands are Codex-skills: `$tokeneconomizer-status`, `$tokeneconomizer-microskills`, `$tokeneconomizer-toolprune` and-`$tokeneconomizer-config`, each also used when you just ask. From a terminal, inside the-repository: `~/.tokeneconomizer/bin/te --host codex <command>` (the launcher appears after the-first session).+**2. Approve its hooks.** Start `codex` in a repository. Codex asks whether to trust the folder+(**Trust and continue**), then shows **Hooks need review**: choose **Trust all and continue**.+Hooks run from the next session on (the session in which you approve gets no session-start+injection), so quit with `/exit` and start `codex` again. To approve later: `/hooks`.++**3. Check it.** Type `$tokeneconomizer:status`. Codex has no plugin slash commands; the plugin's+commands are Codex skills, named like the slash commands on the other agents (type+`$tokeneconomizer` to pick one): `$tokeneconomizer:status`, `:microskills`, `:toolprune`,+`:config` and `:repos`, each followed by its arguments (`$tokeneconomizer:config set+loopguard=off`). Name the skill: a question in plain words (*"what has TokenEconomizer learned+here?"*) may be answered from the plugin's files without running its command. A command that+changes something (`config set` or `unset`, `toolprune apply` or `restore`, `repos migrate` or+`merge`) writes the plugin's state in `~/.tokeneconomizer`, which Codex's sandbox keeps+read-only, so Codex asks first: choose **Yes, proceed**. From a terminal, inside the repository:+`~/.tokeneconomizer/bin/te --host codex <command>` (the launcher appears after the first+session).**4. Work normally.** See [What to expect](#what-to-expect). Codex's deny list removes thesub-agent (`collaboration`), `goals` and image (`image_media`) packages, each only after it went@@ -114,7 +123,10 @@ effect). The web, asking you questions and the bundled skills are never proposedIn `codex exec`, Codex does not print hook messages, so the plugin's notices are not shownthere; a loop guard redirect still reaches the model. Codex cannot stop a turn from a hook, so-`loopguard=stop` acts as `nudge` on Codex.+`loopguard=stop` acts as `nudge` on Codex. Quitting Codex's interactive mode (`/exit`) keeps the+session open to `codex resume` and sends no session end, so the plugin learns from it at a later+session start, once it has been quiet for ten minutes; `codex exec` sessions are learned from+as they end.**Update.** `git pull` in the clone, then `codex plugin add tokeneconomizer@tokeneconomizer`again to refresh Codex's installed copy (your hook approval is kept).@@ -236,7 +248,7 @@ pi install git:github.com/microsoft/TokenEconomizer`pi install /path/to/TokenEconomizer`.)**2. Check it.** Start a new Pi session and type `/te status`. The commands are `/te status`,-`/te microskills` and `/te config …`; from a terminal, inside the repository,+`/te microskills`, `/te config …` and `/te repos`; from a terminal, inside the repository,`~/.tokeneconomizer/bin/te --host pi <command>`. Tool pruning does not apply: Pi loads fourtools. In print and JSON modes the plugin's notices go to stderr.@@ -278,14 +290,17 @@ from); `pi config` turns it off without removing it. Optional: `rm -rf ~/.tokene| `config set KEY=VALUE … [--global]` | change settings for this repository (or every one); see [Settings](#settings) || `config unset KEY … [--global]` | put a setting back to its default || `repomap` / `repomap refresh` | the cached repository map / make it now (see [Repository map](#repository-map)) |-| `doctor` | check Python, the state directory, the agents found and the error log |+| `repos` | every repository it keeps state for: how it was identified, its sessions per agent, the checkouts seen |+| `repos migrate` | file state an earlier version recorded under the repository it belongs to (runs by itself, once, after an upgrade) |+| `repos merge KEY [INTO]` | merge one repository's state into another's (default: this one), for state whose checkouts are gone |+| `doctor` | check Python, the state directory, the agents found, how this directory was identified, and the error log |How to run them:| Agent | Inside the agent | From a terminal, in the repository ||---|---|---|-| Claude Code | `/tokeneconomizer:<command>` | `~/.tokeneconomizer/bin/te <command>` |-| Codex | ask, or `$tokeneconomizer-status` (`-microskills`, `-toolprune`, `-config`) | `~/.tokeneconomizer/bin/te --host codex <command>` |+| Claude Code | `/tokeneconomizer:<command>` | `~/.tokeneconomizer/bin/te --host claude <command>` |+| Codex | `$tokeneconomizer:<command>` (`status`, `microskills`, `toolprune`, `config`, `repos`) | `~/.tokeneconomizer/bin/te --host codex <command>` || Copilot CLI | `/tokeneconomizer:<command>` (interactive mode) | `~/.tokeneconomizer/bin/te --host copilot <command>` || Pi | `/te <command>` | `~/.tokeneconomizer/bin/te --host pi <command>` |@@ -296,8 +311,17 @@ agent that last worked in the repository.## SettingsEach of the three mechanisms can be turned on or off on its own, and each has numbers you can-set by hand. Settings apply to the current repository, or to every repository with `--global`.-The examples use Claude Code's form; on the other agents run the same `config` command their way.+set by hand. Settings apply to the current repository, or to every repository with `--global`,+and are shared by every agent working in it. The examples use Claude Code's form; the same+`config` command on each agent is:++| Agent | Set one value in this repository |+|---|---|+| Claude Code | `/tokeneconomizer:config set loopguard=off` |+| Codex | `$tokeneconomizer:config set loopguard=off` |+| Copilot CLI | `/tokeneconomizer:config set loopguard=off` (interactive mode) |+| Pi | `/te config set loopguard=off` |+| any agent, from a terminal | `~/.tokeneconomizer/bin/te config set loopguard=off` |**Turn a mechanism on or off:**diff --git a/plugin/codex-skills/tokeneconomizer-config/SKILL.md b/plugin/codex-skills/config/SKILL.mdsimilarity index 73%rename from plugin/codex-skills/tokeneconomizer-config/SKILL.mdrename to plugin/codex-skills/config/SKILL.mdindex 8f837d4..0ef39c5 100644--- a/plugin/codex-skills/tokeneconomizer-config/SKILL.md+++ b/plugin/codex-skills/config/SKILL.md@@ -1,10 +1,10 @@----name: "tokeneconomizer-config"+name: "config"description: >Show or change TokenEconomizer's settings: turn micro-skills, tool pruning or the loop guard on or off, or tune them, for this repository or (with --global) every repository. Use when the user asks to configure, enable or disable TokenEconomizer or one of its mechanisms.----# tokeneconomizer-config+# TokenEconomizer: configRun this command in the repository's root directory:@@ -14,6 +14,8 @@ Run this command in the repository's root directory:Use `show` as ARGS unless the user asked to change a setting; then `set KEY=VALUE ...` or `unset KEY ...`, adding `--global` only if they asked for every repository. Show the output verbatim in a code block; if a setting was rejected, say why in one sentence.+Changing a setting (`set`, `unset`) writes TokenEconomizer's own state under `~/.tokeneconomizer`, outside the workspace, which the sandbox keeps read-only: run that command with `sandbox_permissions` set to `"require_escalated"` and a one-line `justification`, so that Codex asks the user to approve it. `show` reads only and needs no approval.+The command reads and writes only TokenEconomizer's own state (under `~/.tokeneconomizer`)and, for `toolprune apply` or `restore`, the project's `.codex/config.toml`; it makes no modelcall. If it reports that the launcher does not exist, the plugin has not run in a session yet:diff --git a/plugin/codex-skills/tokeneconomizer-microskills/SKILL.md b/plugin/codex-skills/microskills/SKILL.mdsimilarity index 92%rename from plugin/codex-skills/tokeneconomizer-microskills/SKILL.mdrename to plugin/codex-skills/microskills/SKILL.mdindex 29790e5..ce31ea9 100644--- a/plugin/codex-skills/tokeneconomizer-microskills/SKILL.md+++ b/plugin/codex-skills/microskills/SKILL.md@@ -1,10 +1,10 @@----name: "tokeneconomizer-microskills"+name: "microskills"description: >Show the repository facts (micro-skills) TokenEconomizer learned and injects at the start of each session here, and the ones still forming. Use when the user asks what TokenEconomizer learned or injects, or about its facts or micro-skills.----# tokeneconomizer-microskills+# TokenEconomizer: microskillsRun this command in the repository's root directory:diff --git a/plugin/codex-skills/repos/SKILL.md b/plugin/codex-skills/repos/SKILL.mdnew file mode 100644index 0000000..b7cc1ef--- /dev/null+++ b/plugin/codex-skills/repos/SKILL.md@@ -0,0 +1,22 @@+---+name: "repos"+description: >+ List every repository TokenEconomizer keeps state for (how each was identified, its agents and sessions, the checkouts seen), or merge one repository's state into another. Use when the user asks which repositories TokenEconomizer tracks, why state looks split or missing, or asks to merge or migrate it.+---++# TokenEconomizer: repos++Run this command in the repository's root directory:++```+"${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te" --host codex --cwd "$(pwd)" repos ARGS+```++Use `list` as ARGS unless the user asked to `migrate`, or to `merge KEY [INTO]` (keys as the list shows them; INTO defaults to this repository). Never run `migrate` or `merge` unless the user asked for it. Show the output verbatim in a code block.++`migrate` and `merge` move state between repositories; that writes TokenEconomizer's own state under `~/.tokeneconomizer`, outside the workspace, which the sandbox keeps read-only: run that command with `sandbox_permissions` set to `"require_escalated"` and a one-line `justification`, so that Codex asks the user to approve it. `list` reads only and needs no approval.++The command reads and writes only TokenEconomizer's own state (under `~/.tokeneconomizer`);+it makes no model call, and a merge keeps the old state directory under+`~/.tokeneconomizer/merged/`. If it reports that the launcher does not exist, the plugin has+not run in a session yet: ask the user to start a new Codex session in this repository first.diff --git a/plugin/codex-skills/tokeneconomizer-status/SKILL.md b/plugin/codex-skills/status/SKILL.mdsimilarity index 94%rename from plugin/codex-skills/tokeneconomizer-status/SKILL.mdrename to plugin/codex-skills/status/SKILL.mdindex 0fe38db..977aa7a 100644--- a/plugin/codex-skills/tokeneconomizer-status/SKILL.md+++ b/plugin/codex-skills/status/SKILL.md@@ -1,10 +1,10 @@----name: "tokeneconomizer-status"+name: "status"description: >Show what TokenEconomizer has learned for this repository, what it has done, and what this repository's sessions cost. Use when the user asks about TokenEconomizer, its status, its savings or overhead, or what it learned here.----# tokeneconomizer-status+# TokenEconomizer: statusRun this command in the repository's root directory:diff --git a/plugin/codex-skills/tokeneconomizer-toolprune/SKILL.md b/plugin/codex-skills/toolprune/SKILL.mdsimilarity index 71%rename from plugin/codex-skills/tokeneconomizer-toolprune/SKILL.mdrename to plugin/codex-skills/toolprune/SKILL.mdindex f5e3925..703ed39 100644--- a/plugin/codex-skills/tokeneconomizer-toolprune/SKILL.md+++ b/plugin/codex-skills/toolprune/SKILL.md@@ -1,10 +1,10 @@----name: "tokeneconomizer-toolprune"+name: "toolprune"description: >Review, apply or undo TokenEconomizer's proposed list of Codex capabilities this repository never uses (written to the project's .codex/config.toml). Use when the user asks about TokenEconomizer's tool pruning or deny list, or asks to apply or restore it.----# tokeneconomizer-toolprune+# TokenEconomizer: toolpruneRun this command in the repository's root directory:@@ -14,6 +14,8 @@ Run this command in the repository's root directory:Use `show` as ARGS unless the user asked to `apply`, `restore` or `measure` (optionally naming capabilities). Never run `apply` or `restore` unless the user asked for it. Show the output verbatim in a code block; if it is a proposal, end with one line saying how to apply it and that it takes effect from the next session.+`apply` and `restore` edit the project's `.codex/config.toml` and record the change in TokenEconomizer's own state under `~/.tokeneconomizer`, outside the workspace, which the sandbox keeps read-only: run that command with `sandbox_permissions` set to `"require_escalated"` and a one-line `justification`, so that Codex asks the user to approve it. `show` and `measure` need no approval.+The command reads and writes only TokenEconomizer's own state (under `~/.tokeneconomizer`)and, for `toolprune apply` or `restore`, the project's `.codex/config.toml`; it makes no modelcall. If it reports that the launcher does not exist, the plugin has not run in a session yet:diff --git a/plugin/pi/tokeneconomizer.ts b/plugin/pi/tokeneconomizer.tsindex ba03cae..dfc3aa7 100644--- a/plugin/pi/tokeneconomizer.ts+++ b/plugin/pi/tokeneconomizer.ts@@ -40,13 +40,19 @@ const SECTION = "tokeneconomizer";const truthy = (v: string | undefined) => ["1", "true", "yes", "on"].includes((v ?? "").trim().toLowerCase());/** Run one of the plugin's launchers with `input` on stdin; resolve to its stdout. */-function run(script: string, args: string[], input: string, mode: string): Promise<string> {+function run(+ script: string,+ args: string[],+ input: string,+ mode: string,+ extra: Record<string, string> = {},+): Promise<string> {return new Promise((resolve) => {let out = "";let child;try {child = spawn(join(SCRIPTS, script), args, {- env: { ...process.env, TE_PI_MODE: mode },+ env: { ...process.env, TE_PI_MODE: mode, ...extra },stdio: ["pipe", "pipe", "ignore"],});} catch {@@ -178,10 +184,14 @@ export default function tokeneconomizer(pi: ExtensionAPI) {});pi.registerCommand("te", {- description: "TokenEconomizer: status | microskills | config (what it learned here, what it did)",+ description: "TokenEconomizer: status | microskills | config | repos (what it learned here, what it did)",handler: async (args, ctx) => {const argv = (args || "status").trim().split(/\s+/).filter(Boolean);- const out = await run("te", ["--host", "pi", "--cwd", ctx.cwd, ...argv], "", ctx.mode);+ // The session id lets `te status` say when this session is recorded under the repository+ // it started in rather than the one `ctx.cwd` is in now.+ const out = await run("te", ["--host", "pi", "--cwd", ctx.cwd, ...argv], "", ctx.mode, {+ TE_SESSION_ID: ctx.sessionManager.getSessionId(),+ });notify(ctx, out.trim() || "te: no output (is Python 3.10+ on PATH?)");},});diff --git a/plugin/slash-commands/config.md b/plugin/slash-commands/config.mdindex b82bc54..913ede6 100644--- a/plugin/slash-commands/config.md+++ b/plugin/slash-commands/config.md@@ -2,10 +2,11 @@description: Show or change TokenEconomizer's settings - turn each mechanism on or off, or tune itargument-hint: "[show | set KEY=VALUE ... [--global] | unset KEY ... [--global]]"----Run this exact command with the Bash tool (use `show` when no arguments were given: "$ARGUMENTS"), then show me its output verbatim in a code block:+The arguments I typed after the command are: "$ARGUMENTS" (it shows every setting when there are none).+Run this exact command with the Bash tool, then show me its output verbatim in a code block:```te="${CLAUDE_PLUGIN_ROOT}/scripts/te"; [ -x "$te" ] || te="${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te"; "$te" --cwd "$(pwd)" config $ARGUMENTS```-Do not run `set` or `unset` unless those words appear in the arguments above. If a setting was rejected, say why in one sentence.+It changes a setting only when I typed `set` or `unset` in those arguments; never add them yourself. If a setting was rejected, say why in one sentence.diff --git a/plugin/slash-commands/repos.md b/plugin/slash-commands/repos.mdnew file mode 100644index 0000000..e0a4778--- /dev/null+++ b/plugin/slash-commands/repos.md@@ -0,0 +1,12 @@+---+description: List every repository TokenEconomizer keeps state for, or merge one repository's state into another+argument-hint: "[list | migrate | merge KEY [INTO]]"+---+The arguments I typed after the command are: "$ARGUMENTS" (it lists the repositories when there are none).+Run this exact command with the Bash tool, then show me its output verbatim in a code block:++```+te="${CLAUDE_PLUGIN_ROOT}/scripts/te"; [ -x "$te" ] || te="${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te"; "$te" --cwd "$(pwd)" repos $ARGUMENTS+```++It moves state only when I typed `migrate` or `merge` in those arguments; never add them yourself. If the list shows state recorded by an earlier version, say in one sentence that it is sorted out at the next session start, or now with `/tokeneconomizer:repos migrate`.diff --git a/plugin/slash-commands/toolprune.md b/plugin/slash-commands/toolprune.mdindex edfe7e1..436bcd9 100644--- a/plugin/slash-commands/toolprune.md+++ b/plugin/slash-commands/toolprune.md@@ -2,10 +2,11 @@description: Review or apply TokenEconomizer's proposed deny list of tools this repository never usesargument-hint: "[show | apply [TOOL ...] | restore [TOOL ...] | refresh-catalog | measure]"----Run this exact command with the Bash tool (use `show` when no arguments were given: "$ARGUMENTS"), then show me its output verbatim in a code block:+The arguments I typed after the command are: "$ARGUMENTS" (it shows the proposal when there are none).+Run this exact command with the Bash tool, then show me its output verbatim in a code block:```te="${CLAUDE_PLUGIN_ROOT}/scripts/te"; [ -x "$te" ] || te="${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te"; "$te" --cwd "$(pwd)" toolprune $ARGUMENTS```-Do not run `apply` or `restore` unless those words appear in the arguments above. If the output is a proposal, end with one line telling me how to apply it (`/tokeneconomizer:toolprune apply`) and that it takes effect from the next session.+It applies or restores the deny list only when I typed `apply` or `restore` in those arguments; never add them yourself. If the output is a proposal, end with one line telling me how to apply it (`/tokeneconomizer:toolprune apply`) and that it takes effect from the next session.diff --git a/plugin/slash-commands/untool.md b/plugin/slash-commands/untool.mdindex 19dceee..c1c73cd 100644--- a/plugin/slash-commands/untool.md+++ b/plugin/slash-commands/untool.md@@ -2,10 +2,11 @@description: Earlier name of /tokeneconomizer:toolprune - review or apply the proposed deny listargument-hint: "[show | apply [TOOL ...] | restore [TOOL ...] | refresh-catalog | measure]"----Run this exact command with the Bash tool (use `show` when no arguments were given: "$ARGUMENTS"), then show me its output verbatim in a code block:+The arguments I typed after the command are: "$ARGUMENTS" (it shows the proposal when there are none).+Run this exact command with the Bash tool, then show me its output verbatim in a code block:```te="${CLAUDE_PLUGIN_ROOT}/scripts/te"; [ -x "$te" ] || te="${TOKENECONOMIZER_HOME:-$HOME/.tokeneconomizer}/bin/te"; "$te" --cwd "$(pwd)" toolprune $ARGUMENTS```-Do not run `apply` or `restore` unless those words appear in the arguments above. If the output is a proposal, end with one line telling me how to apply it (`/tokeneconomizer:toolprune apply`) and that it takes effect from the next session.+It applies or restores the deny list only when I typed `apply` or `restore` in those arguments; never add them yourself. If the output is a proposal, end with one line telling me how to apply it (`/tokeneconomizer:toolprune apply`) and that it takes effect from the next session.diff --git a/tests/test_live_core.py b/tests/test_live_core.pyindex 7ef4c54..c1d2160 100644--- a/tests/test_live_core.py+++ b/tests/test_live_core.py@@ -19,6 +19,8 @@ from tokeneconomizer.plugin.store import Store# ---- repository identity ---------------------------------------------------------------def _git_repo(root, remote=None):os.makedirs(os.path.join(root, ".git"), exist_ok=True)+ with open(os.path.join(root, ".git", "HEAD"), "w") as fh:+ fh.write("ref: refs/heads/main\n")cfg = "[core]\n\trepositoryformatversion = 0\n"if remote:cfg += f'[remote "origin"]\n\turl = {remote}\n\tfetch = +refs/heads/*:refs/remotes/origin/*\n'diff --git a/tests/test_live_hooks.py b/tests/test_live_hooks.pyindex ff41b0b..874c159 100644--- a/tests/test_live_hooks.py+++ b/tests/test_live_hooks.py@@ -32,6 +32,7 @@ def env(tmp_path):def repo(tmp_path):r = tmp_path / "repo"(r / ".git" / "info").mkdir(parents=True)+ (r / ".git" / "HEAD").write_text("ref: refs/heads/main\n")(r / ".git" / "config").write_text('[remote "origin"]\n\turl = https://github.com/acme/widget.git\n')(r / "pyproject.toml").write_text("[project]\nname='w'\n")diff --git a/tests/test_live_repos.py b/tests/test_live_repos.pynew file mode 100644index 0000000..8cac917--- /dev/null+++ b/tests/test_live_repos.py@@ -0,0 +1,641 @@+"""Which repository a session's state belongs to: what counts as a checkout, one key per+repository, session pins, carrying state over from the keys 0.1.0 used, per-checkout deny lists,+and `te repos`.++Every case here was seen on a real state root (2026-10-19): an empty `~/.git` that filed every+project under the home directory, a clone and a worktree whose folder names split one repository+in three, a session recorded in two places because the agent `cd`-ed, and two sessions folded+twice under two keys.+"""+import io+import json+import os++import pytest++from tokeneconomizer.plugin import cli, denylist, fold, hook, paths, repos+from tokeneconomizer.plugin.store import Store+++def git_repo(root, remote=None):+ os.makedirs(os.path.join(root, ".git", "info"), exist_ok=True)+ with open(os.path.join(root, ".git", "HEAD"), "w") as fh:+ fh.write("ref: refs/heads/main\n")+ cfg = "[core]\n\trepositoryformatversion = 0\n"+ if remote:+ cfg += f'[remote "origin"]\n\turl = {remote}\n'+ with open(os.path.join(root, ".git", "config"), "w") as fh:+ fh.write(cfg)+ return root+++def worktree(main, path, name="feature"):+ wt_git = os.path.join(main, ".git", "worktrees", name)+ os.makedirs(wt_git)+ with open(os.path.join(wt_git, "commondir"), "w") as fh:+ fh.write("../..")+ os.makedirs(path)+ with open(os.path.join(path, ".git"), "w") as fh:+ fh.write(f"gitdir: {wt_git}\n")+ return path+++def env(tmp_path):+ home = tmp_path / "home"+ home.mkdir()+ return {"TOKENECONOMIZER_HOME": str(tmp_path / "te"), "TE_FOLD_SYNC": "1",+ "GIT_CEILING_DIRECTORIES": str(tmp_path), "HOME": str(home),+ "PATH": os.environ.get("PATH", "")}+++def call(env, payload, host):+ """One hook call's final JSON object, with Copilot's notice lines as `progress`."""+ out = io.StringIO()+ hook.main(["--host", host], io.StringIO(json.dumps(payload)), out, env)+ lines = out.getvalue().splitlines()+ res = json.loads(lines[-1])+ if lines[:-1]:+ res["progress"] = [json.loads(ln)["message"] for ln in lines[:-1]]+ return res+++def state(env, key, host="claude"):+ return Store(os.path.join(env["TOKENECONOMIZER_HOME"], "repos", key, host))+++# ---- what counts as a checkout -----------------------------------------------------------------+def test_an_empty_or_dangling_dot_git_is_no_checkout(tmp_path, env):+ empty = tmp_path / "empty"+ (empty / ".git").mkdir(parents=True)+ dangling = tmp_path / "dangling"+ dangling.mkdir()+ (dangling / ".git").write_text(f"gitdir: {tmp_path / 'gone'}\n")+ for d in (empty, dangling):+ assert not paths.is_git_entry(str(d / ".git"))+ r = paths.repo_identity(str(d), env)+ assert r.how == paths.BY_DIR and r.root == str(d)+ assert repos.ignored_git_entries(str(empty))[:1] == [str(empty / ".git")]+++def test_a_versioned_home_directory_keeps_only_its_own_sessions(tmp_path, env):+ """The case that filed every unversioned project under `~`: the walk stops at the home+ directory for anything below it, whether `~/.git` is a real repository or an empty one."""+ home = env["HOME"]+ proj = os.path.join(home, "proposal", "draft")+ os.makedirs(proj)+ for make in (lambda: os.makedirs(os.path.join(home, ".git")), # empty, as seen+ lambda: git_repo(home, "https://github.com/me/dotfiles")):+ make()+ r = paths.repo_identity(proj, env)+ assert r.how == paths.BY_DIR and r.root == proj and r.label == "draft"+ assert paths.repo_identity(home, env).label == "me/dotfiles" # started in ~ itself+ assert "is a git repository" in repos.home_git_note(env)+++def test_clones_and_worktrees_share_one_key_whatever_their_folder_names(tmp_path, env):+ a = git_repo(str(tmp_path / "TE_MSR"), "[email protected]:Microsoft/TokenEconomizer.git")+ b = git_repo(str(tmp_path / "TokenEconomizer"), "https://github.com/microsoft/TokenEconomizer")+ wt = worktree(a, str(tmp_path / "wt" / "agent-af30"))+ keys = {paths.repo_identity(d, env).key for d in (a, b, wt)}+ assert keys == {f"tokeneconomizer-{paths.digest('github.com/microsoft/tokeneconomizer')}"}+ # A repository with no remote is keyed by its main checkout, and so is its worktree.+ local = git_repo(str(tmp_path / "local"))+ lwt = worktree(local, str(tmp_path / "local-wt"))+ rl, rw = paths.repo_identity(local, env), paths.repo_identity(lwt, env)+ assert rl.key == rw.key and rl.label == rw.label == "local" and rw.root == lwt+ assert rl.how == paths.BY_PATH+ # ... unchanged from 0.1.0 for a main checkout, so nothing of it needs carrying over.+ assert rl.key == repos.legacy_key(local, env)+++# ---- one session, one repository, on every agent ------------------------------------------------+def _payloads(host, sid, cwd, n):+ base = {"session_id": sid, "cwd": cwd}+ turn = {"claude": {"prompt_id": f"p{n}"}, "codex": {"turn_id": f"t{n}"},+ "pi": {"prompt_id": f"{sid}:{n}"}, "copilot": {}}[host]+ result = ({"tool_result": {"text_result_for_llm": "ok"}} if host == "copilot"+ else {"tool_response": {"stdout": "ok"}})+ return [dict(base, **turn, hook_event_name="UserPromptSubmit", prompt="go"),+ dict(base, **turn, **result, hook_event_name="PostToolUse", tool_name="Bash",+ tool_input={"command": "ls"}),+ dict(base, **turn, hook_event_name="Stop", stop_hook_active=False)]++[email protected]("host", ["claude", "codex", "copilot", "pi"])+def test_a_session_that_moves_into_another_repository_stays_with_its_own(tmp_path, env, host):+ """Claude Code's hook `cwd` follows the agent's `cd`; every agent's hooks name a cwd. The+ first hook pins the session, and nothing is recorded under the repository it moved to."""+ a = git_repo(str(tmp_path / "a"), "https://github.com/o/a")+ b = git_repo(str(tmp_path / "b"), "https://github.com/o/b")+ ka, kb = paths.repo_identity(a, env).key, paths.repo_identity(b, env).key+ call(env, {"hook_event_name": "SessionStart", "session_id": "s1", "cwd": a,+ "source": "startup"}, host)+ for p in _payloads(host, "s1", b, 1):+ call(env, p, host)+ st = state(env, ka, host)+ rec = st.read(os.path.join("sessions", "s1.json"))+ assert rec["cwd"] == a and len(rec["turns"]) == 1+ assert not os.path.exists(os.path.join(env["TOKENECONOMIZER_HOME"], "repos", kb))+++def test_te_fold_for_a_session_uses_its_pin(tmp_path, env, monkeypatch):+ a = git_repo(str(tmp_path / "a"), "https://github.com/o/a")+ b = git_repo(str(tmp_path / "b"), "https://github.com/o/b")+ for k, v in env.items():+ monkeypatch.setenv(k, v)+ call(env, {"hook_event_name": "SessionStart", "session_id": "s1", "cwd": a}, "claude")+ call(env, {"hook_event_name": "SessionEnd", "session_id": "s1", "cwd": b}, "claude")+ ka = paths.repo_identity(a, env).key+ assert "s1" in (state(env, ka).read("folded.json") or {})+ assert cli.main(["--host", "claude", "--cwd", b, "fold", "--session", "s1"]) == 0+ assert not os.path.exists(os.path.join(env["TOKENECONOMIZER_HOME"], "repos",+ paths.repo_identity(b, env).key, "claude",+ "folded.json"))+++def test_status_says_when_this_session_is_recorded_elsewhere(tmp_path, env, monkeypatch, capsys):+ a = git_repo(str(tmp_path / "a"), "https://github.com/o/a")+ b = git_repo(str(tmp_path / "b"), "https://github.com/o/b")+ for k, v in env.items():+ monkeypatch.setenv(k, v)+ call(env, {"hook_event_name": "SessionStart", "session_id": "s9", "cwd": a}, "claude")+ monkeypatch.setenv("CLAUDE_CODE_SESSION_ID", "s9")+ assert cli.main(["--host", "claude", "--cwd", b, "status"]) == 0+ out = capsys.readouterr().out+ assert "identified by its origin remote (github.com/o/b)" in out+ assert f"this claude session started in {a} and is recorded under o/a" in out+ assert cli.main(["--host", "claude", "--cwd", a, "status"]) == 0+ assert "note " not in capsys.readouterr().out+++# ---- carrying state over from 0.1.0's keys ------------------------------------------------------+def transcript(path, cwd):+ with open(path, "w") as fh:+ fh.write(json.dumps({"type": "user", "cwd": cwd, "message": {"content": "hi"}}) + "\n")+ os.utime(path, (1, 1)) # long quiet: a finished session+ return str(path)+++def legacy_session(st, sid, tp, cwd=None, folded=True, tokens=100.0, folded_at=1.0):+ rec = {"session_id": sid, "host": "claude", "started": folded_at, "transcript": tp,+ "turns": [], "updated": folded_at}+ if cwd:+ rec["cwd"] = cwd+ st.write(os.path.join("sessions", f"{sid}.json"), rec)+ if folded:+ f = st.read("folded.json") or {}+ f[sid] = {"at": folded_at, "transcript": tp}+ st.write("folded.json", f)+ st.append("ledger.jsonl", {"kind": "session", "session_id": sid, "folded_at": folded_at,+ "effective_tokens": tokens})+++def learned(st, label, facts=1):+ st.write("injection.json", {"rendered": "- a fact", "sessions": facts})+ st.write(os.path.join("mechanisms", "envfacts_state", label.replace("/", "__") + ".json"),+ {"repo": label, "facts": {}})+++def test_a_clone_under_another_folder_name_is_carried_over_whole(tmp_path, env):+ clone = git_repo(str(tmp_path / "TE_MSR"), "https://github.com/acme/widget")+ old = repos.legacy_key(clone, env)+ assert old.startswith("te-msr-")+ st = state(env, old)+ legacy_session(st, "s1", transcript(tmp_path / "s1.jsonl", clone))+ learned(st, "acme/widget")+ st.write("envelope.json", {"resolved_turns": [5, 6]})+ root = env["TOKENECONOMIZER_HOME"]+ repo = paths.repo_identity(clone, env)+ repos.adopt(root, repo, env)+ new = state(env, repo.key)+ assert repo.key.startswith("widget-") and not os.path.isdir(os.path.dirname(st.base))+ assert new.read("injection.json")["rendered"] == "- a fact"+ assert new.read("envelope.json")["resolved_turns"] == [5, 6]+ assert "s1" in new.read("folded.json") and len(new.read_lines("ledger.jsonl")) == 1+ assert os.listdir(os.path.join(root, "merged"))[0].startswith(old)+ # Seen once, the checkout is not migrated again.+ assert repos.adopt(root, repo, env) == []+++def test_an_old_remote_carries_its_learned_state_under_the_new_name(tmp_path, env):+ """`aaron-jx-li/tokeneconomizer` moved to `microsoft/tokeneconomizer`: the micro-skill state+ is filed by repository name, so it is renamed with the move."""+ clone = git_repo(str(tmp_path / "tokeneconomizer"), "https://github.com/microsoft/te")+ old = f"tokeneconomizer-{paths.digest('github.com/aaron-jx-li/te')}"+ st = state(env, old)+ legacy_session(st, "s1", transcript(tmp_path / "s1.jsonl", clone))+ learned(st, "aaron-jx-li/te")+ root = env["TOKENECONOMIZER_HOME"]+ assert repos.needs_migration(root)+ repos.run_migration(root, env)+ new = state(env, paths.repo_identity(clone, env).key)+ path = new.path("mechanisms", "envfacts_state", "microsoft__te.json")+ assert json.load(open(path))["repo"] == "microsoft/te"+ assert not repos.needs_migration(root)+++def test_sessions_of_other_directories_leave_the_home_directory(tmp_path, env):+ """The home directory's state keeps the sessions started in ~; one started in a project+ below it moves there, and is folded again so that project learns from it."""+ home = env["HOME"]+ os.makedirs(os.path.join(home, ".git")) # the empty one+ proj = os.path.join(home, "agentcache")+ os.makedirs(proj)+ old = repos.legacy_key(proj, env)+ assert old == repos.legacy_key(home, env) # 0.1.0 filed both under ~+ st = state(env, old)+ legacy_session(st, "mine", transcript(tmp_path / "mine.jsonl", home), cwd=home)+ legacy_session(st, "theirs", transcript(tmp_path / "theirs.jsonl", proj), cwd=proj)+ learned(st, "home")+ root = env["TOKENECONOMIZER_HOME"]+ repos.migrate_all(root, env)+ assert set(st.read("folded.json")) == {"mine"}+ assert [r["session_id"] for r in st.read_lines("ledger.jsonl")] == ["mine"]+ assert st.read("injection.json") # what ~ learned stays+ dst = state(env, paths.repo_identity(proj, env).key)+ assert dst.read(os.path.join("sessions", "theirs.json"))["folded"] is False+ assert "theirs" not in (dst.read("folded.json") or {})+ assert dst.read_lines("ledger.jsonl") == [] # its fold writes the record anew+++def test_a_session_split_over_two_keys_counts_once(tmp_path, env):+ """0.1.0 recorded a session wherever the agent was, and could fold it under two keys; the+ first directory its log names says where it started, and the later fold's cost is kept."""+ home = env["HOME"]+ os.makedirs(os.path.join(home, ".git"))+ elsewhere = os.path.join(home, "bench")+ os.makedirs(elsewhere)+ tp = transcript(tmp_path / "s.jsonl", home)+ a = state(env, repos.legacy_key(home, env))+ b = state(env, "bench-0123456789")+ # The record at home names where a compaction's SessionStart found the agent: not the start.+ legacy_session(a, "s", tp, cwd=elsewhere, tokens=10.0, folded_at=1.0)+ legacy_session(b, "s", tp, cwd=None, tokens=50.0, folded_at=2.0)+ learned(a, "home")+ learned(b, "bench")+ root = env["TOKENECONOMIZER_HOME"]+ repos.migrate_all(root, env)+ assert not os.path.isdir(os.path.dirname(b.base))+ led = a.read_lines("ledger.jsonl")+ assert [(r["session_id"], r["effective_tokens"]) for r in led] == [("s", 50.0)]+ assert set(a.read("folded.json")) == {"s"}+ assert a.read(os.path.join("sessions", "s.json")).get("folded") is not False+++def test_where_a_compaction_found_the_agent_does_not_move_its_session(tmp_path, env):+ home = env["HOME"]+ os.makedirs(os.path.join(home, ".git"))+ later = os.path.join(home, "slides")+ os.makedirs(later)+ st = state(env, repos.legacy_key(home, env))+ legacy_session(st, "s", transcript(tmp_path / "s.jsonl", home), cwd=later)+ repos.migrate_all(env["TOKENECONOMIZER_HOME"], env)+ assert set(st.read("folded.json")) == {"s"}+ assert not os.path.isdir(os.path.dirname(state(env, paths.repo_identity(later, env).key).base))+++def test_a_repositorys_own_state_is_not_merged_away_by_a_visiting_session(tmp_path, env):+ """Seen on the first run against real state: the only session under a repository's key had+ started in ~ and `cd`-ed in. It moves to ~; the repository's state directory stays."""+ home = env["HOME"]+ repo_dir = git_repo(os.path.join(home, "widget"), "https://github.com/acme/widget")+ repo = paths.repo_identity(repo_dir, env)+ st = state(env, repo.key)+ legacy_session(st, "visit", transcript(tmp_path / "v.jsonl", home), cwd=repo_dir)+ learned(st, "acme/widget")+ repos.adopt(env["TOKENECONOMIZER_HOME"], repo, env)+ assert st.read("injection.json") and not os.path.exists(st.path("sessions", "visit.json"))+ at_home = state(env, paths.repo_identity(home, env).key)+ assert at_home.read(os.path.join("sessions", "visit.json"))["folded"] is False+ assert not os.path.isdir(os.path.join(env["TOKENECONOMIZER_HOME"], "merged"))+++def test_a_checkout_only_ever_visited_keeps_its_state_directory(tmp_path, env):+ """Its sessions all started in ~, but a hook fired in it: it is a live repository, so the+ migration moves the sessions out and leaves its state directory where it is."""+ home = env["HOME"]+ repo_dir = git_repo(os.path.join(home, "bench"), "https://github.com/acme/bench")+ key = paths.repo_identity(repo_dir, env).key+ st = state(env, key)+ legacy_session(st, "v", transcript(tmp_path / "v.jsonl", home), cwd=repo_dir)+ learned(st, "acme/bench")+ repos.migrate_all(env["TOKENECONOMIZER_HOME"], env)+ assert st.read("injection.json") and "v" not in (st.read("folded.json") or {})+ assert not os.path.isdir(os.path.join(env["TOKENECONOMIZER_HOME"], "merged"))+++def test_learned_state_moves_into_an_empty_mechanisms_directory(tmp_path, env):+ clone = git_repo(str(tmp_path / "other-name"), "https://github.com/acme/widget")+ old = state(env, repos.legacy_key(clone, env))+ legacy_session(old, "s1", transcript(tmp_path / "s1.jsonl", clone))+ learned(old, "acme/widget")+ repo = paths.repo_identity(clone, env)+ new = state(env, repo.key)+ new.ensure("mechanisms") # what `ctx.mech_dir` leaves behind+ repos.adopt(env["TOKENECONOMIZER_HOME"], repo, env)+ assert os.listdir(new.path("mechanisms")) == ["envfacts_state"]+++def test_a_pinned_session_follows_its_repository_into_a_merge(tmp_path, env):+ root = env["TOKENECONOMIZER_HOME"]+ gone = git_repo(str(tmp_path / "x"), "https://github.com/o/x")+ repo = paths.repo_identity(gone, env)+ repos.pin(root, "claude", "s1", repo, gone)+ state(env, repo.key).write("notices.json", {"a": 1})+ target = git_repo(str(tmp_path / "y"), "https://github.com/o/y")+ assert repos.merge(root, repo.key, paths.repo_identity(target, env)) is not None+ assert repos.pinned(root, "claude", "s1").key == paths.repo_identity(target, env).key+ # A session pinned to that key after the merge is the key's again, written to or not.+ repos.pin(root, "claude", "s2", repo, gone)+ assert repos.pinned(root, "claude", "s2").key == repo.key+++def test_te_repos_lists_merges_and_says_what_it_did(tmp_path, env, monkeypatch, capsys):+ for k, v in env.items():+ monkeypatch.setenv(k, v)+ a = git_repo(str(tmp_path / "a"), "https://github.com/o/a")+ call(env, {"hook_event_name": "SessionStart", "session_id": "s1", "cwd": a}, "claude")+ stray = state(env, "orphan-0000000000")+ legacy_session(stray, "s0", str(tmp_path / "missing.jsonl"), cwd=str(tmp_path / "gone"))+ assert cli.main(["--host", "claude", "--cwd", a, "repos"]) == 0+ out = capsys.readouterr().out+ assert out.splitlines()[0].startswith("o/a [a-") and "<- this directory" in out+ assert "orphan-0000000000" in out and "identified by its origin remote" in out+ assert cli.main(["--host", "claude", "--cwd", a, "repos", "merge", "orphan-0000000000"]) == 0+ out = capsys.readouterr().out+ assert "merged orphan-0000000000 into a-" in out and "claude 1 session(s)" in out+ assert "s0" in state(env, paths.repo_identity(a, env).key).read("folded.json")+ assert cli.main(["--host", "claude", "--cwd", a, "repos", "merge", "nope"]) == 2+++# ---- deny lists are per checkout --------------------------------------------------------------+def test_a_deny_list_applied_in_one_clone_is_still_proposed_in_another(tmp_path):+ st = Store(str(tmp_path / "st"))+ a = git_repo(str(tmp_path / "a"), "https://github.com/o/r")+ b = git_repo(str(tmp_path / "b"), "https://github.com/o/r")+ assert denylist.apply(a, ["CronCreate"], st) == ["CronCreate"]+ assert denylist.applied_for(st, a) == ["CronCreate"] and denylist.applied_for(st, b) == []+ assert denylist.restore(b, st) == [] # nothing of b's to take back+ assert denylist.applied_for(st, a) == ["CronCreate"]+ assert denylist.apply(b, ["CronCreate", "Monitor"], st) == ["CronCreate", "Monitor"]+ assert denylist.applied(st) == ["CronCreate", "Monitor"]+++def test_a_deny_list_record_from_0_1_0_is_still_read(tmp_path):+ st = Store(str(tmp_path / "st"))+ a = git_repo(str(tmp_path / "a"))+ path = denylist.settings_path(a, "claude")+ st.write(denylist.APPLIED, {"tools": ["Monitor"], "path": path, "updated": 1})+ assert denylist.applied_for(st, a) == ["Monitor"]+ os.makedirs(os.path.dirname(path))+ json.dump({"permissions": {"deny": ["Monitor", "Mine"]}}, open(path, "w"))+ assert denylist.restore(a, st) == ["Monitor"]+ assert json.load(open(path)) == {"permissions": {"deny": ["Mine"]}}+ assert denylist.applied(st) == []+++def test_pending_sessions_fold_oldest_first(tmp_path, env):+ from tokeneconomizer.plugin import hosts+ from tokeneconomizer.plugin.context import LiveContext+ a = git_repo(str(tmp_path / "a"), "https://github.com/o/a")+ ctx = LiveContext.build(hosts.ClaudeCode(), a, env)+ for sid, started in (("z", 1.0), ("a", 3.0), ("m", 2.0)):+ ctx.store.write(os.path.join("sessions", f"{sid}.json"),+ {"session_id": sid, "started": started, "ended": started})+ assert fold.pending_sessions(ctx) == ["z", "m", "a"]+++def test_a_session_start_says_once_what_carrying_state_over_moved(tmp_path, env):+ clone = git_repo(str(tmp_path / "other-name"), "https://github.com/acme/widget")+ old = state(env, repos.legacy_key(clone, env))+ legacy_session(old, "s1", transcript(tmp_path / "s1.jsonl", clone))+ start = {"hook_event_name": "SessionStart", "cwd": clone, "source": "startup"}+ out = call(env, dict(start, session_id="a"), "claude")+ assert "now filed by repository (1 session(s) moved, 1 directory(ies) merged" in \+ out["systemMessage"] and "/tokeneconomizer:repos" in out["systemMessage"]+ assert "systemMessage" not in call(env, dict(start, session_id="b"), "claude")+ assert "progress" not in call(env, dict(start, session_id="c"), "copilot")+++# ---- carrying over each agent's state, from its own session logs --------------------------------+# Every agent keeps its own subdirectory under a repository's state, learned from its own log+# format; carrying state over must move each, and read where each agent's log says it started.+from tests.test_live_core import copilot_events # noqa: E402+from tests.test_live_hooks import COPILOT_TRAP, pi_trap_session # noqa: E402++AGENTS = ["claude", "codex", "copilot", "pi"]+FACT = "`python -m pytest …` works."+++def claude_trap(path, cwd, i):+ """The pytest trap as a Claude Code transcript, which names its directory on every entry."""+ calls = [("Edit", {"file_path": f"{cwd}/pkg/mod{i}.py", "old_string": "a", "new_string": "b"},+ "ok", False),+ ("Bash", {"command": "pytest -q tests/test_a.py"}, "bash: pytest: command not found",+ True),+ ("Bash", {"command": "python -m pytest -q tests/test_a.py"}, "1 passed in 0.1s", False)]+ lines = [{"type": "user", "cwd": cwd,+ "message": {"role": "user", "content": f"fix bug {i}"}}]+ for n, (name, inp, result, err) in enumerate(calls):+ lines.append({"type": "assistant", "cwd": cwd, "message": {+ "id": f"msg_{i}_{n}", "model": "claude-haiku-5-5", "role": "assistant",+ "usage": {"input_tokens": 10, "cache_read_input_tokens": 1000,+ "cache_creation_input_tokens": 100, "output_tokens": 50},+ "content": [{"type": "tool_use", "id": f"tu{i}{n}", "name": name, "input": inp}]}})+ lines.append({"type": "user", "cwd": cwd, "message": {"role": "user", "content": [+ {"type": "tool_result", "tool_use_id": f"tu{i}{n}", "content": result,+ "is_error": err}]}})+ with open(path, "w") as fh:+ fh.write("\n".join(json.dumps(x) for x in lines) + "\n")+ return path+++def codex_trap(path, cwd, i):+ """The pytest trap as a Codex rollout: `session_meta` names the directory."""+ items = [{"type": "FileChange", "id": f"f{i}", "status": "completed",+ "changes": [{"path": f"{cwd}/pkg/mod{i}.py", "kind": "update"}]},+ {"type": "CommandExecution", "id": f"a{i}", "command": "pytest -q tests/test_a.py",+ "aggregated_output": "bash: pytest: command not found", "exit_code": 127,+ "status": "completed"},+ {"type": "CommandExecution", "id": f"b{i}",+ "command": "python -m pytest -q tests/test_a.py",+ "aggregated_output": "1 passed in 0.1s", "exit_code": 0, "status": "completed"}]+ recs = [{"type": "session_meta", "payload": {"id": f"thread-{i}", "cwd": cwd,+ "cli_version": "0.163.0"}},+ {"type": "turn_context", "payload": {"turn_id": "t1", "model": "gpt-5.4-mini"}}]+ recs += [{"type": "event_msg", "payload": {"type": "item_completed", "turn_id": "t1",+ "item": it}} for it in items]+ recs.append({"type": "event_msg", "payload": {"type": "token_count", "info": {+ "total_token_usage": {"input_tokens": 3000, "cached_input_tokens": 2000,+ "cache_write_input_tokens": 0, "output_tokens": 90,+ "reasoning_output_tokens": 10}}}})+ with open(path, "w") as fh:+ fh.write("\n".join(json.dumps(r) for r in recs) + "\n")+ return path+++def agent_session(env, host, sid, cwd, i, tmp_path, monkeypatch, end=True):+ """One session on `host`, its log in that agent's own format and place; returns what its+ SessionStart answered."""+ base = {"session_id": sid, "cwd": cwd}+ if host == "copilot": # Copilot's log sits where its session id says+ home = tmp_path / "copilot-home"+ monkeypatch.setenv("COPILOT_HOME", str(home))+ copilot_events(str(home / "session-state" / sid / "events.jsonl"), COPILOT_TRAP,+ cwd=cwd, sid=sid)+ else:+ make = {"claude": claude_trap, "codex": codex_trap, "pi": pi_trap_session}[host]+ base["transcript_path"] = make(str(tmp_path / f"rollout-{host}-{sid}.jsonl"), cwd, i)+ start = call(env, dict(base, hook_event_name="SessionStart", source="startup"), host)+ if end:+ call(env, dict(base, hook_event_name="SessionEnd", reason="other"), host)+ return start+++def injected(out, host):+ return (out.get("additionalContext") if host == "copilot" else+ (out.get("hookSpecificOutput") or {}).get("additionalContext")) or ""+++def as_0_1_0(env, key, old_key):+ """Make a state root look as 0.1.0 left it: `key`'s state under `old_key`, no index, no+ pins, no identity file, and session records that name no directory (only the logs do)."""+ root = env["TOKENECONOMIZER_HOME"]+ os.replace(os.path.join(root, "repos", key), os.path.join(root, "repos", old_key))+ for p in (os.path.join(root, "index.json"), os.path.join(root, "repos", old_key, "repo.json")):+ if os.path.exists(p):+ os.remove(p)+ import shutil+ shutil.rmtree(os.path.join(root, "sessions"), ignore_errors=True)+ for host in AGENTS:+ st = state(env, old_key, host)+ d = st.path("sessions")+ for name in (os.listdir(d) if os.path.isdir(d) else []):+ rec = st.read(os.path.join("sessions", name))+ rec.pop("cwd", None)+ st.write(os.path.join("sessions", name), rec)++[email protected]("host", AGENTS)+def test_each_agents_learned_state_follows_its_repository_out_of_a_folder_named_key(+ tmp_path, env, monkeypatch, host):+ old = git_repo(str(tmp_path / "old-name"), "https://github.com/acme/widget")+ other = git_repo(str(tmp_path / "widget"), "https://github.com/acme/widget")+ key = paths.repo_identity(old, env).key+ for i in range(4):+ agent_session(env, host, f"s{i}", old, i, tmp_path, monkeypatch)+ assert FACT in state(env, key, host).read("injection.json")["rendered"]+ legacy = repos.legacy_key(old, env)+ assert legacy.startswith("old-name-") and legacy != key+ as_0_1_0(env, key, legacy)+ out = agent_session(env, host, "next", other, 9, tmp_path, monkeypatch, end=False)+ assert FACT in injected(out, host) # learned in the other clone+ moved = state(env, key, host)+ assert {f"s{i}" for i in range(4)} <= set(moved.read("folded.json"))+ assert len(moved.read_lines("ledger.jsonl")) == 4+ merged = os.listdir(os.path.join(env["TOKENECONOMIZER_HOME"], "merged"))+ assert [m.split(".")[0] for m in merged] == [legacy]++[email protected]("host", AGENTS)+def test_each_agents_session_from_a_project_leaves_the_home_directory(+ tmp_path, env, monkeypatch, host):+ """The empty `~/.git` filed a project's sessions under ~; each agent's log says where its+ session started, and the session moves there and is folded again."""+ home = env["HOME"]+ proj = os.path.join(home, "proposal")+ os.makedirs(proj)+ agent_session(env, host, "own", home, 1, tmp_path, monkeypatch)+ agent_session(env, host, "theirs", proj, 2, tmp_path, monkeypatch)+ # 0.1.0 put both under one key: the empty ~/.git made ~ the "repository" of both.+ os.makedirs(os.path.join(home, ".git"))+ legacy = repos.legacy_key(proj, env)+ hk, pk = paths.repo_identity(home, env).key, paths.repo_identity(proj, env).key+ assert legacy == hk+ src = state(env, pk, host)+ dst_old = state(env, hk, host)+ for sid in ("theirs",):+ os.makedirs(dst_old.path("sessions"), exist_ok=True)+ os.replace(src.path("sessions", f"{sid}.json"), dst_old.path("sessions", f"{sid}.json"))+ dst_old.write("folded.json", dict(dst_old.read("folded.json"), **src.read("folded.json")))+ for r in src.read_lines("ledger.jsonl"):+ dst_old.append("ledger.jsonl", r)+ first_fold = max(r["folded_at"] for r in src.read_lines("ledger.jsonl"))+ import shutil+ shutil.rmtree(os.path.dirname(src.base))+ as_0_1_0(env, hk, hk)+ repos.run_migration(env["TOKENECONOMIZER_HOME"], env)+ assert set(dst_old.read("folded.json")) == {"own"}+ back = state(env, pk, host)+ assert set(back.read("folded.json")) == {"theirs"} # folded again, where it ran+ (rec,) = back.read_lines("ledger.jsonl")+ assert rec["session_id"] == "theirs" and rec.get("error") is None+ assert rec["effective_tokens"] > 0 and rec["folded_at"] > first_fold+ assert os.path.exists(back.path("mechanisms", "envfacts_state", "proposal.json"))++[email protected]("host", AGENTS)+def test_each_agents_state_follows_a_renamed_remote_under_its_new_name(+ tmp_path, env, monkeypatch, host):+ """A remote that moves (`aaron-jx-li/…` to `microsoft/…`) changes the key and the name the+ mechanisms file their state under; Codex's capability state is filed by name too."""+ repo_dir = git_repo(str(tmp_path / "widget"), "https://github.com/acme/widget")+ for i in range(4):+ agent_session(env, host, f"s{i}", repo_dir, i, tmp_path, monkeypatch)+ old = state(env, paths.repo_identity(repo_dir, env).key, host)+ assert os.path.exists(old.path("mechanisms", "envfacts_state", "acme__widget.json"))+ if host == "codex":+ assert os.path.exists(old.path("mechanisms", "interface_state", "acme__widget",+ "codex_untool.json"))+ git_repo(repo_dir, "https://github.com/acme-renamed/widget")+ out = agent_session(env, host, "next", repo_dir, 9, tmp_path, monkeypatch, end=False)+ assert FACT in injected(out, host)+ new = state(env, paths.repo_identity(repo_dir, env).key, host)+ mech = new.path("mechanisms")+ assert os.listdir(os.path.join(mech, "envfacts_state")) == ["acme-renamed__widget.json"]+ if host == "codex":+ assert os.listdir(os.path.join(mech, "interface_state")) == ["acme-renamed__widget"]+ assert new.read("untool.json")["sessions"] == 4+++# ---- what a sandbox or an agent's own threads must not break ---------------------------------[email protected]("host", AGENTS)+def test_an_end_with_no_start_and_no_log_records_nothing(tmp_path, env, host):+ """Codex 0.163.0 sends SessionEnd for a thread that never ran a prompt; it is no session."""+ repo_dir = git_repo(str(tmp_path / "r"), "https://github.com/o/r")+ call(env, {"hook_event_name": "SessionEnd", "session_id": "ghost", "cwd": repo_dir,+ "reason": "other"}, host)+ st = state(env, paths.repo_identity(repo_dir, env).key, host)+ assert not os.path.exists(st.path("sessions", "ghost.json"))+ assert st.read_lines("ledger.jsonl") == []++[email protected](os.geteuid() == 0, reason="root writes through read-only permissions")+def test_a_change_where_the_state_is_read_only_is_refused_whole(tmp_path, env, monkeypatch,+ capsys):+ """Codex's default sandbox makes ~/.tokeneconomizer read-only. A change must be refused+ before it starts, never half made: a deny list in the repository's settings with no record+ of it, which `restore` would then not know to take back."""+ for k, v in env.items():+ monkeypatch.setenv(k, v)+ repo_dir = git_repo(str(tmp_path / "r"), "https://github.com/o/r")+ call(env, {"hook_event_name": "SessionStart", "session_id": "s", "cwd": repo_dir}, "claude")+ st = state(env, paths.repo_identity(repo_dir, env).key)+ st.write("untool.json", {"proposal": ["CronCreate"], "sessions": 5})+ for d in (st.base, os.path.dirname(st.base)):+ os.chmod(d, 0o500)+ try:+ assert cli.main(["--host", "claude", "--cwd", repo_dir, "toolprune", "apply"]) == 1+ assert cli.main(["--host", "claude", "--cwd", repo_dir, "config", "set",+ "loopguard=off"]) == 1+ finally:+ for d in (st.base, os.path.dirname(st.base)):+ os.chmod(d, 0o700)+ out = capsys.readouterr().out+ assert out.count("not changed: TokenEconomizer cannot write its state") == 2+ assert "Traceback" not in out+ assert not os.path.exists(denylist.settings_path(repo_dir, "claude"))+ assert not os.path.exists(os.path.join(os.path.dirname(st.base), "config.json"))+ # ... and reading still works there+ assert cli.main(["--host", "claude", "--cwd", repo_dir, "toolprune"]) == 0diff --git a/tests/test_plugin_package.py b/tests/test_plugin_package.pyindex d5b20d7..ba8345c 100644--- a/tests/test_plugin_package.py+++ b/tests/test_plugin_package.py@@ -329,7 +329,10 @@ def test_a_codex_install_copy_finds_the_core_in_the_marketplace_it_came_from(tmpdef test_codex_gets_its_commands_as_plugin_skills_and_no_one_else_does():"""Codex has no plugin slash commands; its plugins carry skills. Ours live outside `skills/`,- which Claude Code and Copilot would load beside their slash commands."""+ which Claude Code and Copilot would load beside their slash commands. Codex lists a plugin's+ skills under the plugin's name (0.163.0), so `status` is `$tokeneconomizer:status`, as the+ slash command is `/tokeneconomizer:status`; each description names TokenEconomizer, which is+ what a request in plain words, or a Codex that lists the bare name, matches on."""from tokeneconomizer.plugin import climanifest = _json(PLUGIN, ".codex-plugin", "plugin.json")assert manifest["skills"] == "./codex-skills"@@ -337,13 +340,13 @@ def test_codex_gets_its_commands_as_plugin_skills_and_no_one_else_does():root = os.path.join(PLUGIN, "codex-skills")subcommands = set(cli.build_parser()._subparsers._group_actions[0].choices)names = sorted(os.listdir(root))- assert names == ["tokeneconomizer-config", "tokeneconomizer-microskills",- "tokeneconomizer-status", "tokeneconomizer-toolprune"]+ assert names == ["config", "microskills", "repos", "status", "toolprune"]for name in names:text = open(os.path.join(root, name, "SKILL.md"), encoding="utf-8").read()assert text.startswith(f'---\nname: "{name}"\ndescription: >\n')+ assert "TokenEconomizer" in text.split("\n")[3]cmd = re.search(r'bin/te" --host codex --cwd "\$\(pwd\)" (\w+)', text)- assert cmd and cmd.group(1) in subcommands and cmd.group(1) == name.split("-", 1)[1]+ assert cmd and cmd.group(1) in subcommands and cmd.group(1) == namedef test_the_commands_keep_their_earlier_names(tmp_path, monkeypatch, capsys):diff --git a/tokeneconomizer/plugin/cli.py b/tokeneconomizer/plugin/cli.pyindex cff09ba..c699aaf 100644--- a/tokeneconomizer/plugin/cli.py+++ b/tokeneconomizer/plugin/cli.py@@ -16,6 +16,12 @@te config unset KEY ... back to the next source down (the global file, then default)te repomap [show | refresh] the repository map (`repomap=on`): what is cached, ormake it now+ te repos every repository with state here: how it was identified,+ its agents and sessions, the checkouts seen+ te repos migrate send state recorded under earlier keys where it belongs+ now (runs by itself, once, after an upgrade)+ te repos merge KEY [INTO] merge the state directory KEY into INTO (default: this+ repository's), for state whose checkouts are gonete doctor check the installationte --host copilot probe real Copilot sessions in a throwaway repository: does alearned fact change what the model does, and what does the@@ -31,25 +37,79 @@ import globimport jsonimport osimport sys+import timefrom .. import loopguard-from . import accounting, denylist, fold, hosts, repomap, toolcheck+from . import accounting, denylist, fold, hosts, paths, repomap, repos, toolcheckfrom .config import unset_config, write_configfrom .context import LiveContextfrom .paths import state_root-def _ctx(args, env=None):+def _ctx(args, env=None, session_id=None):host = hosts.HOSTS[args.host]()- return LiveContext.build(host, args.cwd, env)+ return LiveContext.build(host, args.cwd, env, session_id=session_id)+++def _unwritable(path):+ """Why the plugin cannot write its state at `path`, or None when it can. A command that+ changes something checks first: a sandboxed agent (Codex's default sandbox makes everything+ outside the workspace read-only) must not get half a change -- a deny list written to the+ repository's settings, and no record that the plugin added it, which `restore` needs."""+ probe = os.path.join(path, f".write-test-{os.getpid()}")+ try:+ os.makedirs(path, exist_ok=True)+ open(probe, "w").close()+ os.remove(probe)+ return None+ except OSError as e:+ return e.strerror or str(e)+++def _refuse_unwritable(path):+ """Print why a change cannot be made here, and return the exit code; 0 when it can."""+ why = _unwritable(path)+ if why is None:+ return 0+ print(f"not changed: TokenEconomizer cannot write its state in {path} ({why}). Inside a "+ f"sandboxed agent, run this command with permission to write outside the workspace "+ f"(Codex asks you to approve it), or run it from a terminal as "+ f"`~/.tokeneconomizer/bin/te {' '.join(sys.argv[1:]) or '...'}`.")+ return 1+++def _session_ctx(args, session_id):+ """The context of a recorded session: the repository it is pinned to, when that repository+ holds its record (a fold handed off at SessionEnd), else the one `--cwd` names. Only a+ session's own hooks pin it; this never does."""+ ctx = _ctx(args)+ if session_id and repos.pinned(ctx.root, ctx.host.name, session_id) is not None:+ pinned = _ctx(args, session_id=session_id)+ if os.path.exists(pinned.store.path("sessions", f"{session_id}.json")):+ return pinned+ return ctx+++def _session_note(ctx, env=None):+ """A line when this command runs inside an agent session recorded under another repository+ (the one it started in), else None."""+ env = os.environ if env is None else env+ sid = ctx.host.env_session_id(env)+ pin = repos.pinned(ctx.root, ctx.host.name, sid) if sid else None+ if pin is None or pin.key == ctx.repo.key:+ return None+ return (f"this {ctx.host.name} session started in {pin.root} and is recorded under "+ f"{pin.label} (`te --cwd {pin.root} status`)")# ---- status / microskills ------------------------------------------------------------------def cmd_status(args):ctx = _ctx(args)cfg = ctx.config- out = {"repo": ctx.repo.label, "repo_root": ctx.repo.root, "host": ctx.host.name,- "state": ctx.store.base, "config": cfg.as_dict(), "warnings": cfg.warnings}+ out = {"repo": ctx.repo.label, "repo_root": ctx.repo.root, "repo_key": ctx.repo.key,+ "identified_by": ctx.repo.how, "host": ctx.host.name,+ "state": ctx.store.base, "config": cfg.as_dict(), "warnings": cfg.warnings,+ "session_note": _session_note(ctx)}inj = ctx.store.read("injection.json") or {}unt = ctx.store.read("untool.json") or {}env_tracker = loopguard.load_envelope(ctx.store, cfg.loopguard_aggr,@@ -63,7 +123,8 @@ def cmd_status(args):"toolprune": {"mode": cfg.toolprune, "sessions": unt.get("sessions", 0),"catalog_source": unt.get("catalog_source"),"proposal": unt.get("proposal", []),- "applied": denylist.applied(ctx.store)},+ "applied": denylist.applied_for(ctx.store, ctx.repo.root,+ ctx.host.name)},"loopguard": {"mode": cfg.loopguard, "envelope": env_tracker.envelope,"ended_green_turns": len(env_tracker.resolved_turns)},"ledger": ledger})@@ -71,6 +132,7 @@ def cmd_status(args):print(json.dumps(out, indent=2, default=str))return 0print(f"TokenEconomizer -- {out['repo']} ({ctx.host.name})")+ print(f" repository {ctx.repo.root}, {repos.describe(ctx.repo)}")print(f" state {out['state']}")print(f" config microskills={cfg.microskills_effective} toolprune={cfg.toolprune} "f"loopguard={cfg.loopguard} repomap={cfg.repomap} mode={cfg.mode} paid={cfg.paid} "@@ -83,6 +145,8 @@ def cmd_status(args):f"none yet ({why})"))for w in cfg.warnings:print(f" warning {w}")+ if out["session_note"]:+ print(f" note {out['session_note']}")print(f" sessions {ledger['sessions']} folded, "f"{accounting.fmt_tokens(ledger['effective_tokens'])} effective tokens, plugin "f"overhead {accounting.fmt_tokens(ledger['overhead_tokens'])} "@@ -127,8 +191,8 @@ def _toolprune_show(ctx, unt):f"{unt.get('catalog_source') or 'none yet'}")print(f"applied ({denylist.unit(host, plural=True)} this plugin added to "f"{denylist.settings_path(ctx.repo.root, host)}): "- f"{', '.join(denylist.applied(ctx.store)) or '-'}")- print(f"proposed: {', '.join(unt.get('proposal', [])) or '-'}")+ f"{', '.join(denylist.applied_for(ctx.store, ctx.repo.root, host)) or '-'}")+ print(f"proposed: {', '.join(_proposal(ctx, unt)) or '-'}")if host == "codex":caps = unt.get("capabilities") or {}if caps:@@ -167,6 +231,13 @@ def _toolprune_show(ctx, unt):return 0+def _proposal(ctx, unt):+ """The proposal, less what this checkout already applied: the clones of one repository share+ its evidence, and one of them may have applied the list before another."""+ mine = set(denylist.applied_for(ctx.store, ctx.repo.root, ctx.host.name))+ return [t for t in unt.get("proposal", []) if t not in mine]++def cmd_toolprune(args):ctx = _ctx(args)host = ctx.host.name@@ -177,8 +248,10 @@ def cmd_toolprune(args):action = args.actionif action == "show":return _toolprune_show(ctx, unt)+ if action in ("apply", "restore") and _refuse_unwritable(ctx.store.base):+ return 1if action == "apply":- tools = args.tools or unt.get("proposal", [])+ tools = args.tools or _proposal(ctx, unt)if not tools:print("nothing to apply")return 0@@ -201,7 +274,8 @@ def cmd_toolprune(args):print("warning: Copilot reads a repository's .github/copilot settings only in a ""trusted folder, and this one is not. Trust it (Copilot asks when you ""start it here), or the change does nothing.")- left = toolcheck.verify_copilot(ctx.repo.root, denylist.applied(ctx.store))+ left = toolcheck.verify_copilot(ctx.repo.root,+ denylist.applied_for(ctx.store, ctx.repo.root, host))if left is not None:print("checked with a local capture: " + ", ".join(f"{k} {'removed' if not v else f'still loaded ({v} tools)'}"@@ -211,7 +285,8 @@ def cmd_toolprune(args):print("warning: this project is not trusted in Codex, which ignores a ""project's .codex/config.toml until it is. Trust it (Codex asks when ""you start it here), or the change does nothing.")- state = toolcheck.verify_codex(ctx.repo.root, denylist.applied(ctx.store))+ state = toolcheck.verify_codex(ctx.repo.root,+ denylist.applied_for(ctx.store, ctx.repo.root, host))if state:print("codex features list: " + ", ".join(f"{k}={'on' if v else 'off'}" for k, v in sorted(state.items())))@@ -233,7 +308,8 @@ def cmd_toolprune(args):print(f"{len(tools)} tools recorded in {path}:\n " + ", ".join(tools))return 0if action == "measure":- tools = args.tools or unt.get("proposal", []) or denylist.applied(ctx.store)+ tools = args.tools or _proposal(ctx, unt) or denylist.applied_for(+ ctx.store, ctx.repo.root, host)if not tools:print("no proposal to measure")return 1@@ -313,6 +389,8 @@ def cmd_config(args):return 0path = (os.path.join(ctx.root, "config.json") if args.globallyelse os.path.join(os.path.dirname(ctx.store.base), "config.json"))+ if _refuse_unwritable(os.path.dirname(path)):+ return 1if args.action == "unset":try:cur = unset_config(path, [k.strip() for k in args.pairs])@@ -347,7 +425,8 @@ def cmd_config(args):def cmd_fold(args):- ctx = _ctx(args)+ # A session is folded into the repository it is pinned to, wherever `--cwd` points.+ ctx = _session_ctx(args, (args.session or [None])[0])sids = args.session or fold.pending_sessions(ctx)for sid in sids:rec = fold.fold_session(ctx, sid)@@ -359,7 +438,90 @@ def cmd_fold(args):def cmd_judge(args):"""The detached half of the paid stuck judge (see plugin/judge.py); not for people."""from . import judge- judge.run_job(_ctx(args), args.session, args.job)+ judge.run_job(_session_ctx(args, args.session), args.session, args.job)+ return 0+++# ---- repos ----------------------------------------------------------------------------------+def _when(ts):+ return time.strftime("%Y-%m-%d %H:%M", time.localtime(ts)) if ts else "-"+++def _print_moves(done):+ """One line per move a migration made; returns how many there were."""+ n = 0+ for r in done or ():+ for m in r.get("moves") or ():+ n += 1+ what = "all of its state" if r.get("into") == m["into"] else f"{m['moved']} session(s)"+ print(f" {r['key']} -> {m['into']} ({m['host']}): {what}"+ + (f", {m['refold']} to be folded there again" if m.get("refold") else ""))+ return n+++def cmd_repos(args):+ root = state_root()+ if args.action in ("migrate", "merge") and _refuse_unwritable(root):+ return 1+ if args.action == "migrate":+ done = repos.run_migration(root)+ if done is None:+ print("another migration holds the state root; try again in a minute")+ return 1+ if not args.quiet:+ if not _print_moves(done):+ print("nothing to move: every session is filed under the repository it ran in")+ return 0+ if args.action == "merge":+ if not args.keys or len(args.keys) > 2:+ print("usage: te repos merge KEY [INTO] (keys as `te repos` lists them)")+ return 2+ src = args.keys[0]+ if not os.path.isdir(os.path.join(repos.repos_dir(root), src)):+ print(f"no state directory {src!r} in {repos.repos_dir(root)}")+ return 2+ into = args.keys[1] if len(args.keys) > 1 else _ctx(args).repo+ into_key = into if isinstance(into, str) else into.key+ if into_key == src:+ print(f"{src} is this repository's own state; name the one to merge into it")+ return 2+ res = repos.merge(root, src, into)+ if res is None:+ print("the state root or one of the two directories is busy; try again in a minute")+ return 1+ print(f"merged {src} into {into_key}: " + (", ".join(+ f"{h} {c['moved']} session(s)" + (f" ({c['refold']} to be folded again)"+ if c["refold"] else "")+ for h, c in sorted(res.items())) or "no sessions"))+ print(f"the old directory is kept under {os.path.join(root, 'merged')}")+ if not isinstance(into, str):+ repos.refold_moved([{"moves": [dict(c, host=h, cwd=into.root)+ for h, c in res.items()]}])+ return 0+ current = _ctx(args).repo+ rows, merged = repos.listing(root, current=current)+ if args.json:+ print(json.dumps({"repos": rows, "merged": merged}, indent=2, default=str))+ return 0+ if not rows:+ print(f"no state yet in {repos.repos_dir(root)}")+ for row in rows:+ print(f"{row['label']} [{row['key']}]" + (" <- this directory" if row["current"]+ else ""))+ print(" identified " + (repos.how_words(row["how"], row["remote"]) if row["how"]+ else "recorded by an earlier version"))+ print(" sessions " + (", ".join(f"{h} {n}" for h, n in row["agents"].items())+ or "none") + f"; last {_when(row['last'])}")+ if row["checkouts"]:+ print(" checkouts " + ", ".join(row["checkouts"]))+ elif row["cwds"]:+ print(" ran in " + ", ".join(row["cwds"][:3])+ + (f" (+{len(row['cwds']) - 3})" if len(row["cwds"]) > 3 else ""))+ for n in row["notes"]:+ print(f" note {n}")+ if merged:+ print(f"\n{merged} earlier state director{'y' if merged == 1 else 'ies'} merged into "+ f"the above, kept under {os.path.join(root, 'merged')}")return 0@@ -423,6 +585,18 @@ def cmd_doctor(args):mine = [p for p in pkgs if "tokeneconomizer" in json.dumps(p).lower()]print(f"pi package {'installed: ' + str(mine[0]) if mine else 'not in ' + settings}")ctx = _ctx(args)+ print(f"repository {ctx.repo.root}: {repos.describe(ctx.repo)}; state {ctx.repo.key}")+ home_git = os.path.join(paths.home_dir(), ".git")+ for path in repos.ignored_git_entries(args.cwd):+ if os.path.realpath(path) != home_git: # the home line below says it+ print(f"repository ignored {path}: not a git repository (no HEAD, or a dangling "+ f"gitdir)")+ note = repos.home_git_note()+ if note:+ print(f"home {note}")+ if repos.needs_migration(root):+ print("state recorded by an earlier version and not yet migrated: `te repos "+ "migrate` (runs by itself at the next session start)")py = repomap.find_python(ctx)print(f"repomap {ctx.config.repomap}; " + (f"aider found ({py})" if py else"no Python with aider found (pip install aider-chat, or set repomap_python)"))@@ -478,6 +652,12 @@ def build_parser():p.add_argument("--job", required=True)p.set_defaults(fn=cmd_judge)add("doctor").set_defaults(fn=cmd_doctor)+ p = add("repos")+ p.add_argument("action", nargs="?", default="list", choices=("list", "migrate", "merge"))+ p.add_argument("keys", nargs="*")+ p.add_argument("--json", action="store_true")+ p.add_argument("--quiet", action="store_true")+ p.set_defaults(fn=cmd_repos)p = add("repomap")p.add_argument("action", nargs="?", default="show", choices=("show", "refresh"))p.set_defaults(fn=cmd_repomap)diff --git a/tokeneconomizer/plugin/context.py b/tokeneconomizer/plugin/context.pyindex 7bb96ad..a75c2d7 100644--- a/tokeneconomizer/plugin/context.py+++ b/tokeneconomizer/plugin/context.py@@ -4,6 +4,7 @@ import subprocessimport sysfrom dataclasses import dataclass+from . import reposfrom .config import LiveConfig, load_configfrom .paths import RepoId, repo_identity, repo_state_dir, state_rootfrom .store import Store@@ -17,6 +18,7 @@ class LiveContext:store: Store # this host's state for this repositoryconfig: LiveConfigenv: dict+ unsettled: tuple = None # (cwd, session id) until `settle` has run@propertydef mech_dir(self):@@ -32,14 +34,36 @@ class LiveContext:return self.host.headless(self.env)@classmethod- def build(cls, host, cwd, env=None):+ def build(cls, host, cwd, env=None, session_id=None, settle=True):+ """The context for `cwd`; with `session_id`, for the repository that session is pinned+ to, wherever the agent has moved since. With `settle` (see there) it is ready to use;+ a hook settles only once it knows it will act, so a call it ignores writes nothing."""env = dict(os.environ if env is None else env)- repo = repo_identity(cwd, env)root = state_root(env)+ repo = repos.pinned(root, host.name, session_id) if session_id else None+ unsettled = None+ if repo is None:+ repo = repo_identity(cwd, env)+ unsettled = (cwd, session_id)base = repo_state_dir(repo, host.name, env)- store = Store(base)- config = load_config(root, repo_dir=os.path.dirname(base), env=env)- return cls(host=host, repo=repo, root=root, store=store, config=config, env=env)+ ctx = cls(host=host, repo=repo, root=root, store=Store(base),+ config=load_config(root, repo_dir=os.path.dirname(base), env=env), env=env,+ unsettled=unsettled)+ if settle:+ ctx.settle()+ return ctx++ def settle(self):+ """Carry over what this checkout's earlier keys hold, and pin the session to this+ repository (`repos.settle`); once, and a no-op for a session already pinned."""+ if self.unsettled is None:+ return+ cwd, sid = self.unsettled+ self.unsettled = None+ if repos.settle(self.root, self.host.name, self.repo, cwd, self.env, session_id=sid):+ # A merge may have brought this repository its settings file.+ self.config = load_config(self.root, repo_dir=os.path.dirname(self.store.base),+ env=self.env)def spawn(self, argv, log_name):"""Run `te <argv>` for this host and repository in a detached process, its outputdiff --git a/tokeneconomizer/plugin/controller.py b/tokeneconomizer/plugin/controller.pyindex 405307a..e9447e3 100644--- a/tokeneconomizer/plugin/controller.py+++ b/tokeneconomizer/plugin/controller.py@@ -23,7 +23,7 @@ import osimport timefrom .. import loopguard-from . import denylist, fold, repomap+from . import denylist, fold, repomap, reposfrom .hosts import merge_outputsfrom .paths import ensure_launcher@@ -46,9 +46,11 @@ class LiveController:def _session(self):s = self.store.read(self._sess_name())if not isinstance(s, dict):+ # Where the session started (its first hook's directory): what `repos` resolves+ # to tell which repository the session belongs to, when its log does not say.s = {"session_id": self.sid, "host": self.host.name, "started": time.time(),- "turns": [], "nudges": 0, "aborts": 0, "judge_tokens": 0.0,- "writer_tokens": 0.0}+ "cwd": self.host.cwd(self.p, self.ctx.env), "turns": [], "nudges": 0,+ "aborts": 0, "judge_tokens": 0.0, "writer_tokens": 0.0}return sdef _save(self, s):@@ -75,6 +77,8 @@ class LiveController:# leave an "unknown" session behind.if not self.cfg.enabled or not self.host.session_id(self.p):return {}+ self.ctx.settle()+ self.cfg = self.ctx.configevent = self.p.get("hook_event_name") or ""# PostToolUseFailure: Copilot reports a failed tool there, not in PostToolUse.handler = {"SessionStart": self.session_start, "UserPromptSubmit": self.user_prompt,@@ -91,7 +95,7 @@ class LiveController:passs = self._session()s["source"] = source- s["cwd"] = self.host.cwd(self.p, self.ctx.env)+ s.setdefault("cwd", self.host.cwd(self.p, self.ctx.env))outputs = []seen = self.store.read("notices.json") or {}@@ -118,7 +122,10 @@ class LiveController:if (self.cfg.toolprune == "propose" and denylist.supports(self.host.name)and not self.cfg.shadow):- prop = (self.store.read("untool.json") or {}).get("proposal") or []+ # What this checkout already applied is no news here (another clone may not have).+ mine = set(denylist.applied_for(self.store, self.ctx.repo.root, self.host.name))+ prop = [t for t in (self.store.read("untool.json") or {}).get("proposal") or []+ if t not in mine]key = ",".join(prop)if prop and seen.get("untool") != key:outputs.append(self.host.notice(@@ -128,6 +135,10 @@ class LiveController:f"`{self._cmd('toolprune')}`; nothing changes until you apply it."))seen["untool"] = key+ note = repos.migration_notice(self.ctx.root, self._cmd("repos"))+ if note and not self.cfg.shadow:+ outputs.append(self.host.notice(note))+if self.cfg.repomap != "off":if repomap.stale(self.ctx):repomap.spawn_refresh(self.ctx)@@ -140,6 +151,9 @@ class LiveController:if outputs:self.store.write("notices.json", seen)self._save(s)+ repos.note_repo(self.ctx.root, self.ctx.repo)+ repos.prune_pins(self.ctx.root, self.host.name)+ repos.start_migration(self.ctx)fold.spawn_fold(self.ctx, fold.pending_sessions(self.ctx, exclude=(self.sid,)))return merge_outputs(*outputs)@@ -268,6 +282,13 @@ class LiveController:# ---- SessionEnd ---------------------------------------------------------------------def session_end(self):+ # An end with no start and no session log is no session to learn from: Codex 0.163.0+ # sends one for a thread that never ran a prompt (`codex debug prompt-input`), and+ # recording it would only leave an unreadable fold in the ledger.+ tp = self.host.transcript(self.p)+ if not os.path.exists(self.store.path(self._sess_name())) and not (+ tp and os.path.exists(tp)):+ return {}s = self._session()self._close_turn(s, stopped_normally=False)s["ended"] = time.time()diff --git a/tokeneconomizer/plugin/denylist.py b/tokeneconomizer/plugin/denylist.pyindex 4dd1c41..9a8781a 100644--- a/tokeneconomizer/plugin/denylist.py+++ b/tokeneconomizer/plugin/denylist.py@@ -26,8 +26,9 @@ Rules common to all three:* Only the person's approval (`te toolprune apply`), or `toolprune: auto`, writes the file,and only from the NEXT session: tools are fixed at session start, and changing themmid-session would rewrite the cached prompt prefix.- * The writer adds and removes exactly the entries it recorded adding (`untool_applied.json`);- an entry the person wrote is never touched.+ * The writer adds and removes exactly the entries it recorded adding (`untool_applied.json`,+ per settings file, since the clones of one repository share its state but not their+ settings); an entry the person wrote is never touched.* When the plugin creates the file, it adds the path to `.git/info/exclude`, so a file meantto be per-user can never be committed by accident.@@ -162,13 +163,48 @@ def _exclude_from_git(repo_root, rel=SETTINGS_REL):return False-def applied(store):- return list((store.read("untool_applied.json") or {}).get("tools", []))+# What the writer added, per settings file: clones and worktrees of one repository share its+# state (and so its proposal), but each checkout has its own settings file. Up to 0.1.0 the+# record held one file's entries (`{"tools", "path"}`); that shape is still read.+APPLIED = "untool_applied.json"+++def _canon(path):+ return os.path.realpath(path) if path else ""+++def applied_by_path(doc):+ """{settings file: [entries the plugin added to it]} from an `untool_applied.json`."""+ if isinstance(doc.get("by_path"), dict):+ return {_canon(p): list(t or []) for p, t in doc["by_path"].items()}+ if doc.get("tools"):+ return {_canon(doc.get("path") or ""): list(doc["tools"])}+ return {}+++def write_applied(store, by_path):+ store.write(APPLIED, {"by_path": {p: sorted(t) for p, t in by_path.items() if t},+ "updated": time.time()})+++def applied(store, path=None):+ """What the plugin added to the settings file at `path`; without one, to any checkout's."""+ by = applied_by_path(store.read(APPLIED) or {})+ if path is None:+ return sorted(set().union(*by.values())) if by else []+ return list(by.get(_canon(path)) or by.get("") or [])+++def applied_for(store, repo_root, host="claude"):+ """What the plugin added to this checkout's settings file for `host`."""+ return applied(store, settings_path(repo_root, host))def _record(store, items, path):- store.write("untool_applied.json", {"tools": sorted(items), "path": path,- "updated": time.time()})+ by = applied_by_path(store.read(APPLIED) or {})+ by.pop("", None)+ by[_canon(path)] = sorted(items)+ write_applied(store, by)# ---- the JSON-list hosts: Claude Code's deny rules, Copilot's disabled MCP servers -------@@ -191,12 +227,12 @@ def _apply_json_list(repo_root, items, store, host):write_json(path, data)if created:_exclude_from_git(repo_root, _SETTINGS[host])- _record(store, set(applied(store)) | set(added), path)+ _record(store, set(applied(store, path)) | set(added), path)return addeddef _restore_json_list(repo_root, store, items, host):- mine = set(applied(store))+ mine = set(applied(store, settings_path(repo_root, host)))target = mine if not items else mine & set(items)if not target:return []@@ -358,7 +394,7 @@ def _apply_codex(repo_root, capabilities, store):text = originaladded = []for cap in capabilities:- if cap not in CODEX_TOGGLES or cap in applied(store):+ if cap not in CODEX_TOGGLES or cap in applied(store, path):continuefor table, key, value in CODEX_TOGGLES[cap]:text, _ = _toml_insert(text, table, key, value, f"{MARK}:{cap}")@@ -377,12 +413,12 @@ def _apply_codex(repo_root, capabilities, store):raise RuntimeError(f"Codex rejected the edited {path}, so it was put back: {err}")if created:_exclude_from_git(repo_root, CODEX_CONFIG_REL)- _record(store, set(applied(store)) | set(added), path)+ _record(store, set(applied(store, path)) | set(added), path)return addeddef _restore_codex(repo_root, store, capabilities):- mine = set(applied(store))+ mine = set(applied(store, settings_path(repo_root, "codex")))target = mine if not capabilities else mine & set(capabilities)if not target:return []diff --git a/tokeneconomizer/plugin/fold.py b/tokeneconomizer/plugin/fold.pyindex e5be66a..e8b0181 100644--- a/tokeneconomizer/plugin/fold.py+++ b/tokeneconomizer/plugin/fold.py@@ -95,7 +95,7 @@ def _fold_toolprune(ctx, adapter, run_dir, session_id, transcript=None, workdir=stage.tool_unused_streaks = {k: int(v) for k, v in (st.get("streaks") or {}).items()}stage.catalog_tools = set(st.get("catalog_tools", []))stage.catalog_desc = dict(st.get("catalog_desc") or {})- applied = denylist.applied(ctx.store)+ applied = denylist.applied_for(ctx.store, ctx.repo.root, ctx.host.name)stage._exclude_tools = list(applied) # the mask this session actually ran under# A tool that has since become protected (the web tools, from this version on) comes back:# remove the plugin's OWN deny rule for it. Only rules it recorded adding, never one the@@ -109,7 +109,7 @@ def _fold_toolprune(ctx, adapter, run_dir, session_id, transcript=None, workdir=except RuntimeError: # an unreadable or redirected settings file: leave itrestored = []if restored:- applied = denylist.applied(ctx.store)+ applied = denylist.applied_for(ctx.store, ctx.repo.root, ctx.host.name)# The stage warns once per STREAM when no catalog parses -- a harness defect signal there.# Here a stage lives for one fold, and a session that called no tool legitimately has no# observed catalog; the source (or its absence) is recorded in untool.json instead.@@ -189,7 +189,7 @@ def _fold_toolprune_codex(ctx, adapter, session_id, transcript, workdir):repo=ctx.repo.label, results_root=ctx.mech_dir, fresh=False)stage._warned_no_catalog = Truestage.build_tools({"instance_id": session_id}, 0)- applied = denylist.applied(ctx.store)+ applied = denylist.applied_for(ctx.store, ctx.repo.root, ctx.host.name)stage.codex_profile._pending["logical_capabilities"] = sorted(applied)srow = {}stage.after_task({"instance_id": session_id}, {}, run_dir, srow)@@ -269,7 +269,7 @@ def fold_session(ctx, session_id, transcript_path=None):"turns": len(turns),"nudges": int(sess.get("nudges", 0)), "aborts": int(sess.get("aborts", 0)),"injected_chars": int(sess.get("injected_chars", 0)),- "untool_applied": denylist.applied(ctx.store),+ "untool_applied": denylist.applied_for(ctx.store, ctx.repo.root, ctx.host.name),"overhead": {"optimizer_tokens": ((record.get("injection") or {}).get("optimizer_tokens")or 0),@@ -307,8 +307,9 @@ def pending_sessions(ctx, exclude=(), stale_s=STALE_S, now=None):except OSError:quiet = Falseif sess.get("ended") or quiet:- out.append(sid)- return out+ out.append((float(sess.get("started") or 0), sid))+ # Oldest first: the sessions a migration hands over are folded in the order they ran.+ return [sid for _, sid in sorted(out)]def spawn_fold(ctx, session_ids):diff --git a/tokeneconomizer/plugin/hook.py b/tokeneconomizer/plugin/hook.pyindex ed35d13..ebadd09 100644--- a/tokeneconomizer/plugin/hook.py+++ b/tokeneconomizer/plugin/hook.py@@ -26,7 +26,8 @@ def run(payload, env, host_hint=None):from .context import LiveContextfrom .controller import LiveControllerhost = hosts.detect(payload, env, hint=host_hint)- ctx = LiveContext.build(host, host.cwd(payload, env), env)+ ctx = LiveContext.build(host, host.cwd(payload, env), env,+ session_id=host.session_id(payload) or None, settle=False)return LiveController(ctx, payload).handle()diff --git a/tokeneconomizer/plugin/hosts.py b/tokeneconomizer/plugin/hosts.pyindex 30373cf..439b213 100644--- a/tokeneconomizer/plugin/hosts.py+++ b/tokeneconomizer/plugin/hosts.py@@ -122,6 +122,11 @@ class Host:def cwd(self, p, env):return p.get("cwd") or env.get("CLAUDE_PROJECT_DIR") or os.getcwd()+ def env_session_id(self, env):+ """The session a `te` command runs inside, from its shell's environment ("" if none is+ named). `TE_SESSION_ID` is set by the Pi extension's `/te`."""+ return str(env.get("TE_SESSION_ID") or "")+def turn_key(self, p):return ""@@ -206,6 +211,10 @@ class ClaudeCode(Host):def turn_key(self, p):return str(p.get("prompt_id") or "")+ def env_session_id(self, env):+ # Claude Code exports its session id to the Bash tool's shell (seen on 2.1.304).+ return str(env.get("TE_SESSION_ID") or env.get("CLAUDE_CODE_SESSION_ID") or "")+def stop(self, reason):return {"continue": False, "stopReason": reason}diff --git a/tokeneconomizer/plugin/paths.py b/tokeneconomizer/plugin/paths.pyindex 8bb7d49..bac1180 100644--- a/tokeneconomizer/plugin/paths.py+++ b/tokeneconomizer/plugin/paths.py@@ -1,10 +1,13 @@"""Where live state lives, and which repository a session belongs to.-State is keyed by REPOSITORY, not by directory: two worktrees of one clone, or a session started-in a subdirectory, are the same stream of work and should share what was learned about it. The-key is derived from the `origin` remote when there is one (so a re-clone keeps its history) and-from the real path of the checkout otherwise. Reading the remote parses `.git/config` directly ---a hook that shelled out to `git` would pay a subprocess on every tool call.+State is keyed by REPOSITORY, not by directory: two clones or worktrees of one repository, or a+session started in a subdirectory, are the same stream of work and should share what was+learned about it. The key is derived from the `origin` remote when there is one (so a re-clone+keeps its history), from the real path of the main checkout otherwise, and from the directory+itself outside any checkout. Reading the remote parses `.git/config` directly -- a hook that+shelled out to `git` would pay a subprocess on every tool call. Which repository a running+session belongs to is decided once, at its first hook, and pinned (`repos`); state written under+an earlier key is carried over by `repos` too.The state root is `$TOKENECONOMIZER_HOME`, else `~/.tokeneconomizer`. It is deliberately not ahost's plugin data directory: the CLI runs from the agent's Bash tool, where those variables are@@ -81,22 +84,58 @@ def ensure_launcher(env=None):return path+def home_dir(env=None):+ """The real path of the person's home directory ("" if there is none)."""+ env = os.environ if env is None else env+ home = env.get("HOME") or os.path.expanduser("~")+ return os.path.realpath(home) if home and home != "~" else ""+++def _gitdir_of_file(dot):+ """The directory a `.git` FILE points at (`gitdir: <path>`), or None."""+ try:+ with open(dot, encoding="utf-8") as fh:+ line = fh.read(4096).strip()+ except OSError:+ return None+ if not line.startswith("gitdir:"):+ return None+ gitdir = line.split(":", 1)[1].strip()+ if not os.path.isabs(gitdir):+ gitdir = os.path.normpath(os.path.join(os.path.dirname(dot), gitdir))+ return gitdir+++def is_git_entry(dot):+ """Does the `.git` entry at `dot` make its directory a checkout, as git itself would take it?++ A directory counts when it holds `HEAD`; a file (a linked worktree, a submodule) when its+ `gitdir:` line names a directory that exists. An empty `.git` directory -- left behind by a+ tool, or by an undone `git init` -- is no repository to git, and so none here."""+ if os.path.isdir(dot):+ return os.path.isfile(os.path.join(dot, "HEAD"))+ gitdir = _gitdir_of_file(dot)+ return bool(gitdir) and os.path.isdir(gitdir)++def find_repo_root(start, env=None):- """The nearest directory at or above `start` that holds a `.git` entry, else None.+ """The nearest directory at or above `start` that is a git checkout (`is_git_entry`), else+ None.- `.git` may be a directory (a clone) or a file (a worktree or submodule), so existence is the- test, not `isdir`. The walk honours `GIT_CEILING_DIRECTORIES` as git does: it never climbs- into a listed directory, so a stray `.git` in a shared parent (`/tmp`, a versioned home- directory) need not swallow every session beneath it."""+ The walk honours `GIT_CEILING_DIRECTORIES` as git does -- it never climbs into a listed+ directory -- and treats the home directory as one more ceiling for anything below it: a+ versioned home directory is the repository of a session started in `~` itself, never of+ every unversioned project underneath it."""env = os.environ if env is None else envceilings = {os.path.abspath(c) for c in(env.get("GIT_CEILING_DIRECTORIES") or "").split(os.pathsep) if c}+ home = home_dir(env)cur = os.path.abspath(start or os.getcwd())while True:- if os.path.exists(os.path.join(cur, ".git")):+ if is_git_entry(os.path.join(cur, ".git")):return curparent = os.path.dirname(cur)- if parent == cur or parent in ceilings:+ if parent == cur or parent in ceilings or (home and os.path.realpath(parent) == home):return Nonecur = parent@@ -106,16 +145,9 @@ def _git_common_dir(root):dot = os.path.join(root, ".git")if os.path.isdir(dot):return dot- try:- with open(dot, encoding="utf-8") as fh:- line = fh.read().strip()- except OSError:- return None- if not line.startswith("gitdir:"):+ gitdir = _gitdir_of_file(dot)+ if not gitdir:return None- gitdir = line.split(":", 1)[1].strip()- if not os.path.isabs(gitdir):- gitdir = os.path.normpath(os.path.join(root, gitdir))# A worktree's gitdir is <main>/.git/worktrees/<name>; `commondir` points back at <main>/.git.try:with open(os.path.join(gitdir, "commondir"), encoding="utf-8") as fh:@@ -167,24 +199,53 @@ def _slug(text):return re.sub(r"[^a-z0-9]+", "-", (text or "repo").lower()).strip("-")[:40] or "repo"+def digest(canon):+ return hashlib.sha1(canon.encode("utf-8")).hexdigest()[:10]+++# How a repository was identified, as `RepoId.how` records it.+BY_REMOTE, BY_PATH, BY_DIR = "remote", "path", "dir"++@dataclass(frozen=True)class RepoId:root: str # the checkout this session runs inkey: str # stable directory name for its statelabel: str # human name, used in rendered manuals ("owner/repo" or the basename)remote: str # normalized remote, "" when the checkout has none+ how: str = "" # BY_REMOTE, BY_PATH (a checkout with no remote) or BY_DIR (no checkout)+++def _main_checkout(root):+ """The directory holding a checkout's shared `.git`: the checkout itself, or for a linked+ worktree the clone it was made from. None when that git directory is not a `.git` (a bare+ repository's worktree, `--separate-git-dir`)."""+ common = _git_common_dir(root)+ if common and os.path.basename(os.path.normpath(common)) == ".git":+ return os.path.dirname(os.path.normpath(common))+ return Nonedef repo_identity(cwd, env=None):- """Identify the repository a session in `cwd` belongs to."""- root = find_repo_root(cwd, env) or os.path.abspath(cwd or os.getcwd())- has_git = os.path.exists(os.path.join(root, ".git"))- remote = normalize_remote(origin_url(root)) if has_git else ""- canon = remote or os.path.realpath(root)- label = "/".join(remote.split("/")[-2:]) if remote else os.path.basename(root.rstrip("/"))- digest = hashlib.sha1(canon.encode("utf-8")).hexdigest()[:10]- return RepoId(root=root, key=f"{_slug(os.path.basename(root.rstrip('/')))}-{digest}",- label=label or "repo", remote=remote)+ """Identify the repository a session in `cwd` belongs to.++ One repository has one key however it is checked out: its normalized `origin` remote when+ it has one (every clone, worktree and re-clone), else the real path of its main checkout (a+ linked worktree shares its clone's), else -- outside any checkout -- the directory itself.+ The key's readable part is the repository's name (the remote's last component, or the main+ checkout's folder), not the folder one particular checkout sits in."""+ found = find_repo_root(cwd, env)+ root = found or os.path.abspath(cwd or os.getcwd())+ remote = normalize_remote(origin_url(root)) if found else ""+ if remote:+ how, canon, name = BY_REMOTE, remote, remote.rstrip("/").rsplit("/", 1)[-1]+ label = "/".join(remote.split("/")[-2:])+ else:+ main = (_main_checkout(root) or _git_common_dir(root) or root) if found else root+ how, canon = (BY_PATH if found else BY_DIR), os.path.realpath(main)+ name = label = os.path.basename(main.rstrip("/"))+ return RepoId(root=root, key=f"{_slug(name)}-{digest(canon)}", label=label or "repo",+ remote=remote, how=how)def repo_state_dir(repo, host, env=None):diff --git a/tokeneconomizer/plugin/repos.py b/tokeneconomizer/plugin/repos.pynew file mode 100644index 0000000..8f1c489--- /dev/null+++ b/tokeneconomizer/plugin/repos.py@@ -0,0 +1,853 @@+"""Which repository's state a session belongs to, over time: session pins, the checkout index,+carrying state over from an earlier key, and the listing behind `te repos`.++Three things used to put one repository's sessions under several keys, or several repositories'+sessions under one; each has its remedy here.++ * A session that changes directory. Every hook names the directory the agent is in NOW --+ Claude Code's `cwd` follows the agent's `cd` -- so a session that moved into another+ repository was recorded under both. The first hook of a session pins it+ (`<root>/sessions/<host>/<id>.json`), and every later hook, and the fold it hands off, uses+ the pinned repository: the one the session started in, which is also where the agent files+ its own session log.+ * A key that changed. Up to 0.1.0 a checkout's folder name was part of the key, any `.git`+ entry made a checkout (an empty one in a home directory took in every project below it), and+ a repository's `origin` can move. The first time a checkout is seen (`index.json` remembers+ the ones already seen) the state its earlier keys hold is sent where it belongs (`adopt`);+ `te repos migrate` does the same for every state directory, and runs by itself, once, in+ the background after an upgrade.+ * Sessions filed under a repository that is not theirs. Each recorded session names the+ directory it ran in; one whose directory now resolves to another repository moves there+ and is folded again, so that repository learns from it (`migrate_dir`).++Nothing is deleted on the way. A state directory merged whole is set aside under+`<root>/merged/`; learned state that gives way to another's is kept beside it as `premerge-*`;+a session that moves keeps its ledger record when its log is gone and it cannot be folded again.+"""+import contextlib+import json+import os+import re+import shutil+import time+import traceback++from . import hosts as hosts_mod+from .paths import (BY_PATH, BY_REMOTE, RepoId, _slug, digest, home_dir, is_git_entry,+ normalize_remote, origin_url, repo_identity, state_root)+from .store import Store++INDEX = "index.json"+LAYOUT = 2 # the state layout this version writes (1: everything up to 0.1.0)+PIN_MAX_AGE_S = 30 * 86400 # a session pinned this long ago is over (a resume pins anew)+LOCK_WAIT_S = 2.0 # how long a hook waits to carry state over before trying next time+MIGRATE_RESPAWN_S = 600 # a background migration started this recently is still running+_FIELDS = ("root", "key", "label", "remote", "how")+# A fold derives these from session logs, so a merge keeps one side's and folds the other+# side's sessions again; the guard's envelope comes from Stop hooks instead and is concatenated.+LEARNED = ("injection.json", "untool.json", "mechanisms")+++def repos_dir(root):+ return os.path.join(root, "repos")+++def _repo_dir(root, key):+ return os.path.join(repos_dir(root), key)+++def _record_error(root):+ try:+ os.makedirs(root, exist_ok=True)+ with open(os.path.join(root, "errors.log"), "a", encoding="utf-8") as fh:+ fh.write(f"--- {time.strftime('%Y-%m-%dT%H:%M:%S')} pid={os.getpid()} (repos)\n")+ fh.write(traceback.format_exc())+ except Exception:+ pass+++# ---- session pins ---------------------------------------------------------------------------+def _pin_store(root, host):+ return Store(os.path.join(root, "sessions", host))+++def _pin_name(session_id):+ return re.sub(r"[^A-Za-z0-9._-]", "_", str(session_id))[:200] + ".json"+++def _repo_from(d):+ if not isinstance(d, dict) or not d.get("key") or not d.get("root"):+ return None+ return RepoId(**{k: str(d.get(k) or "") for k in _FIELDS})+++def pinned(root, host, session_id):+ """The repository a running session was pinned to, following any merge since; or None.++ Only a merge made AFTER the pin moves it: a key merged away can come back -- a checkout+ whose only state was a stray fragment of another session -- and a session pinned to it+ since then belongs to it, even before it has written anything there."""+ doc = _pin_store(root, host).read(_pin_name(session_id))+ repo = _repo_from(doc)+ if repo is None or os.path.isdir(_repo_dir(root, repo.key)):+ return repo+ redirects = (Store(root).read(INDEX) or {}).get("redirects") or {}+ key, hops, since = repo.key, 0, float(doc.get("at") or 0)+ while key in redirects and hops < 8:+ r = redirects[key]+ if float(r.get("at") or 0) < since:+ break+ key, hops = r.get("to"), hops + 1+ if not key or key == repo.key:+ return repo+ return RepoId(root=repo.root, key=key, label=repo.label, remote=repo.remote, how=repo.how)+++def pin(root, host, session_id, repo, cwd):+ _pin_store(root, host).write(_pin_name(session_id), dict(+ {k: getattr(repo, k) for k in _FIELDS}, cwd=cwd, at=time.time()))+++def prune_pins(root, host, now=None, max_age_s=PIN_MAX_AGE_S):+ """Remove pins older than `max_age_s`; at most once a day, so a hook pays nothing."""+ st = _pin_store(root, host)+ now = now or time.time()+ marker = st.path(".pruned")+ try:+ if now - os.path.getmtime(marker) < 86400:+ return 0+ except OSError:+ pass+ n = 0+ try:+ for name in os.listdir(st.base):+ p = st.path(name)+ if name.endswith(".json") and now - os.path.getmtime(p) > max_age_s:+ os.remove(p)+ n += 1+ open(marker, "w").close()+ except OSError:+ pass+ return n+++# ---- the identity the plugin used up to 0.1.0 (frozen: migration has to find that state) ----+def _legacy_root(start, env):+ env = os.environ if env is None else env+ ceilings = {os.path.abspath(c) for c in+ (env.get("GIT_CEILING_DIRECTORIES") or "").split(os.pathsep) if c}+ cur = os.path.abspath(start)+ while True:+ if os.path.exists(os.path.join(cur, ".git")):+ return cur+ parent = os.path.dirname(cur)+ if parent == cur or parent in ceilings:+ return None+ cur = parent+++def legacy_key(cwd, env=None):+ """The key 0.1.0 gave `cwd`: any `.git` entry made a checkout, the walk did not stop at the+ home directory, and the key's readable part was the checkout's own folder name."""+ root = _legacy_root(cwd, env) or os.path.abspath(cwd)+ remote = normalize_remote(origin_url(root)) if os.path.exists(+ os.path.join(root, ".git")) else ""+ return f"{_slug(os.path.basename(root.rstrip('/')))}-{digest(remote or os.path.realpath(root))}"+++# ---- reading one state directory ----------------------------------------------------------------+def _host_dirs(repo_dir):+ try:+ return sorted(h for h in os.listdir(repo_dir)+ if h in hosts_mod.HOSTS and os.path.isdir(os.path.join(repo_dir, h)))+ except OSError:+ return []+++def _sessions(st):+ """{session_id: record} for one agent's state, counting a session known only to the fold."""+ out = {}+ d = st.path("sessions")+ try:+ names = sorted(os.listdir(d))+ except OSError:+ names = []+ for name in names:+ if name.endswith(".json"):+ rec = st.read(os.path.join("sessions", name))+ out[name[:-5]] = rec if isinstance(rec, dict) else {}+ for sid in st.read("folded.json") or {}:+ out.setdefault(sid, {})+ return out+++_CWD_RE = re.compile(r'"cwd"\s*:\s*("(?:[^"\\]|\\.)*")')+++def _transcript_cwd(path):+ """The first directory a session log names (every agent's log records where it started)."""+ try:+ with open(path, encoding="utf-8", errors="replace") as fh:+ m = _CWD_RE.search(fh.read(262144))+ return json.loads(m.group(1)) if m else None+ except (OSError, ValueError, TypeError):+ return None+++def session_cwd(rec, folded=None):+ """Where a recorded session started: the first directory its log names, else its record's+ `cwd`. The log comes first because every fragment of a session (0.1.0 filed one wherever+ the agent had moved) shares it, and because 0.1.0 rewrote a record's `cwd` at every+ SessionStart, a compaction's included."""+ return _transcript_cwd(_transcript_of(rec, folded)) or rec.get("cwd") or None+++def _transcript_of(rec, folded_entry):+ return rec.get("transcript") or (folded_entry or {}).get("transcript") or ""+++def _has_learned(st):+ for name in LEARNED:+ p = st.path(name)+ if os.path.isfile(p) or (os.path.isdir(p) and any(os.scandir(p))):+ return True+ return False+++def dir_label(repo_dir):+ """The repository name a state directory was learned under: its `repo.json`, else the name its+ micro-skill state is filed under, else its ledger's."""+ doc = Store(repo_dir).read("repo.json") or {}+ if doc.get("label"):+ return doc["label"]+ for h in _host_dirs(repo_dir):+ st = Store(os.path.join(repo_dir, h))+ for sub in ("envfacts_state", "manual_state"):+ try:+ names = [n for n in os.listdir(st.path("mechanisms", sub)) if n.endswith(".json")]+ except OSError:+ continue+ if names:+ return names[0][:-5].replace("__", "/")+ for rec in reversed(st.read_lines("ledger.jsonl")):+ if rec.get("repo"):+ return rec["repo"]+ return ""+++def note_repo(root, repo):+ """Record a repository's identity beside its state, for `te repos` (once it has state)."""+ st = Store(_repo_dir(root, repo.key))+ if not os.path.isdir(st.base):+ return+ doc = st.read("repo.json") or {}+ want = {k: getattr(repo, k) for k in ("key", "label", "remote", "how")}+ if any(doc.get(k) != v for k, v in want.items()):+ st.write("repo.json", dict(doc, **want, updated=time.time()))+++# ---- moving sessions between state directories -----------------------------------------------+def _write_lines(st, name, records):+ target = st.path(name)+ os.makedirs(os.path.dirname(target), exist_ok=True)+ tmp = f"{target}.{os.getpid()}.tmp"+ with open(tmp, "w", encoding="utf-8") as fh:+ for r in records:+ fh.write(json.dumps(r, sort_keys=True) + "\n")+ os.replace(tmp, target)+++def _rename_label(mech_dir, label):+ """Mechanism state is filed by repository name; file what moved under the destination's."""+ if not label:+ return+ want = label.replace("/", "__")+ for sub in ("envfacts_state", "manual_state"):+ d = os.path.join(mech_dir, sub)+ try:+ names = [n for n in os.listdir(d) if n.endswith(".json")]+ except OSError:+ continue+ if len(names) == 1 and names[0] != want + ".json" and \+ not os.path.exists(os.path.join(d, want + ".json")):+ p = os.path.join(d, want + ".json")+ os.replace(os.path.join(d, names[0]), p)+ try:+ with open(p, encoding="utf-8") as fh:+ doc = json.load(fh)+ if isinstance(doc, dict) and "repo" in doc:+ doc["repo"] = label+ with open(p, "w", encoding="utf-8") as fh:+ json.dump(doc, fh, indent=2)+ except (OSError, ValueError):+ pass+ d = os.path.join(mech_dir, "interface_state")+ try:+ names = [n for n in os.listdir(d) if os.path.isdir(os.path.join(d, n))]+ except OSError:+ names = []+ if len(names) == 1 and names[0] != want and not os.path.exists(os.path.join(d, want)):+ os.replace(os.path.join(d, names[0]), os.path.join(d, want))+++def _take_learned(src, dst, label):+ """Move `src`'s learned state into `dst`, setting aside whatever `dst` had."""+ aside = None+ for name in LEARNED:+ p = dst.path(name)+ if os.path.isdir(p) and not any(os.scandir(p)):+ os.rmdir(p)+ elif os.path.lexists(p):+ aside = aside or dst.ensure(f"premerge-{time.strftime('%Y%m%d-%H%M%S')}")+ os.replace(p, os.path.join(aside, name))+ for name in LEARNED:+ if os.path.exists(src.path(name)):+ dst.ensure()+ shutil.move(src.path(name), dst.path(name))+ _rename_label(dst.path("mechanisms"), label)+ return aside+++def _merge_applied(src, dst):+ from .denylist import APPLIED, applied_by_path, write_applied+ by = applied_by_path(dst.read(APPLIED) or {})+ for path, tools in applied_by_path(src.read(APPLIED) or {}).items():+ by[path] = sorted(set(by.get(path) or []) | set(tools))+ if by:+ write_applied(dst, by)+++def _merge_envelope(src, dst):+ from ..loopguard.envelope import ENVELOPE_HISTORY+ a, b = src.read("envelope.json"), dst.read("envelope.json") or {}+ if not a:+ return+ merged = dict(b or a)+ for k in ("resolved_turns", "resolved_snaps"):+ merged[k] = (list(a.get(k) or []) + list(b.get(k) or []))[-ENVELOPE_HISTORY:]+ dst.write("envelope.json", merged)+++def _locks(stores, timeout):+ """Every lock a fold or the guard's envelope takes, on each store; yields whether all were."""+ with contextlib.ExitStack() as stack:+ ok = True+ for st in stores:+ for name in ("fold", "envelope"):+ if not stack.enter_context(st.locked(name, timeout=timeout)):+ ok = False+ break+ if not ok:+ break+ yield ok+++def _merge_host(src, dst, sids, whole, label="", timeout=LOCK_WAIT_S):+ """Move sessions `sids` of one agent's state `src` into `dst` (both Stores).++ Learned state is not additive, so one side keeps its own: with `whole`, `src`'s if it+ learned from more sessions (`dst`'s is set aside), else always `dst`'s. The sessions the+ surviving learned state never saw are unmarked as folded, so the destination's next session+ start folds them again from their logs; one whose log is gone keeps its ledger record and+ stays folded. Returns {"moved", "refold"}, or None when a lock could not be taken."""+ with _locks((src, dst), timeout) as ok:+ if not ok:+ return None+ s_folded, d_folded = src.read("folded.json") or {}, dst.read("folded.json") or {}+ s_sess, d_sess = _sessions(src), _sessions(dst)+ sids = [s for s in sids if s in s_sess]+ take = whole and _has_learned(src) and (+ not _has_learned(dst) or len(s_folded) > len(d_folded))+ # The sessions the surviving learned state has not seen: never one it folded itself.+ if take:+ unlearned = set(d_folded) - set(s_folded)+ _take_learned(src, dst, label)+ else:+ unlearned = (set(sids) & set(s_folded)) - set(d_folded)+ refold = set()+ for sid in unlearned:+ rec = s_sess.get(sid) if sid in sids else d_sess.get(sid)+ entry = (s_folded if sid in sids else d_folded).get(sid)+ tp = _transcript_of(rec or {}, entry)+ if tp and os.path.exists(tp):+ refold.add(sid)++ incoming = set(sids)+ s_ledger, d_ledger = src.read_lines("ledger.jsonl"), dst.read_lines("ledger.jsonl")+ # One session record per session: 0.1.0 could fold a session it had split over two keys+ # under both, and its cost counts once -- the later fold's, which read the longer log.+ # A refolded session's record is written again by its fold.+ sessions, other = {}, {}+ for r in d_ledger + [r for r in s_ledger if r.get("session_id") in incoming]:+ sid = r.get("session_id")+ if r.get("kind") == "session":+ cur = sessions.get(sid)+ if sid not in refold and (cur is None or float(r.get("folded_at") or 0)+ > float(cur.get("folded_at") or 0)):+ sessions[sid] = r+ else:+ other.setdefault((r.get("kind"), sid, r.get("at")), r)+ ledger = sorted(list(sessions.values()) + list(other.values()),+ key=lambda r: float(r.get("folded_at") or r.get("at") or 0))+ _write_lines(dst, "ledger.jsonl", ledger)+ folded = {s: v for s, v in d_folded.items() if s not in refold}+ folded.update({s: s_folded[s] for s in incoming if s in s_folded and s not in refold})+ dst.write("folded.json", folded)+ for sid in incoming:+ rec = dict(s_sess.get(sid) or {})+ mine = d_sess.get(sid)+ if mine and float(mine.get("updated") or 0) > float(rec.get("updated") or 0):+ rec = dict(mine)+ if rec:+ if sid in refold:+ rec["folded"] = False+ dst.write(os.path.join("sessions", f"{sid}.json"), rec)+ for sid in refold - incoming:+ rec = dict(d_sess.get(sid) or {})+ if rec:+ rec["folded"] = False+ dst.write(os.path.join("sessions", f"{sid}.json"), rec)+ for r in src.read_lines("events.jsonl"):+ if r.get("session_id") in incoming:+ dst.append("events.jsonl", r)+ if whole:+ _merge_envelope(src, dst)+ _merge_applied(src, dst)+ if src.read("notices.json") and not dst.read("notices.json"):+ dst.write("notices.json", src.read("notices.json"))+ else:+ _write_lines(src, "ledger.jsonl", [r for r in s_ledger+ if r.get("session_id") not in incoming])+ src.write("folded.json", {s: v for s, v in s_folded.items() if s not in incoming})+ for sid in incoming:+ with contextlib.suppress(OSError):+ os.remove(src.path("sessions", f"{sid}.json"))+ return {"moved": len(incoming), "refold": len(refold)}+++def merge_whole(root, src_key, dst_key, label="", timeout=LOCK_WAIT_S):+ """Merge every agent's state under `src_key` into `dst_key` and set `src_key` aside under+ `<root>/merged/`. The caller holds the index lock. Returns {host: counts}, or None."""+ src_dir, dst_dir = _repo_dir(root, src_key), _repo_dir(root, dst_key)+ label = label or dir_label(dst_dir) or dir_label(src_dir)+ out = {}+ for h in _host_dirs(src_dir):+ src, dst = Store(os.path.join(src_dir, h)), Store(os.path.join(dst_dir, h))+ r = _merge_host(src, dst, list(_sessions(src)), whole=True, label=label, timeout=timeout)+ if r is None:+ return None+ out[h] = r+ for name in ("config.json",): # a repository's own settings, if it had none+ if os.path.exists(os.path.join(src_dir, name)) and \+ not os.path.exists(os.path.join(dst_dir, name)):+ os.makedirs(dst_dir, exist_ok=True)+ shutil.copyfile(os.path.join(src_dir, name), os.path.join(dst_dir, name))+ aside = os.path.join(root, "merged", f"{src_key}.{time.strftime('%Y%m%d-%H%M%S')}")+ os.makedirs(os.path.dirname(aside), exist_ok=True)+ os.replace(src_dir, aside)+ # A session pinned to the old key follows it (`pinned`).+ idx = Store(root).read(INDEX) or {}+ redirects = {k: v for k, v in (idx.get("redirects") or {}).items()+ if k != dst_key and isinstance(v, dict)}+ redirects[src_key] = {"to": dst_key, "at": time.time()}+ idx["redirects"] = redirects+ Store(root).write(INDEX, idx)+ return out+++def _resolve(cwd, env, cache):+ """The repository `cwd` belongs to now; None when the directory is gone (nothing says)."""+ if not cwd or not os.path.isdir(cwd):+ return None+ if cwd not in cache:+ cache[cwd] = repo_identity(cwd, env)+ return cache[cwd]+++def plan_dir(root, key, env=None, cache=None):+ """({destination key: {"repo": RepoId, "hosts": {host: [session ids]}}}, here) for the+ sessions recorded under `key`, grouped by the repository each one started in, as it+ resolves now; a session whose directory is gone stays where it is and is not listed.+ `here` says whether any directory a session record names -- where a hook fired -- still+ resolves to `key`: a checkout that only ever saw sessions started elsewhere is still one."""+ cache = {} if cache is None else cache+ groups, here = {}, False+ repo_dir = _repo_dir(root, key)+ for h in _host_dirs(repo_dir):+ st = Store(os.path.join(repo_dir, h))+ folded = st.read("folded.json") or {}+ for sid, rec in _sessions(st).items():+ repo = _resolve(session_cwd(rec, folded.get(sid)), env, cache)+ if repo is not None:+ g = groups.setdefault(repo.key, {"repo": repo, "hosts": {}})+ g["hosts"].setdefault(h, []).append(sid)+ if not here and rec.get("cwd"):+ seen = _resolve(rec["cwd"], env, cache)+ here = seen is not None and seen.key == key+ return groups, here+++def _live(root, key, env, cache, idx):+ """Does a checkout that exists now resolve to `key`? (Seen in the index, checked afresh.)"""+ for path, v in (idx.get("checkouts") or {}).items():+ if v.get("key") == key:+ repo = _resolve(path, env, cache)+ if repo is not None and repo.key == key:+ return True+ return False+++def migrate_dir(root, key, env=None, timeout=LOCK_WAIT_S, cache=None, live=False):+ """Send each session recorded under `key` to the repository it started in, as that resolves+ now (`plan_dir`).++ Sessions that started in a directory resolving to `key` stay, with those whose directory is+ gone; the rest move out (`_merge_host`). When `key` is no live key any more -- no directory+ its sessions name and no known checkout resolves to it (`live` says one does): a key from+ before the derivation changed, or from a remote that moved -- the whole state directory+ goes to the repository most of its sessions belong to, learned state included+ (`merge_whole`). The caller holds the index lock. Returns {"key", "moves": [...], "into"},+ or None when a lock was busy."""+ out = {"key": key, "moves": [], "into": None}+ if not os.path.isdir(_repo_dir(root, key)):+ return out+ cache = {} if cache is None else cache+ groups, here = plan_dir(root, key, env, cache)+ if key in groups:+ note_repo(root, groups[key]["repo"])+ away = {k: g for k, g in groups.items() if k != key}+ if not away:+ return out+ live = live or here or key in groups or _live(root, key, env, cache,+ Store(root).read(INDEX) or {})+ whole_into = None if live else max(+ away, key=lambda k: sum(len(v) for v in away[k]["hosts"].values()))+ for dst_key, g in sorted(away.items()):+ if dst_key == whole_into:+ continue+ for h, sids in g["hosts"].items():+ r = _merge_host(Store(os.path.join(_repo_dir(root, key), h)),+ Store(os.path.join(_repo_dir(root, dst_key), h)), sids,+ whole=False, label=g["repo"].label, timeout=timeout)+ if r is None:+ return None+ out["moves"].append(dict(r, host=h, into=dst_key, cwd=g["repo"].root))+ note_repo(root, g["repo"])+ if whole_into:+ g = away[whole_into]+ r = merge_whole(root, key, whole_into, label=g["repo"].label, timeout=timeout)+ if r is None:+ return None+ out["into"] = whole_into+ note_repo(root, g["repo"])+ out["moves"].extend(dict(c, host=h, into=whole_into, cwd=g["repo"].root)+ for h, c in r.items())+ return out+++# ---- the checkout index ---------------------------------------------------------------------+def _record_moves(idx, done):+ """Count what a migration moved, for the one-time notice (`migration_notice`)."""+ moves = [m for r in done for m in r.get("moves") or ()]+ if moves:+ m = idx.get("migration") or {}+ idx["migration"] = {"at": time.time(), "noticed": False,+ "sessions": int(m.get("sessions") or 0) * (not m.get("noticed"))+ + sum(x["moved"] for x in moves),+ "merged": int(m.get("merged") or 0) * (not m.get("noticed"))+ + sum(1 for r in done if r.get("into"))}+ return idx+++def _candidates(root, repo, env, idx):+ """State directories that may hold this checkout's sessions under another key."""+ keys = []+ if repo.key not in (idx.get("checked") or {}):+ keys.append(repo.key) # sessions of other repositories filed here+ keys.append(legacy_key(repo.root, env))+ prev = ((idx.get("checkouts") or {}).get(os.path.realpath(repo.root)) or {}).get("key")+ if prev:+ keys.append(prev)+ if repo.how == BY_REMOTE: # other clones' and worktrees' folder names+ tail = "-" + repo.key.rsplit("-", 1)[-1]+ try:+ keys.extend(sorted(n for n in os.listdir(repos_dir(root)) if n.endswith(tail)))+ except OSError:+ pass+ seen, out = set(), []+ for k in keys:+ if k not in seen and os.path.isdir(_repo_dir(root, k)):+ seen.add(k)+ out.append(k)+ return out+++def _prune_index(idx, now):+ co = idx.get("checkouts") or {}+ idx["checkouts"] = {p: v for p, v in co.items()+ if os.path.isdir(p) or now - float(v.get("seen") or 0) < 30 * 86400}+ return idx+++def adopt(root, repo, env=None, timeout=LOCK_WAIT_S):+ """The first time a checkout is seen under its key, send the state its earlier keys hold+ where it belongs. Cheap after that: one read of `index.json`. Returns the migrations run."""+ real = os.path.realpath(repo.root)+ ist = Store(root)+ idx = ist.read(INDEX) or {}+ if ((idx.get("checkouts") or {}).get(real) or {}).get("key") == repo.key:+ return []+ done = []+ with ist.locked("index", timeout=timeout) as got:+ if not got:+ return []+ idx = ist.read(INDEX) or {}+ if ((idx.get("checkouts") or {}).get(real) or {}).get("key") == repo.key:+ return []+ ok, cache = True, {}+ for key in _candidates(root, repo, env, idx):+ r = migrate_dir(root, key, env, timeout=timeout, cache=cache, live=key == repo.key)+ if r is None:+ ok = False+ continue+ done.append(r)+ idx = ist.read(INDEX) or {}+ if os.path.isdir(_repo_dir(root, key)):+ idx.setdefault("checked", {})[key] = time.time()+ ist.write(INDEX, idx)+ note_repo(root, repo)+ if ok:+ idx = _record_moves(ist.read(INDEX) or {}, done)+ idx.setdefault("checkouts", {})[real] = {"key": repo.key, "seen": time.time()}+ idx.setdefault("checked", {})[repo.key] = time.time()+ ist.write(INDEX, _prune_index(idx, time.time()))+ return done+++def migrate_all(root, env=None, timeout=60.0):+ """`te repos migrate`: run `migrate_dir` over every state directory not yet checked, and mark+ the state root as on this layout. Returns the migrations run, or None if the index was busy."""+ ist = Store(root)+ done = []+ with ist.locked("index", timeout=timeout) as got:+ if not got:+ return None+ cache = {}+ try:+ keys = sorted(os.listdir(repos_dir(root)))+ except OSError:+ keys = []+ complete = True+ for key in keys:+ idx = ist.read(INDEX) or {}+ if key in (idx.get("checked") or {}) or not os.path.isdir(_repo_dir(root, key)):+ continue+ r = migrate_dir(root, key, env, timeout=timeout, cache=cache)+ if r is None:+ complete = False+ continue+ done.append(r)+ idx = ist.read(INDEX) or {}+ if os.path.isdir(_repo_dir(root, key)):+ idx.setdefault("checked", {})[key] = time.time()+ ist.write(INDEX, idx)+ idx = _record_moves(ist.read(INDEX) or {}, done)+ if complete:+ idx["layout"] = LAYOUT+ ist.write(INDEX, idx)+ return done+++def merge(root, src_key, dst_repo, timeout=60.0):+ """`te repos merge`: put one state directory into another, whatever its sessions' directories+ say -- for state whose checkouts are gone. `dst_repo` is a RepoId, or a key."""+ ist = Store(root)+ with ist.locked("index", timeout=timeout) as got:+ if not got:+ return None+ dst_key = dst_repo if isinstance(dst_repo, str) else dst_repo.key+ if not isinstance(dst_repo, str):+ note_repo(root, dst_repo)+ label = "" if isinstance(dst_repo, str) else dst_repo.label+ return merge_whole(root, src_key, dst_key, label=label, timeout=timeout)+++def needs_migration(root):+ """Whether this state root still holds state laid out by an earlier version."""+ if (Store(root).read(INDEX) or {}).get("layout", 0) >= LAYOUT:+ return False+ try:+ return any(os.path.isdir(_repo_dir(root, k)) for k in os.listdir(repos_dir(root)))+ except OSError:+ return False+++def start_migration(ctx):+ """Once after an upgrade: migrate every state directory, in the background (inline under+ `TE_FOLD_SYNC=1`, for tests). A marker keeps concurrent session starts from piling up."""+ root = ctx.root+ if not needs_migration(root):+ return False+ if ctx.env.get("TE_FOLD_SYNC") == "1":+ run_migration(root, ctx.env)+ return True+ marker = os.path.join(root, ".migrating")+ try:+ if time.time() - os.path.getmtime(marker) < MIGRATE_RESPAWN_S:+ return False+ except OSError:+ pass+ open(marker, "w").close()+ return ctx.spawn(["repos", "migrate", "--quiet"], "migrate.log")+++def run_migration(root, env=None):+ """`migrate_all`, then fold the sessions it moved, each where it now belongs."""+ done = migrate_all(root, env)+ if done is not None:+ with contextlib.suppress(OSError):+ os.remove(os.path.join(root, ".migrating"))+ if done:+ refold_moved(done, env)+ return done+++def migration_notice(root, command="te repos"):+ """Once, after a migration moved anything: a sentence saying so (else None)."""+ ist = Store(root)+ m = (ist.read(INDEX) or {}).get("migration") or {}+ if not m or m.get("noticed"):+ return None+ with ist.locked("index", timeout=LOCK_WAIT_S) as got:+ if not got:+ return None+ idx = ist.read(INDEX) or {}+ m = idx.get("migration") or {}+ if m.get("noticed"):+ return None+ m["noticed"] = True+ ist.write(INDEX, idx)+ return (f"TokenEconomizer: state recorded by an earlier version is now filed by repository "+ f"({m.get('sessions', 0)} session(s) moved, {m.get('merged', 0)} directory(ies) "+ f"merged; nothing deleted) -- see `{command}`.")+++def refold_moved(done, env=None):+ """Fold, where they landed, the sessions a migration unmarked as folded."""+ from .context import LiveContext+ from . import fold+ targets = {(m["host"], m["cwd"]) for r in done or () for m in r.get("moves") or ()+ if m.get("refold") and m.get("cwd")}+ for host, cwd in sorted(targets):+ try:+ ctx = LiveContext.build(hosts_mod.HOSTS[host](), cwd, env)+ fold.spawn_fold(ctx, fold.pending_sessions(ctx))+ except Exception:+ _record_error(state_root(env))+++def settle(root, host, repo, cwd, env=None, session_id=None):+ """Make `repo` the home of a hook or command in `cwd`: carry over what its earlier keys hold+ (`adopt`), then pin the session, if there is one, to it. Carrying over fails open -- an+ error there is logged, never raised. Returns whether any state moved."""+ moved = []+ try:+ moved = adopt(root, repo, env)+ except Exception:+ _record_error(root)+ if session_id:+ pin(root, host, session_id, repo, cwd)+ return any(r.get("moves") for r in moved)+++# ---- what `te repos` shows -------------------------------------------------------------------+def how_words(how, remote=""):+ if how == BY_REMOTE:+ return f"by its origin remote ({remote})"+ if how == BY_PATH:+ return "by its path (a git repository with no remote)"+ return "by its directory (not a git repository)"+++def describe(repo):+ """How a repository was identified, in words."""+ return "identified " + how_words(repo.how, repo.remote)+++def ignored_git_entries(cwd, env=None):+ """`.git` entries between `cwd` and its checkout (or the filesystem root) that git would not+ take for a repository, and so neither does `find_repo_root`."""+ out = []+ cur = os.path.abspath(cwd)+ while True:+ dot = os.path.join(cur, ".git")+ if is_git_entry(dot):+ return out+ if os.path.lexists(dot):+ out.append(dot)+ parent = os.path.dirname(cur)+ if parent == cur:+ return out+ cur = parent+++def listing(root, env=None, current=None):+ """One row per state directory: identity, agents and sessions, checkouts, notes."""+ idx = Store(root).read(INDEX) or {}+ checkouts = {}+ for path, v in (idx.get("checkouts") or {}).items():+ checkouts.setdefault(v.get("key"), []).append(path)+ home = home_dir(env)+ rows = []+ try:+ keys = sorted(os.listdir(repos_dir(root)))+ except OSError:+ keys = []+ for key in keys:+ d = _repo_dir(root, key)+ if not os.path.isdir(d):+ continue+ doc = Store(d).read("repo.json") or {}+ agents, cwds, last = {}, set(), 0.0+ for h in _host_dirs(d):+ st = Store(os.path.join(d, h))+ sess = _sessions(st)+ agents[h] = len(sess)+ for name in ("ledger.jsonl", "sessions"):+ try:+ last = max(last, os.path.getmtime(st.path(name)))+ except OSError:+ pass+ for rec in sess.values():+ if rec.get("cwd"):+ cwds.add(rec["cwd"])+ notes = []+ if key not in (idx.get("checked") or {}) and idx.get("layout", 0) < LAYOUT:+ notes.append("recorded by an earlier version; `te repos migrate` sorts it out "+ "(it runs by itself at the next session start)")+ if home and any(os.path.realpath(p) == home for p in checkouts.get(key, [])):+ notes.append("your home directory: holds only sessions started in ~ itself")+ rows.append({"key": key, "label": doc.get("label") or dir_label(d) or key,+ "how": doc.get("how", ""), "remote": doc.get("remote", ""),+ "agents": agents, "last": last, "state": d,+ "checkouts": sorted(checkouts.get(key, [])), "cwds": sorted(cwds),+ "current": bool(current and current.key == key), "notes": notes})+ try:+ merged = len(os.listdir(os.path.join(root, "merged")))+ except OSError:+ merged = 0+ rows.sort(key=lambda r: (not r["current"], -r["last"]))+ return rows, merged+++def home_git_note(env=None):+ """A sentence about a `.git` in the home directory, or None when there is none."""+ home = home_dir(env)+ if not home or not os.path.lexists(os.path.join(home, ".git")):+ return None+ if is_git_entry(os.path.join(home, ".git")):+ return (f"{home} is a git repository; it is the repository of sessions started there, "+ f"not of the unversioned directories below it")+ return (f"{home}/.git exists but is not a git repository (git ignores it, and so does "+ f"TokenEconomizer)")