sessiontools 0.3.1__tar.gz → 0.3.2__tar.gz

{sessiontools-0.3.1 → sessiontools-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sessiontools
-Version: 0.3.1
+Version: 0.3.2
 Summary: The harness layer: sessions, status and idle, one driver per harness - a library first
 Author: Mike Bailey
 Author-email: Mike Bailey <mike@sessionkit.ai>
@@ -61,6 +61,8 @@ eval "$(session completion bash)"
   category.
 - `session ledger --short`: each file read and command run, by tokens.
 - `session account status`: which Claude account this Mac is on.
+- `session account verify`: which account the API bills for this seat's
+  token, from one 1-token request.
 - `session start --list-agents`: the agents it can start.
 - `session reap`: seats idle past 1h, each CLOSE or KEEP, and why. A dry
   run.
@@ -129,8 +131,10 @@ it. Each line says what puts it there and what takes it away.
   sessiontools` drops this package's entries, and `uv cache prune` drops
   the ones nothing uses.
 - **Folders, each made by a verb you run:**
-  - `~/.session/state/list/`: the list cache, `snapshot.json` and
-    `list.lock`, at the first `session list`.
+  - `~/.sessionkit/tools/state/list/`: the list cache, `snapshot.json`
+    and `list.lock`, at the first `session list`. The state folders here
+    and below are on a fresh host; a host that still has
+    `~/.session/state/` keeps using it until it is moved.
   - `~/.session/sessions/<session-id>/`: one for each `session start`,
     holding `launch/`, `log/settings.jsonl` and `session-id`. It also
     gets `settings/<tool>.d/50-env.json`, one for each tool whose
@@ -139,14 +143,19 @@ it. Each line says what puts it there and what takes it away.
     `log/settings.jsonl` names each variable it read, never its value.
     The plugin's hooks and `session park` write only inside a folder
     that is already there.
-  - `~/.session/state/reap.log`: `session reap --yes`.
-  - `~/.session/state/pane-state/watch.lock`: the pane signal's service.
-  - `~/.session/state/default-model/`: `backups/` and `log.jsonl`, the
-    first time `session default-model enforce` changes settings.json.
+  - `~/.sessionkit/tools/state/pane-state/watch.lock`: the pane signal's
+    service.
+  - `~/.sessionkit/tools/state/default-model/`: `backups/` and
+    `log.jsonl`, the first time `session default-model enforce` changes
+    settings.json.
   - `~/.sessionkit/tools/accounts/`: `session account new` and `use`.
-  - `~/.local/share/sessiontools/sound/bin/`: `session sound engine on`
-    builds the sound engine there with `swiftc`.
-  - `~/Library/Logs/sessiontools/`: the two services' logs.
+  - `~/.sessionkit/tools/state/sound/bin/`: `session sound engine on`
+    builds the sound engine there with `swiftc` (in
+    `~/.local/share/sessiontools/sound/bin/` while that old folder is
+    still there).
+  - `~/.sessionkit/tools/log/`: the services' logs and `reap.log`
+    (Logs, below). An older release wrote them elsewhere, and those
+    files stay where they were.
   - `SESSIONS_DIR`, `SESSION_STATE_DIR` and `SESSIONTOOLS_SOUND_HOME`
     move these folders when set.
 - **Services (launchd agents):** none until you turn one on. Each `on`
@@ -188,6 +197,12 @@ it. Each line says what puts it there and what takes it away.
   With `model.default` set, `session default-model enforce` (and the
   unit or `watch` that runs it) rewrites the top-level `"model"` in
   `~/.claude/settings.json`, after a backup.
+- **Not changed by an upgrade: a live tmux server.** One born inside the
+  default seat by sessiontools 0.3.1 or earlier still hands
+  `CLAUDE_CODE_AGENT=claude` to every pane it makes, so a raw `claude`
+  there hears the seat's mail. Restarting that server, or running
+  `tmux set-environment -g -u CLAUDE_CODE_AGENT` on it, is yours to do
+  ([the default seat][default-seat]).
 
 ## Uninstall
 
@@ -208,23 +223,27 @@ uv tool uninstall sessiontools
 ```
 
 That leaves what the verbs made, listed above. The plugin's cached
-copy, the services' logs and the engine's folder are sessiontools'
-alone. To delete them:
+copy and the engine's folder are sessiontools' alone. To delete them:
 
 ```bash
 rm -rf "${HOME:?}/.claude/plugins/cache/sessiontools"
-rm -rf "${HOME:?}/Library/Logs/sessiontools"
 rm -rf "${HOME:?}/.local/share/sessiontools"
+rm -rf "${HOME:?}/.sessionkit/tools/state/sound"
 ```
 
+The logs are left in place: the new ones in `~/.sessionkit/tools/log/`,
+and an older release's in `~/Library/Logs/sessiontools/`. Nothing here
+deletes from `~/Library/Logs`.
+
 uv's cache stays too, with the other things uv installed; `uv cache
 clean sessiontools` drops this package's entries.
 
 The rest is your data: delete it by hand only if you want it gone.
-`~/.sessionkit/tools/` holds your settings and accounts, and the
-accounts folder keeps the backups of every token `session account use`
-replaced. `~/.session/` holds the session folders and the list cache,
-and the kit's other packages keep their files in it too.
+`~/.sessionkit/tools/` holds your settings, accounts, state and logs,
+and the accounts folder keeps the backups of every token `session
+account use` replaced. `~/.session/` holds the session folders (and, on
+a host that has not moved it, the old state folder), and the kit's other
+packages keep their files in it too.
 
 ## Docs
 
@@ -236,6 +255,10 @@ and the kit's other packages keep their files in it too.
 - [The `session list` cache][cache]: one computation, many readers
 - [Operator and privileged seats][operator]: who seats ask
 - [Closing idle seats][reap]: `session reap`, a dry run by default
+- [Where tools keeps its state][state-paths]: each folder, old and new,
+  the rule, and `session path`, the verb peers ask
+- [Moving tools' state][state-migrate]: `session path migrate`, one host
+  at a time, dry run first
 - [Shell completion][completion]: `session completion bash|zsh`, a static
   script built from the verbs' own parsers
 - [The Claude Code plugin][plugin]: the skill and the hooks
@@ -244,6 +267,8 @@ and the kit's other packages keep their files in it too.
 - [The busy sound][busy]: a sound while a tool batch runs long
 - [The session-info hooks][session-info]: the short session id as the
   session title, and the session's facts in context, both off by default
+- [The identity block][identity]: who a launched session is, in its
+  context on turn one and from `session identity`
 - [The sound engine][engine]: the busy sound from one resident process
 - [The status line][status-line]: `session statusline install` puts it in the
   kit's claude-code layer, never `~/.claude`. `session start` seats show it;
@@ -266,11 +291,28 @@ be set, and where each one lives ([configuration][configuration]):
 - **Settings files**, JSON in layers: `~/.sessionkit/tools/settings/session.json`
   (the operator, the list cache, the pane signal, accounts, a session's
   home, the default model), `~/.sessionkit/tools/settings/sounds.json` (the busy sound), and
-  `~/.sessionkit/tools/settings/claude-code.json` (the model, effort
-  and status line `session start` passes on). Every key, its default and
+  `~/.sessionkit/tools/settings/claude-code.json` (the model, effort,
+  status line and renderer `session start` passes on). Every key, its default and
   which layers it is read from: [settings][settings].
-- **Folders of its own:** `~/.session/` (sessions, seats, agent files, the
-  state dir) and `~/.sessionkit/tools/accounts/` (`session account`).
+- **Folders of its own:** `~/.sessionkit/tools/accounts/` (`session
+  account`), and its state, each leaf with an old and a new folder. A
+  fresh host starts `state` and `sound` in the new folder; an existing
+  one stays put until it is moved, and a moved one is followed
+  ([where tools keeps its state][state-paths]):
+  - `state`: `~/.session/state/`, new `~/.sessionkit/tools/state/`.
+  - `sessions`, `seats`, `agent` and `backups`: `~/.session/<leaf>/`, new
+    `~/.sessionkit/tools/state/<leaf>/`.
+  - `sound`: `~/.local/share/sessiontools/sound/`, new
+    `~/.sessionkit/tools/state/sound/`.
+  - **The rule, per leaf:** its variable when set; else the old folder
+    while it is real; else the new one when it exists; else the new one
+    for `state` and `sound`, the old one for the rest.
+  - **To see what is used:** `session path LEAF`, or `session path --json`.
+  - **To move `state` and `sound`:** `session path migrate --dry-run`,
+    then a real run with that host's go ([moving tools' state][state-migrate]).
+  - **Upgrade every copy of sessiontools on a host together,** other
+    packages' copies included: an older copy writes the old `state`
+    folder, and `session path --json` shows `stranded` when one lags.
 - **Environment variables:** the settle alert's `SESSION_SETTLE_AT`, the
   clock line's `SESSION_CLOCK_WARN_AT`, the hooks' `SESSIONTOOLS_HOOK_*`
   switches (`SESSIONTOOLS_HOOK_CLOCK=on` switches the clock line on), and
@@ -280,31 +322,43 @@ be set, and where each one lives ([configuration][configuration]):
 
 ## Logs
 
-- **The sound engine:** `~/Library/Logs/sessiontools/sound-engine.log`,
+- **The sound engine:** `~/.sessionkit/tools/log/sound-engine.log`,
   once `session sound engine on` has run.
-- **The pane signal's agent:** `~/Library/Logs/sessiontools/pane-state.log`,
+- **The pane signal's agent:** `~/.sessionkit/tools/log/pane-state.log`,
   once `session pane-state agent on` has run.
-- **The default model:** `~/.session/state/default-model/log.jsonl`, one
-  line per write to settings.json, and
-  `~/Library/Logs/sessiontools/default-model.log`, once you have loaded
+- **The default model:** `~/.sessionkit/tools/state/default-model/log.jsonl`
+  (`~/.session/state/default-model/log.jsonl` on a Mac that still has
+  its old state folder), one line per write to settings.json, and
+  `~/.sessionkit/tools/log/default-model.log`, once you have loaded
   the launchd agent `session default-model unit launchd` prints.
-- **`session reap --yes`:** `~/.session/state/reap.log`, one line for each
-  seat it closed or failed to close.
+- **`session reap --yes`:** `~/.sessionkit/tools/log/reap.log`, one line
+  for each seat it closed or failed to close.
 - **Each session's settings at birth:**
   `~/.session/sessions/<session-id>/log/settings.jsonl`, what `session
   start` read into that session's settings: each environment variable
   by name, never its value.
 - **The status line:** `~/.config/session/statusline-log.jsonl`, one line
   per render, only when `~/.config/session/` already exists.
+- **Old logs, 0.3.1 and before:** the three services logged to
+  `~/Library/Logs/sessiontools/`, and `session reap --yes` to
+  `$SESSION_STATE_DIR/reap.log` (`~/.session/state/reap.log`). Those
+  files are left in place. A service an older release installed keeps
+  writing its old log, at every login too, until its plist is written
+  again: `on` for the sound engine and the pane signal, the steps in
+  [the default model][default-model] for its agent. The sound engine's
+  and the pane signal's `status` name an old log while it is still there.
 
 Follow one as it grows with `tail -F`, for example
-`tail -F ~/Library/Logs/sessiontools/pane-state.log`.
+`tail -F ~/.sessionkit/tools/log/pane-state.log`.
 
 - **Health:** `session list` prints a row for each live session, with its
-  state and context. A session you know is running that is not listed is
-  one sessiontools cannot see.
+  state and context, and SEAT names the seat a session holds: `claude`
+  for the default seat, or an agent's name for its hand-launched
+  holder. A session you know is running that is not listed is one
+  sessiontools cannot see.
 
 [verbs]: docs/session.md
+[default-seat]: docs/session.md#the-default-seat
 [start]: docs/session-start-launcher.md
 [credentials]: docs/session-start-launcher.md#credentials-are-never-handed-down
 [account]: docs/account.md
@@ -312,11 +366,14 @@ Follow one as it grows with `tail -F`, for example
 [operator]: docs/operator-privileged-seats.md
 [reap]: docs/session-reap.md
 [completion]: docs/shell-completion.md
+[state-paths]: docs/tools-state-paths.md
+[state-migrate]: docs/tools-state-migrate.md
 [plugin]: docs/claude-code-plugin.md
 [settle]: docs/settle-alert-hook.md
 [clock]: docs/clock-line-hook.md
 [busy]: docs/busy-sound-hook.md
 [session-info]: docs/session-info-hook.md
+[identity]: docs/identity-block.md
 [engine]: docs/sound-engine-agent.md
 [status-line]: docs/status-line-script.md
 [pane-state]: docs/pane-state-signal.md

{sessiontools-0.3.1 → sessiontools-0.3.2}/README.md

@@ -45,6 +45,8 @@ eval "$(session completion bash)"
   category.
 - `session ledger --short`: each file read and command run, by tokens.
 - `session account status`: which Claude account this Mac is on.
+- `session account verify`: which account the API bills for this seat's
+  token, from one 1-token request.
 - `session start --list-agents`: the agents it can start.
 - `session reap`: seats idle past 1h, each CLOSE or KEEP, and why. A dry
   run.
@@ -113,8 +115,10 @@ it. Each line says what puts it there and what takes it away.
   sessiontools` drops this package's entries, and `uv cache prune` drops
   the ones nothing uses.
 - **Folders, each made by a verb you run:**
-  - `~/.session/state/list/`: the list cache, `snapshot.json` and
-    `list.lock`, at the first `session list`.
+  - `~/.sessionkit/tools/state/list/`: the list cache, `snapshot.json`
+    and `list.lock`, at the first `session list`. The state folders here
+    and below are on a fresh host; a host that still has
+    `~/.session/state/` keeps using it until it is moved.
   - `~/.session/sessions/<session-id>/`: one for each `session start`,
     holding `launch/`, `log/settings.jsonl` and `session-id`. It also
     gets `settings/<tool>.d/50-env.json`, one for each tool whose
@@ -123,14 +127,19 @@ it. Each line says what puts it there and what takes it away.
     `log/settings.jsonl` names each variable it read, never its value.
     The plugin's hooks and `session park` write only inside a folder
     that is already there.
-  - `~/.session/state/reap.log`: `session reap --yes`.
-  - `~/.session/state/pane-state/watch.lock`: the pane signal's service.
-  - `~/.session/state/default-model/`: `backups/` and `log.jsonl`, the
-    first time `session default-model enforce` changes settings.json.
+  - `~/.sessionkit/tools/state/pane-state/watch.lock`: the pane signal's
+    service.
+  - `~/.sessionkit/tools/state/default-model/`: `backups/` and
+    `log.jsonl`, the first time `session default-model enforce` changes
+    settings.json.
   - `~/.sessionkit/tools/accounts/`: `session account new` and `use`.
-  - `~/.local/share/sessiontools/sound/bin/`: `session sound engine on`
-    builds the sound engine there with `swiftc`.
-  - `~/Library/Logs/sessiontools/`: the two services' logs.
+  - `~/.sessionkit/tools/state/sound/bin/`: `session sound engine on`
+    builds the sound engine there with `swiftc` (in
+    `~/.local/share/sessiontools/sound/bin/` while that old folder is
+    still there).
+  - `~/.sessionkit/tools/log/`: the services' logs and `reap.log`
+    (Logs, below). An older release wrote them elsewhere, and those
+    files stay where they were.
   - `SESSIONS_DIR`, `SESSION_STATE_DIR` and `SESSIONTOOLS_SOUND_HOME`
     move these folders when set.
 - **Services (launchd agents):** none until you turn one on. Each `on`
@@ -172,6 +181,12 @@ it. Each line says what puts it there and what takes it away.
   With `model.default` set, `session default-model enforce` (and the
   unit or `watch` that runs it) rewrites the top-level `"model"` in
   `~/.claude/settings.json`, after a backup.
+- **Not changed by an upgrade: a live tmux server.** One born inside the
+  default seat by sessiontools 0.3.1 or earlier still hands
+  `CLAUDE_CODE_AGENT=claude` to every pane it makes, so a raw `claude`
+  there hears the seat's mail. Restarting that server, or running
+  `tmux set-environment -g -u CLAUDE_CODE_AGENT` on it, is yours to do
+  ([the default seat][default-seat]).
 
 ## Uninstall
 
@@ -192,23 +207,27 @@ uv tool uninstall sessiontools
 ```
 
 That leaves what the verbs made, listed above. The plugin's cached
-copy, the services' logs and the engine's folder are sessiontools'
-alone. To delete them:
+copy and the engine's folder are sessiontools' alone. To delete them:
 
 ```bash
 rm -rf "${HOME:?}/.claude/plugins/cache/sessiontools"
-rm -rf "${HOME:?}/Library/Logs/sessiontools"
 rm -rf "${HOME:?}/.local/share/sessiontools"
+rm -rf "${HOME:?}/.sessionkit/tools/state/sound"
 ```
 
+The logs are left in place: the new ones in `~/.sessionkit/tools/log/`,
+and an older release's in `~/Library/Logs/sessiontools/`. Nothing here
+deletes from `~/Library/Logs`.
+
 uv's cache stays too, with the other things uv installed; `uv cache
 clean sessiontools` drops this package's entries.
 
 The rest is your data: delete it by hand only if you want it gone.
-`~/.sessionkit/tools/` holds your settings and accounts, and the
-accounts folder keeps the backups of every token `session account use`
-replaced. `~/.session/` holds the session folders and the list cache,
-and the kit's other packages keep their files in it too.
+`~/.sessionkit/tools/` holds your settings, accounts, state and logs,
+and the accounts folder keeps the backups of every token `session
+account use` replaced. `~/.session/` holds the session folders (and, on
+a host that has not moved it, the old state folder), and the kit's other
+packages keep their files in it too.
 
 ## Docs
 
@@ -220,6 +239,10 @@ and the kit's other packages keep their files in it too.
 - [The `session list` cache][cache]: one computation, many readers
 - [Operator and privileged seats][operator]: who seats ask
 - [Closing idle seats][reap]: `session reap`, a dry run by default
+- [Where tools keeps its state][state-paths]: each folder, old and new,
+  the rule, and `session path`, the verb peers ask
+- [Moving tools' state][state-migrate]: `session path migrate`, one host
+  at a time, dry run first
 - [Shell completion][completion]: `session completion bash|zsh`, a static
   script built from the verbs' own parsers
 - [The Claude Code plugin][plugin]: the skill and the hooks
@@ -228,6 +251,8 @@ and the kit's other packages keep their files in it too.
 - [The busy sound][busy]: a sound while a tool batch runs long
 - [The session-info hooks][session-info]: the short session id as the
   session title, and the session's facts in context, both off by default
+- [The identity block][identity]: who a launched session is, in its
+  context on turn one and from `session identity`
 - [The sound engine][engine]: the busy sound from one resident process
 - [The status line][status-line]: `session statusline install` puts it in the
   kit's claude-code layer, never `~/.claude`. `session start` seats show it;
@@ -250,11 +275,28 @@ be set, and where each one lives ([configuration][configuration]):
 - **Settings files**, JSON in layers: `~/.sessionkit/tools/settings/session.json`
   (the operator, the list cache, the pane signal, accounts, a session's
   home, the default model), `~/.sessionkit/tools/settings/sounds.json` (the busy sound), and
-  `~/.sessionkit/tools/settings/claude-code.json` (the model, effort
-  and status line `session start` passes on). Every key, its default and
+  `~/.sessionkit/tools/settings/claude-code.json` (the model, effort,
+  status line and renderer `session start` passes on). Every key, its default and
   which layers it is read from: [settings][settings].
-- **Folders of its own:** `~/.session/` (sessions, seats, agent files, the
-  state dir) and `~/.sessionkit/tools/accounts/` (`session account`).
+- **Folders of its own:** `~/.sessionkit/tools/accounts/` (`session
+  account`), and its state, each leaf with an old and a new folder. A
+  fresh host starts `state` and `sound` in the new folder; an existing
+  one stays put until it is moved, and a moved one is followed
+  ([where tools keeps its state][state-paths]):
+  - `state`: `~/.session/state/`, new `~/.sessionkit/tools/state/`.
+  - `sessions`, `seats`, `agent` and `backups`: `~/.session/<leaf>/`, new
+    `~/.sessionkit/tools/state/<leaf>/`.
+  - `sound`: `~/.local/share/sessiontools/sound/`, new
+    `~/.sessionkit/tools/state/sound/`.
+  - **The rule, per leaf:** its variable when set; else the old folder
+    while it is real; else the new one when it exists; else the new one
+    for `state` and `sound`, the old one for the rest.
+  - **To see what is used:** `session path LEAF`, or `session path --json`.
+  - **To move `state` and `sound`:** `session path migrate --dry-run`,
+    then a real run with that host's go ([moving tools' state][state-migrate]).
+  - **Upgrade every copy of sessiontools on a host together,** other
+    packages' copies included: an older copy writes the old `state`
+    folder, and `session path --json` shows `stranded` when one lags.
 - **Environment variables:** the settle alert's `SESSION_SETTLE_AT`, the
   clock line's `SESSION_CLOCK_WARN_AT`, the hooks' `SESSIONTOOLS_HOOK_*`
   switches (`SESSIONTOOLS_HOOK_CLOCK=on` switches the clock line on), and
@@ -264,31 +306,43 @@ be set, and where each one lives ([configuration][configuration]):
 
 ## Logs
 
-- **The sound engine:** `~/Library/Logs/sessiontools/sound-engine.log`,
+- **The sound engine:** `~/.sessionkit/tools/log/sound-engine.log`,
   once `session sound engine on` has run.
-- **The pane signal's agent:** `~/Library/Logs/sessiontools/pane-state.log`,
+- **The pane signal's agent:** `~/.sessionkit/tools/log/pane-state.log`,
   once `session pane-state agent on` has run.
-- **The default model:** `~/.session/state/default-model/log.jsonl`, one
-  line per write to settings.json, and
-  `~/Library/Logs/sessiontools/default-model.log`, once you have loaded
+- **The default model:** `~/.sessionkit/tools/state/default-model/log.jsonl`
+  (`~/.session/state/default-model/log.jsonl` on a Mac that still has
+  its old state folder), one line per write to settings.json, and
+  `~/.sessionkit/tools/log/default-model.log`, once you have loaded
   the launchd agent `session default-model unit launchd` prints.
-- **`session reap --yes`:** `~/.session/state/reap.log`, one line for each
-  seat it closed or failed to close.
+- **`session reap --yes`:** `~/.sessionkit/tools/log/reap.log`, one line
+  for each seat it closed or failed to close.
 - **Each session's settings at birth:**
   `~/.session/sessions/<session-id>/log/settings.jsonl`, what `session
   start` read into that session's settings: each environment variable
   by name, never its value.
 - **The status line:** `~/.config/session/statusline-log.jsonl`, one line
   per render, only when `~/.config/session/` already exists.
+- **Old logs, 0.3.1 and before:** the three services logged to
+  `~/Library/Logs/sessiontools/`, and `session reap --yes` to
+  `$SESSION_STATE_DIR/reap.log` (`~/.session/state/reap.log`). Those
+  files are left in place. A service an older release installed keeps
+  writing its old log, at every login too, until its plist is written
+  again: `on` for the sound engine and the pane signal, the steps in
+  [the default model][default-model] for its agent. The sound engine's
+  and the pane signal's `status` name an old log while it is still there.
 
 Follow one as it grows with `tail -F`, for example
-`tail -F ~/Library/Logs/sessiontools/pane-state.log`.
+`tail -F ~/.sessionkit/tools/log/pane-state.log`.
 
 - **Health:** `session list` prints a row for each live session, with its
-  state and context. A session you know is running that is not listed is
-  one sessiontools cannot see.
+  state and context, and SEAT names the seat a session holds: `claude`
+  for the default seat, or an agent's name for its hand-launched
+  holder. A session you know is running that is not listed is one
+  sessiontools cannot see.
 
 [verbs]: docs/session.md
+[default-seat]: docs/session.md#the-default-seat
 [start]: docs/session-start-launcher.md
 [credentials]: docs/session-start-launcher.md#credentials-are-never-handed-down
 [account]: docs/account.md
@@ -296,11 +350,14 @@ Follow one as it grows with `tail -F`, for example
 [operator]: docs/operator-privileged-seats.md
 [reap]: docs/session-reap.md
 [completion]: docs/shell-completion.md
+[state-paths]: docs/tools-state-paths.md
+[state-migrate]: docs/tools-state-migrate.md
 [plugin]: docs/claude-code-plugin.md
 [settle]: docs/settle-alert-hook.md
 [clock]: docs/clock-line-hook.md
 [busy]: docs/busy-sound-hook.md
 [session-info]: docs/session-info-hook.md
+[identity]: docs/identity-block.md
 [engine]: docs/sound-engine-agent.md
 [status-line]: docs/status-line-script.md
 [pane-state]: docs/pane-state-signal.md

{sessiontools-0.3.1 → sessiontools-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sessiontools"
-version = "0.3.1"
+version = "0.3.2"
 description = "The harness layer: sessions, status and idle, one driver per harness - a library first"
 readme = "README.md"
 license = "AGPL-3.0-or-later"

{sessiontools-0.3.1 → sessiontools-0.3.2}/src/sessiontools/account/cli.py

@@ -1,12 +1,13 @@
-"""`session account list | status | use | new | add | remove`: the group's
-argparse `main(argv)`.
+"""`session account list | status | verify | use | new | add | remove`: the
+group's argparse `main(argv)`.
 
-`list`, `status`, `use` and `new` live in their own modules (`status`,
-`use`, `new`); this module parses their flags and calls them. `add` and
-`remove` live here.
+`list`, `status`, `verify`, `use` and `new` live in their own modules
+(`status`, `verify`, `use`, `new`); this module parses their flags and
+calls them. `add` and `remove` live here.
 
     session account list
     session account status [--json] [--no-resets]
+    session account verify [NAME] [--json]
     session account use NAME --witness WHO [--yes]
     session account new NAME --email E
     session account add NAME --email E --source BACKEND:REF [--source ...] [--no-fp]
@@ -55,12 +56,12 @@ Two deliberate calls:
 
 Exit codes: 0 done; 2 usage, unknown or duplicate name, a bad source; 3
 `remove` of the host's account; 4 (`add`) no source resolved; 5 a refused
-registry or config. `use` and `new` keep their own tables
-(`use.EXIT_CODES`, `new.EXIT_CODES`).
+registry or config. `verify`, `use` and `new` keep their own tables
+(`verify.EXIT_CODES`, `use.EXIT_CODES`, `new.EXIT_CODES`).
 
 Seams: every external is a keyword of `main` (the Keychain, the preflight,
-the seat scan, the usage fetcher, the backends, the environment, HOME, and
-`new`'s token store, capture and terminal), so
+the seat scan, the usage fetcher, `verify`'s transport, the backends, the
+environment, HOME, and `new`'s token store, capture and terminal), so
 the end-to-end test drives every verb on fakes. Left as None, each is the
 production default, chosen by the module that owns it.
 """
@@ -80,6 +81,7 @@ from sessiontools.account import keychain as kc
 from sessiontools.account import registry as reg
 from sessiontools.account import status as st
 from sessiontools.account import use as u
+from sessiontools.account import verify as vf
 
 if TYPE_CHECKING:
     from sessiontools.account.setuptoken import Run
@@ -93,6 +95,17 @@ EXIT_HOST = 3                           # remove: the host is on it
 EXIT_UNRESOLVED = reg.EXIT_UNRESOLVED   # 4
 EXIT_REGISTRY = reg.EXIT_REGISTRY       # 5
 
+#: The group's `-h` leads with how it knows the accounts and which one is in
+#: use (registry.default_path; status.host_of), and why `/login` moves every
+#: seat on a Keychain host (keychain.SERVICE). Raw: the line breaks are kept.
+DESCRIPTION = """\
+Which Claude account this Mac is on, and the switch. Never prints a token.
+Available: the accounts `new` or `add` put in ~/.sessionkit/tools/accounts/.
+In use: the host's token, fingerprinted and looked up in that list: the
+Keychain item's, or the file's when the setting account.token_file names one.
+/login moves every seat on a Keychain host: all with no env token read the item.
+"""
+
 EPILOG = """\
 By default the host signs in from the Keychain item all seats read: `use`
 moves every seat with no env token within about 50 s, and each one's
@@ -108,6 +121,12 @@ file unless its agent file says inherit: [CLAUDE_CODE_OAUTH_TOKEN];
 without it, it signs in from Claude's stored credentials, and `status`
 says so.
 
+`use` changes the token, never ~/.claude.json: Claude's /status and
+`claude auth status` name the account from that file's oauthAccount,
+so after a switch they can name the old one. `status` prints that name
+on its own profile line, and `verify` makes one 1-token request to show
+which account the API bills for a token.
+
 `new` runs `claude setup-token` in a masked copy of its screen, saves the
 token to passage at <PREFIX>/<E>, reads it back, and registers it. PREFIX
 is the `session` setting account.passage_prefix (default
@@ -123,6 +142,7 @@ backup or ledger (or `use`: a bad account.token_file or token file; or
 restored the item or file; 7 `use` could not restore it; 8 `new` did not save the
 token; 9 `new` saved it but did not register it.
 """
+EPILOG += "\n" + vf.EPILOG_LINE + "\n"
 
 
 class AccountError(Exception):
@@ -261,8 +281,7 @@ def remove(name: str, *, keychain: kc.Keychain | None = None,
 def parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog=PROG, epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter,
-        description="Which of the Claude accounts this Mac is on, and the switch "
-                    "between them. Never prints a token.")
+        description=DESCRIPTION)
     verbs = p.add_subparsers(dest="verb", metavar="VERB")
     verbs.required = True
 
@@ -272,13 +291,28 @@ def parser() -> argparse.ArgumentParser:
 
     s = verbs.add_parser("status", help="the host's account, this seat's, plan usage",
                          description="Which account the host is on, this seat's route, "
-                                     "and the plan usage of the live account.")
+                                     "the plan usage of the live account (a window past "
+                                     "its reset is STALE, its figure not shown), and the "
+                                     "account ~/.claude.json names (display only: the "
+                                     "token decides billing).")
     s.add_argument("--json", action="store_true", help="one JSON object")
     s.add_argument("--no-resets", action="store_true",
                    help="hide when each usage window resets (shown by default)")
     s.add_argument("--resets", action="store_true",
                    help="accepted and ignored: resets are shown by default")
 
+    v = verbs.add_parser("verify", help="ask the API which account a token bills",
+                         description="Make ONE 1-token request to the API with a token "
+                                     "and print the account-wide usage windows it "
+                                     "reports: the 7d reset identifies the account. "
+                                     "NAME: that registry account's token. No NAME: "
+                                     "the token this seat bills (the env token, else "
+                                     "the host's token file or Keychain item). Never "
+                                     "prints a token.")
+    v.add_argument("name", metavar="NAME", nargs="?",
+                   help="a registered account (default: this seat's token)")
+    v.add_argument("--json", action="store_true", help="one JSON object")
+
     # The usage line is written by hand: --witness is required to write, but
     # argparse's `required=True` would exit before `use` shows the plan.
     w = verbs.add_parser("use", help="move the HOST's sign-in to NAME",
@@ -329,6 +363,7 @@ def main(argv: Sequence[str] | None = None, *,
          preflight: u.Preflight | None = None,
          seat_scan: u.SeatScan | None = None,
          fetch: st.Fetcher | None = None,
+         post: vf.Post | None = None,
          backends: Mapping[str, reg.Backend] | None = None,
          env: Mapping[str, str] | None = None,
          home: str | os.PathLike | None = None,
@@ -340,7 +375,8 @@ def main(argv: Sequence[str] | None = None, *,
          out: TextIO | None = None, err: TextIO | None = None) -> int:
     """`session account VERB ...`. Returns the exit code. Every keyword is
     a seam; None is the production default. `store`, `capture` and `tty`
-    (stdin's fd, stdout's fd) are `new`'s; so is `preflight`, as `use`'s."""
+    (stdin's fd, stdout's fd) are `new`'s; so is `preflight`, as `use`'s.
+    `post` is `verify`'s transport."""
     out = sys.stdout if out is None else out
     err = sys.stderr if err is None else err
     try:
@@ -355,6 +391,9 @@ def main(argv: Sequence[str] | None = None, *,
     if args.verb == "status":
         return st.status(as_json=args.json, resets=not args.no_resets, keychain=keychain,
                          fetch=fetch, env=env, home=home, clock=clock, out=out, err=err)
+    if args.verb == "verify":
+        return vf.verify(args.name, as_json=args.json, keychain=keychain, backends=backends,
+                         env=env, home=home, post=post, clock=clock, out=out, err=err)
     if args.verb == "use":
         return u.use(args.name, witness=args.witness, yes=args.yes, keychain=keychain,
                      preflight=preflight, seat_scan=seat_scan, home=home,

{sessiontools-0.3.1 → sessiontools-0.3.2}/src/sessiontools/account/limits.py

@@ -26,8 +26,9 @@ What is read, and what is refused:
 - `written_at` is required: without it the file's age cannot be told, and an
   old file must never read as current. Past `STALE_AFTER` seconds the file
   is marked stale; its numbers are still shown.
-- A window whose `resets_at` has passed measured a window that is over. Its
-  percent is not shown (`expired`), never guessed to be 0.
+- A window whose `resets_at` has passed measured a window that is over. It
+  reads as the exporter's does (`status.stale_text`): STALE, when it ended,
+  its percent not shown (`expired`, `stale`), never guessed to be 0.
 - `account` must be absent or `"default"`, the host's own sign-in: any other
   account's window is not the host's usage.
 
@@ -204,6 +205,7 @@ def read_limits(path: str | os.PathLike, now: float) -> st.Usage:
     if age < -FUTURE_SLACK:
         return _malformed(path, "written_at is in the future")
 
+    age_s = max(0, int(age))
     windows = []
     for key, label in WINDOWS:
         raw = data.get(key)
@@ -217,10 +219,10 @@ def read_limits(path: str | os.PathLike, now: float) -> st.Usage:
         resets_at = _number(raw.get("resets_at"))
         expired = resets_at is not None and resets_at <= now
         windows.append(st.Window(label, None, None if expired else percent, resets_at,
-                                 expired=expired))
+                                 expired=expired, age_s=age_s,
+                                 ended_s=max(0, int(now - resets_at)) if expired else None))
     if not windows:
         return st.Usage(None, unavailable=f"{path} has no usage windows")
-    age_s = max(0, int(age))
     return st.Usage(None, tuple(windows), source=st.SOURCE_FILE, file=str(path),
                     written_at=written_at, age_s=age_s, stale=age_s > STALE_AFTER)