sessiontools 0.3.3__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sessiontools
-Version: 0.3.3
+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>
@@ -32,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:
@@ -62,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.
@@ -151,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
@@ -182,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.
@@ -257,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
@@ -266,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
@@ -317,8 +337,8 @@ be set, and where each one lives ([configuration][configuration]):
   - **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
@@ -340,6 +360,8 @@ be set, and where each one lives ([configuration][configuration]):
 - **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
@@ -364,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.3 → 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.
@@ -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
@@ -299,8 +319,8 @@ be set, and where each one lives ([configuration][configuration]):
   - **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
@@ -322,6 +342,8 @@ be set, and where each one lives ([configuration][configuration]):
 - **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
@@ -346,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.3.3 → sessiontools-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sessiontools"
-version = "0.3.3"
+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"

{sessiontools-0.3.3 → sessiontools-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sessiontools"
-version = "0.3.3"
+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"

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"]

{sessiontools-0.3.3 → sessiontools-0.4.0}/src/sessiontools/band.py

@@ -1,8 +1,11 @@
 """`band`: how close a window is to its seat's settle threshold, as data
 ("thresholds belong to session, the sidebar only paints").
 
-- OVER: at or past the settle threshold (`sessiontools.settle.threshold`,
-  read-only: this module never writes or re-reads its variable itself).
+- OVER: at or past the settle threshold: the soft line's mark,
+  `settle.soft.at`, read through the settings cascade by
+  `settle_settings.read` (read-only: no OFF stamp is written here), so
+  `session context` and the sidebar agree with the alert. No soft line
+  on in any layer: no threshold.
 - NEAR: within NEAR percent under it: `used >= threshold * (1 - NEAR/100)`.
 - OK: below that.
 - None (JSON null): no threshold is set, or `used` is unknown.
@@ -10,15 +13,16 @@
 THE NEAR CUT IS A SETTING, read through the settings cascade
 (`sessiontools.settings`: template, host, agent, seat and session layers),
 under ONE key, NEAR_KEY, of the `session` tool. It is never read from the
-environment: the environment is not a layer (settle's own
-`SESSION_SETTLE_AT` read is the pattern a later version retires). Unset,
+environment: the environment is not a layer, for the threshold either
+(`SESSION_SETTLE_AT` reaches it only as `session start`'s birth copy into
+the session layer, `settle.soft.at`). Unset,
 unreadable or not a number from 0 to 100 is the default, DEFAULT_NEAR_PCT
 (any other default is a one-line change to it).
 
     <sessions>/<sid>/settings/session.json   {"context": {"near_pct": 10}}
 
-No schema is shipped for the key: the cascade reads a key without one, and
-nothing installs a `session` schema today.
+The `session` schema `session start` installs (`settle_settings`) names
+the settle keys only, not this one: the cascade reads a key without one.
 
 It sits at the top level, not in `context_parts`: importing any
 `context_parts` submodule runs that package's `__init__`, which imports the
@@ -64,16 +68,25 @@ def _lookup(merged: Mapping, dotted: str) -> Any:
     return node
 
 
+def _sid(sid: str | None, env: Mapping[str, str] | None) -> str | None:
+    """SID as the full id `settings.resolve_sid` makes of a short prefix,
+    as `session settings` does: `session_dir` is a literal join, and a
+    prefix would otherwise read no session, agent or seat layer and fall
+    back without a word. None stays None (template and host layers only).
+    An AMBIGUOUS prefix is refused there (SettingsError) and raised here."""
+    from sessiontools import settings
+    if not sid:
+        return None
+    sid, _note = settings.resolve_sid(sid, env)
+    return sid
+
+
 def setting(sid: str | None = None, env: Mapping[str, str] | None = None) -> Any:
     """NEAR_KEY's raw merged value for session SID (None: template and host
     layers only), or None when no layer sets it or a layer cannot be read.
 
-    SID may be a short prefix: `settings.resolve_sid` turns it into the full
-    id, as `session settings` does, since `session_dir` is a literal join
-    and a prefix would otherwise read no session, agent or seat layer and
-    fall back to the default without a word. An AMBIGUOUS prefix is refused
-    there (SettingsError) and reads as None here, so the default: never a
-    guess at which session was meant.
+    SID may be a short prefix (`_sid`). An AMBIGUOUS prefix reads as None
+    here, so the default: never a guess at which session was meant.
 
     `sources` + `merge`, as `busy.values` reads `sounds`: `resolve` would
     also check an installed schema, which imports jsonschema. The agent
@@ -82,8 +95,8 @@ def setting(sid: str | None = None, env: Mapping[str, str] | None = None) -> Any
     from sessiontools import settings
     try:
         agent = seat = None
+        sid = _sid(sid, env)
         if sid:
-            sid, _note = settings.resolve_sid(sid, env)
             agent, seat = settings.identity(sid, env)
         try:
             srcs = settings.sources(NEAR_TOOL, sid, agent, seat, env)
@@ -115,16 +128,25 @@ def band(used: float | None, threshold: float | None,
     return OK
 
 
-def threshold(env: Mapping[str, str] | None = None) -> int | None:
-    """The seat's settle threshold in tokens, as settle reads it (read-only)."""
-    import os
-
-    from sessiontools import settle
-    return settle.threshold(os.environ if env is None else env)
+def threshold(sid: str | None = None, env: Mapping[str, str] | None = None) -> int | None:
+    """Session SID's settle threshold in tokens: `settle.soft.at`, as the
+    alert reads it (`settle_settings.read`, every layer, live), or None
+    when no layer turns the soft line on, a layer cannot be read, or SID
+    is an ambiguous prefix (never a guess). SID may be a short prefix
+    (`_sid`); None reads the template and host layers only. Read-only:
+    `read`, not `resolve`, so the OFF stamp is the hook's alone."""
+    from sessiontools import settings, settle_settings
+    try:
+        sid = _sid(sid, env)
+    except (settings.SettingsError, OSError, ValueError):
+        return None
+    found = settle_settings.read(sid, env)
+    return None if found is None or found.soft is None else found.soft.at
 
 
 def band_for(used: float | None, sid: str | None = None,
              env: Mapping[str, str] | None = None) -> str | None:
     """The band of USED tokens for session SID (a full id or a unique
-    prefix): settle's threshold, and the near cut from the settings cascade."""
-    return band(used, threshold(env), near_pct(sid, env))
+    prefix): the soft line's mark and the near cut, both from the settings
+    cascade."""
+    return band(used, threshold(sid, env), near_pct(sid, env))