sessiontools 0.3.2__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sessiontools
-Version: 0.3.2
+Version: 0.4.0
 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>
@@ -9,9 +9,11 @@ License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
 Requires-Dist: pyyaml>=6
 Requires-Dist: jsonschema>=4
+Requires-Dist: cryptography>=42 ; extra == 'passkey'
 Requires-Python: >=3.11, <3.15
 Project-URL: Homepage, https://github.com/sessionkit/sessiontools
 Project-URL: Repository, https://github.com/sessionkit/sessiontools
+Provides-Extra: passkey
 Description-Content-Type: text/markdown
 
 # sessiontools
@@ -30,7 +32,7 @@ uv tool install sessiontools
 ```
 
 Python 3.11 to 3.14. Optional: [the Claude Code plugin][plugin] adds
-the `session` skill and four hooks.
+the `session` skill and five hooks.
 
 Shell completion, one line per shell ([shell completion][completion]).
 For zsh, in `~/.zshrc` after compinit:
@@ -60,12 +62,18 @@ eval "$(session completion bash)"
 - `session context --parts`: what filled it: boot, then growth by
   category.
 - `session ledger --short`: each file read and command run, by tokens.
+- `session commands SEAT --since 7d --count`: the programs a seat's
+  sessions ran in a week, by how often.
+- `session list --past SEAT`: every session recorded as SEAT on this
+  host, oldest first.
 - `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.
+- `session respawn`: the plan to restart this seat in its pane with the
+  line it was started with. `--go` acts.
 - `session default-model`: the model every new `claude` starts on, and
   whether a pin keeps it there. Off until you set `model.default`.
 - `session --help`: every verb.
@@ -134,8 +142,8 @@ it. Each line says what puts it there and what takes it away.
   - `~/.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`,
+    `~/.session/` keeps using its folders there until they are moved.
+  - `~/.sessionkit/tools/state/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
     settings name a variable that is set when the session starts. Each
@@ -149,30 +157,36 @@ it. Each line says what puts it there and what takes it away.
     `log.jsonl`, the first time `session default-model enforce` changes
     settings.json.
   - `~/.sessionkit/tools/accounts/`: `session account new` and `use`.
+  - `~/.sessionkit/tools/services/`, beside `settings/`: one file per
+    service, for `sessionkit service list`. `pane-state.json`:
+    `session pane-state agent on|off`. `sound-engine.json`: `session
+    sound engine on|off`. `default-model.json`: `session default-model
+    agent on|off`. `web.json`: `session web declare`, which installs
+    nothing. `off` rewrites a file with `enabled: false` and keeps it.
   - `~/.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.
+  - `~/.sessionkit/tools/log/`: the services' logs, `reap.log` and
+    `respawn.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`
   writes a plist in `~/Library/LaunchAgents/` and loads it, and it
   starts again at every login. Each `off` unloads it and deletes the
-  plist. Both `on` and `off` also retire a job an older release set up
-  under its old label: they unload it and delete its plist. `status`
-  names one that is still there, and `--dry-run` lists the retire and
-  changes nothing.
+  plist. For pane-state and the sound engine, `on` and `off` also
+  retire a job an older release set up under its old label: they unload
+  it and delete its plist. `status` names one that is still there, and
+  `--dry-run` lists the retire and changes nothing.
   - `dev.sessionkit.tools.sound-engine`: `session sound engine on`.
     `off --purge` also deletes the engine it built.
   - `dev.sessionkit.tools.pane-state`: `session pane-state agent on`.
     It sets `@session_state` and `@session_state_why` on each seat's
     tmux pane.
-  - `dev.sessionkit.tools.default-model`: no verb writes or loads it.
-    `session default-model unit launchd` prints it, and it is there only
-    if you save and load it yourself
+  - `dev.sessionkit.tools.default-model`: `session default-model agent
+    on`. Opt-in: nothing turns it on for you. `session default-model
+    unit launchd` prints the same plist for a hand install
     ([the default model][default-model]).
 - **Plugin and hooks, optional:** `claude plugin marketplace add` and
   `claude plugin install` ([the Claude Code plugin][plugin]). Claude
@@ -180,9 +194,10 @@ it. Each line says what puts it there and what takes it away.
   (`extraKnownMarketplaces`, `enabledPlugins`), lists them in
   `~/.claude/plugins/`, and keeps a copy in
   `~/.claude/plugins/cache/sessiontools/`. The plugin brings the
-  `session` skill and nine hook entries: SessionStart (two),
-  PreToolUse, PostToolBatch (three), Stop, UserPromptSubmit and
-  SessionEnd. Each is silent unless set.
+  `session` skill and twelve hook entries: SessionStart (three),
+  PreToolUse (two), PostToolBatch (three), PreCompact, Stop,
+  UserPromptSubmit and SessionEnd. Most are silent unless set; the sed
+  guard is on, and refuses only `sed -i ''` against GNU sed.
   Uninstalling the plugin takes it out of the settings and leaves the
   cached copy.
 - **Settings:** the install writes none, and none are needed.
@@ -255,6 +270,7 @@ 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
+- [Restarting a seat][respawn]: `session respawn`, a plan unless `--go`
 - [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
@@ -264,7 +280,13 @@ packages keep their files in it too.
 - [The Claude Code plugin][plugin]: the skill and the hooks
 - [The settle alert][settle]: one line past a context threshold
 - [The clock line][clock]: the time and the context on every tool batch
+- [The Markdown lint][md-lint]: wide table lines and `shape`, named
+  after a `.md` write
+- [The hidden-failure note][hidden-failure]: one line when an agent's test
+  run piped into `head` or `tail` exits 0 with failures shown
 - [The busy sound][busy]: a sound while a tool batch runs long
+- [The sed guard][sed-guard]: refuses `sed -i ''` where sed is GNU, and
+  names the GNU form
 - [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
@@ -296,8 +318,9 @@ be set, and where each one lives ([configuration][configuration]):
   which layers it is read from: [settings][settings].
 - **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
+  fresh host, one with no `~/.session/`, starts every leaf 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
@@ -306,15 +329,16 @@ be set, and where each one lives ([configuration][configuration]):
     `~/.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.
+    for `state` and `sound`, and for the rest the new one on a fresh host
+    and the old one on a host that has `~/.session/`.
   - **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_*`
+- **Environment variables:** `SESSION_SETTLE_AT`, which `session start`
+  copies once into the session layer, the hooks' `SESSIONTOOLS_HOOK_*`
   switches (`SESSIONTOOLS_HOOK_CLOCK=on` switches the clock line on), and
   the paths it reads, such as `SESSIONS_DIR` and `SESSION_STATE_DIR`.
   The configuration page lists each one with its default, under the part
@@ -333,6 +357,11 @@ be set, and where each one lives ([configuration][configuration]):
   the launchd agent `session default-model unit launchd` prints.
 - **`session reap --yes`:** `~/.sessionkit/tools/log/reap.log`, one line
   for each seat it closed or failed to close.
+- **Busy detection:** `~/.sessionkit/tools/log/busy.log`, one line each
+  time voice could not be asked where its mouth is, naming why and the
+  folder used instead ([the busy sound][busy]).
+- **`session respawn --go`:** `~/.sessionkit/tools/log/respawn.log`, one line
+  for each pane it respawned, written before the kill.
 - **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
@@ -357,31 +386,35 @@ Follow one as it grows with `tail -F`, for example
   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
-[cache]: docs/list-snapshot-cache.md
-[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
-[default-model]: docs/default-model.md
-[library]: docs/python-library-api.md
-[building]: docs/building-and-testing.md
-[dependencies]: docs/dependencies.md
-[changelog]: CHANGELOG.md
-[license]: LICENSE
-[configuration]: docs/configuration.md
-[settings]: docs/settings.md
+[verbs]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session.md
+[default-seat]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session.md#the-default-seat
+[start]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-start-launcher.md
+[credentials]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-start-launcher.md#credentials-are-never-handed-down
+[account]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/account.md
+[cache]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/list-snapshot-cache.md
+[operator]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/operator-privileged-seats.md
+[reap]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-reap.md
+[respawn]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-respawn.md
+[completion]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/shell-completion.md
+[state-paths]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/tools-state-paths.md
+[state-migrate]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/tools-state-migrate.md
+[plugin]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/claude-code-plugin.md
+[settle]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/settle-alert-hook.md
+[clock]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/clock-line-hook.md
+[md-lint]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/md-lint-hook.md
+[hidden-failure]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/hidden-failure-hook.md
+[busy]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/busy-sound-hook.md
+[sed-guard]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/sed-guard-hook.md
+[session-info]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-info-hook.md
+[identity]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/identity-block.md
+[engine]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/sound-engine-agent.md
+[status-line]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/status-line-script.md
+[pane-state]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/pane-state-signal.md
+[default-model]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/default-model.md
+[library]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/python-library-api.md
+[building]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/building-and-testing.md
+[dependencies]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/dependencies.md
+[changelog]: https://github.com/sessionkit/sessiontools/blob/HEAD/CHANGELOG.md
+[license]: https://github.com/sessionkit/sessiontools/blob/HEAD/LICENSE
+[configuration]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/configuration.md
+[settings]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/settings.md

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

@@ -14,7 +14,7 @@ uv tool install sessiontools
 ```
 
 Python 3.11 to 3.14. Optional: [the Claude Code plugin][plugin] adds
-the `session` skill and four hooks.
+the `session` skill and five hooks.
 
 Shell completion, one line per shell ([shell completion][completion]).
 For zsh, in `~/.zshrc` after compinit:
@@ -44,12 +44,18 @@ eval "$(session completion bash)"
 - `session context --parts`: what filled it: boot, then growth by
   category.
 - `session ledger --short`: each file read and command run, by tokens.
+- `session commands SEAT --since 7d --count`: the programs a seat's
+  sessions ran in a week, by how often.
+- `session list --past SEAT`: every session recorded as SEAT on this
+  host, oldest first.
 - `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.
+- `session respawn`: the plan to restart this seat in its pane with the
+  line it was started with. `--go` acts.
 - `session default-model`: the model every new `claude` starts on, and
   whether a pin keeps it there. Off until you set `model.default`.
 - `session --help`: every verb.
@@ -118,8 +124,8 @@ it. Each line says what puts it there and what takes it away.
   - `~/.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`,
+    `~/.session/` keeps using its folders there until they are moved.
+  - `~/.sessionkit/tools/state/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
     settings name a variable that is set when the session starts. Each
@@ -133,30 +139,36 @@ it. Each line says what puts it there and what takes it away.
     `log.jsonl`, the first time `session default-model enforce` changes
     settings.json.
   - `~/.sessionkit/tools/accounts/`: `session account new` and `use`.
+  - `~/.sessionkit/tools/services/`, beside `settings/`: one file per
+    service, for `sessionkit service list`. `pane-state.json`:
+    `session pane-state agent on|off`. `sound-engine.json`: `session
+    sound engine on|off`. `default-model.json`: `session default-model
+    agent on|off`. `web.json`: `session web declare`, which installs
+    nothing. `off` rewrites a file with `enabled: false` and keeps it.
   - `~/.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.
+  - `~/.sessionkit/tools/log/`: the services' logs, `reap.log` and
+    `respawn.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`
   writes a plist in `~/Library/LaunchAgents/` and loads it, and it
   starts again at every login. Each `off` unloads it and deletes the
-  plist. Both `on` and `off` also retire a job an older release set up
-  under its old label: they unload it and delete its plist. `status`
-  names one that is still there, and `--dry-run` lists the retire and
-  changes nothing.
+  plist. For pane-state and the sound engine, `on` and `off` also
+  retire a job an older release set up under its old label: they unload
+  it and delete its plist. `status` names one that is still there, and
+  `--dry-run` lists the retire and changes nothing.
   - `dev.sessionkit.tools.sound-engine`: `session sound engine on`.
     `off --purge` also deletes the engine it built.
   - `dev.sessionkit.tools.pane-state`: `session pane-state agent on`.
     It sets `@session_state` and `@session_state_why` on each seat's
     tmux pane.
-  - `dev.sessionkit.tools.default-model`: no verb writes or loads it.
-    `session default-model unit launchd` prints it, and it is there only
-    if you save and load it yourself
+  - `dev.sessionkit.tools.default-model`: `session default-model agent
+    on`. Opt-in: nothing turns it on for you. `session default-model
+    unit launchd` prints the same plist for a hand install
     ([the default model][default-model]).
 - **Plugin and hooks, optional:** `claude plugin marketplace add` and
   `claude plugin install` ([the Claude Code plugin][plugin]). Claude
@@ -164,9 +176,10 @@ it. Each line says what puts it there and what takes it away.
   (`extraKnownMarketplaces`, `enabledPlugins`), lists them in
   `~/.claude/plugins/`, and keeps a copy in
   `~/.claude/plugins/cache/sessiontools/`. The plugin brings the
-  `session` skill and nine hook entries: SessionStart (two),
-  PreToolUse, PostToolBatch (three), Stop, UserPromptSubmit and
-  SessionEnd. Each is silent unless set.
+  `session` skill and twelve hook entries: SessionStart (three),
+  PreToolUse (two), PostToolBatch (three), PreCompact, Stop,
+  UserPromptSubmit and SessionEnd. Most are silent unless set; the sed
+  guard is on, and refuses only `sed -i ''` against GNU sed.
   Uninstalling the plugin takes it out of the settings and leaves the
   cached copy.
 - **Settings:** the install writes none, and none are needed.
@@ -239,6 +252,7 @@ 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
+- [Restarting a seat][respawn]: `session respawn`, a plan unless `--go`
 - [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
@@ -248,7 +262,13 @@ packages keep their files in it too.
 - [The Claude Code plugin][plugin]: the skill and the hooks
 - [The settle alert][settle]: one line past a context threshold
 - [The clock line][clock]: the time and the context on every tool batch
+- [The Markdown lint][md-lint]: wide table lines and `shape`, named
+  after a `.md` write
+- [The hidden-failure note][hidden-failure]: one line when an agent's test
+  run piped into `head` or `tail` exits 0 with failures shown
 - [The busy sound][busy]: a sound while a tool batch runs long
+- [The sed guard][sed-guard]: refuses `sed -i ''` where sed is GNU, and
+  names the GNU form
 - [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
@@ -280,8 +300,9 @@ be set, and where each one lives ([configuration][configuration]):
   which layers it is read from: [settings][settings].
 - **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
+  fresh host, one with no `~/.session/`, starts every leaf 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
@@ -290,15 +311,16 @@ be set, and where each one lives ([configuration][configuration]):
     `~/.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.
+    for `state` and `sound`, and for the rest the new one on a fresh host
+    and the old one on a host that has `~/.session/`.
   - **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_*`
+- **Environment variables:** `SESSION_SETTLE_AT`, which `session start`
+  copies once into the session layer, the hooks' `SESSIONTOOLS_HOOK_*`
   switches (`SESSIONTOOLS_HOOK_CLOCK=on` switches the clock line on), and
   the paths it reads, such as `SESSIONS_DIR` and `SESSION_STATE_DIR`.
   The configuration page lists each one with its default, under the part
@@ -317,6 +339,11 @@ be set, and where each one lives ([configuration][configuration]):
   the launchd agent `session default-model unit launchd` prints.
 - **`session reap --yes`:** `~/.sessionkit/tools/log/reap.log`, one line
   for each seat it closed or failed to close.
+- **Busy detection:** `~/.sessionkit/tools/log/busy.log`, one line each
+  time voice could not be asked where its mouth is, naming why and the
+  folder used instead ([the busy sound][busy]).
+- **`session respawn --go`:** `~/.sessionkit/tools/log/respawn.log`, one line
+  for each pane it respawned, written before the kill.
 - **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
@@ -341,31 +368,35 @@ Follow one as it grows with `tail -F`, for example
   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
-[cache]: docs/list-snapshot-cache.md
-[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
-[default-model]: docs/default-model.md
-[library]: docs/python-library-api.md
-[building]: docs/building-and-testing.md
-[dependencies]: docs/dependencies.md
-[changelog]: CHANGELOG.md
-[license]: LICENSE
-[configuration]: docs/configuration.md
-[settings]: docs/settings.md
+[verbs]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session.md
+[default-seat]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session.md#the-default-seat
+[start]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-start-launcher.md
+[credentials]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-start-launcher.md#credentials-are-never-handed-down
+[account]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/account.md
+[cache]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/list-snapshot-cache.md
+[operator]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/operator-privileged-seats.md
+[reap]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-reap.md
+[respawn]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-respawn.md
+[completion]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/shell-completion.md
+[state-paths]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/tools-state-paths.md
+[state-migrate]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/tools-state-migrate.md
+[plugin]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/claude-code-plugin.md
+[settle]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/settle-alert-hook.md
+[clock]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/clock-line-hook.md
+[md-lint]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/md-lint-hook.md
+[hidden-failure]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/hidden-failure-hook.md
+[busy]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/busy-sound-hook.md
+[sed-guard]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/sed-guard-hook.md
+[session-info]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/session-info-hook.md
+[identity]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/identity-block.md
+[engine]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/sound-engine-agent.md
+[status-line]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/status-line-script.md
+[pane-state]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/pane-state-signal.md
+[default-model]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/default-model.md
+[library]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/python-library-api.md
+[building]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/building-and-testing.md
+[dependencies]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/dependencies.md
+[changelog]: https://github.com/sessionkit/sessiontools/blob/HEAD/CHANGELOG.md
+[license]: https://github.com/sessionkit/sessiontools/blob/HEAD/LICENSE
+[configuration]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/configuration.md
+[settings]: https://github.com/sessionkit/sessiontools/blob/HEAD/docs/settings.md

sessiontools-0.4.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "sessiontools"
+version = "0.4.0"
+description = "The harness layer: sessions, status and idle, one driver per harness - a library first"
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+license-files = ["LICENSE"]
+classifiers = ["Development Status :: 3 - Alpha"]
+requires-python = ">=3.11,<3.15"
+dependencies = [
+    "PyYAML>=6",
+    "jsonschema>=4",
+]
+
+[[project.authors]]
+name = "Mike Bailey"
+email = "mike@sessionkit.ai"
+
+[project.optional-dependencies]
+passkey = ["cryptography>=42"]
+
+[project.urls]
+Homepage = "https://github.com/sessionkit/sessiontools"
+Repository = "https://github.com/sessionkit/sessiontools"
+
+[project.scripts]
+session = "sessiontools.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.9,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+    "cryptography>=42",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--strict-markers"

sessiontools-0.3.2/pyproject.toml → sessiontools-0.4.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sessiontools"
-version = "0.3.2"
+version = "0.4.0"
 description = "The harness layer: sessions, status and idle, one driver per harness - a library first"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
@@ -34,6 +34,14 @@ dependencies = ["PyYAML>=6", "jsonschema>=4"]
 # aside: sessiontools provides it, same verbs, ported as package code.
 # Exactly one package owns `session` on the PATH; from here it is this one.
 # argparse and the library; PyYAML for `session start` alone (above).
+# The front door's passkey (`session web serve`, PROPOSED door-passkey):
+# WebAuthn verifies ECDSA and RSA signatures, which the standard library
+# cannot, so `cryptography` comes only with this extra and only
+# `sessiontools.web.passkey` imports it. Without it the front door is the
+# pairing code alone. Rule 3: an extra is the maintainer's call too.
+[project.optional-dependencies]
+passkey = ["cryptography>=42"]
+
 [project.urls]
 Homepage = "https://github.com/sessionkit/sessiontools"
 Repository = "https://github.com/sessionkit/sessiontools"
@@ -49,6 +57,8 @@ build-backend = "uv_build"
 dev = [
     "pytest>=8",
     "ruff>=0.6",
+    # the passkey extra's tests run its ceremonies with a software authenticator
+    "cryptography>=42",
 ]
 
 [tool.pytest.ini_options]

sessiontools-0.4.0/src/sessiontools/argv_flags.py

@@ -0,0 +1,32 @@
+"""Reading a vendor's flags back off an argv, by the vendor's own rule.
+
+claude parses a repeated scalar flag by keeping the LAST one, in either
+spelling: `--flag value` or `--flag=value`. Two readers need that rule:
+the settle hook (`compact_point`, reading a recorded launch line) and
+`session start` (`start.user_memory`, reading the argv it is about to
+render). One definition, here, so the two never disagree.
+
+Standard library only, and nothing imported at all: the settle hook
+imports `compact_point`, and so this, on every batch, maybe under a bare
+python3 (it must not pull in `sessiontools.start` or PyYAML).
+"""
+
+from __future__ import annotations
+
+
+def last_value(argv: list[str], flag: str) -> str | None:
+    """The value of the LAST `FLAG value` or `FLAG=value` in ARGV, or None.
+
+    The `=` is part of the prefix, so a longer flag that merely starts with
+    FLAG's spelling (`--settings-file` for `--settings`) is not FLAG. A
+    trailing FLAG with no value after it sets nothing."""
+    found = None
+    for index, token in enumerate(argv):
+        if token == flag and index + 1 < len(argv):
+            found = argv[index + 1]
+        elif token.startswith(flag + "="):
+            found = token[len(flag) + 1:]
+    return found
+
+
+__all__ = ["last_value"]