pocketshell 0.5.3__tar.gz → 0.5.4__tar.gz

{pocketshell-0.5.3 → pocketshell-0.5.4}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: pocketshell
-Version: 0.5.3
+Version: 0.5.4
 Summary: Unified server-side Python utility for the PocketShell Android client.
 Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
 Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues
 Author: Alexey Grigorev
 License: MIT
-Keywords: agents,pocketshell,ssh,tmux,usage
+Keywords: agents,pocketshell,ssh,usage
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -18,12 +18,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Classifier: Topic :: System :: Monitoring
 Requires-Python: >=3.11
-Requires-Dist: aplexer==0.1.4; sys_platform == 'linux'
+Requires-Dist: aplexer==0.1.5; sys_platform == 'linux'
 Requires-Dist: click>=8.2.0
 Requires-Dist: google-auth>=2.0.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: quse==0.0.15
-Requires-Dist: tmuxctl>=0.3.5
 Provides-Extra: dev
 Requires-Dist: pytest>=8.4.0; extra == 'dev'
 Requires-Dist: ruff>=0.15.0; extra == 'dev'
@@ -35,9 +34,25 @@ Description-Content-Type: text/markdown
 
 Unified server-side Python utility for the [PocketShell](https://github.com/alexeygrigorev/pocketshell)
 Android client. The app probes for this single helper on each remote
-host and uses its subcommands for usage, tmux session/job metadata,
-agent conversations, QR host setup, repository discovery, environment
-files, hooks, logs, and daemon lifecycle checks.
+host and uses its subcommands for usage, aplexer session lifecycle, agent
+conversations, QR host setup, repository discovery, environment files, hooks,
+logs, and daemon lifecycle checks.
+
+## Durable workspaces
+
+The Quiet workspace-first client uses the host-side workspace membership
+contract before it has any live session to enumerate:
+
+```text
+pocketshell workspaces list --host <host> --json
+pocketshell workspaces add <path> --host <host> --json
+pocketshell workspaces remove <path> --host <host> --json
+```
+
+Membership is stored in the existing private tree registry. Each entry has a
+canonical absolute `path` for identity and a separate `display_path` for the
+path spelling shown in the UI. Adding or removing the same path repeatedly is
+safe, and `list` retains empty workspaces.
 
 ## Install
 
@@ -82,9 +97,10 @@ Top-level commands in the current helper:
 
 ```text
 pocketshell usage [provider] [--json]       # provider quota / usage
-pocketshell send --pane %3 --token <id>     # acknowledged pane delivery
-pocketshell sessions list [--by activity]   # tmux session summaries
-pocketshell jobs ...                        # tmux recurring jobs
+pocketshell sessions list --json           # schema-3 aplexer session rows
+pocketshell sessions create NAME --json      # create or reuse a session
+pocketshell sessions attach NAME             # attach to a live session
+pocketshell sessions kill NAME --json        # stop and reap a session
 pocketshell agent-log ...                   # agent conversation logs
 pocketshell repos list ...                  # local / GitHub repositories
 pocketshell github status [--json]          # gh install / auth state
@@ -101,136 +117,25 @@ flag set. Some parity subcommands still proxy through the existing host
 tools internally so their output remains byte-identical to what the app
 already parses.
 
-### `pocketshell send`
+### `pocketshell sessions`
 
-Deliver a payload into an exact tmux pane, **exactly once per token**. The
-exit status IS the acknowledgement — the client no longer has to read the
-terminal screen and guess whether its prompt landed (issue #2122, epic
-#2121).
+The session group is deliberately aplexer-only. `list`, `create`, `attach`, and
+`kill` all use the bundled `a` executable resolved next to the installed
+PocketShell interpreter; a missing or unusable aplexer is reported as an error
+instead of an empty session list.
 
 ```bash
-printf 'summarise the diff' | pocketshell send --pane %3 --token <row-id> --enter
-pocketshell send --prune-older-than 30d
+pocketshell sessions list --json
+pocketshell sessions create my-session --cwd ~/git/project --mem none --json
+pocketshell sessions attach my-session
+pocketshell sessions kill my-session --json
 ```
 
-The payload is read from **stdin as raw bytes** and delivered byte-exact
-(`load-buffer -` → `paste-buffer -d -r`, never argv). This command does not
-add bracketed-paste markers: the client already frames its payload, and
-framing twice put the inner markers into the receiving program as literal
-text (issue #1854). Callers that want bracketed paste write the framed bytes
-to stdin.
-
-Exit codes are stable. Both renderings below — this table and `--help` — are
-generated from the one `EXIT_CODE_TABLE` the code exits with, so neither can
-drift from the other (issue #2153; regenerate with
-`tools/pocketshell/scripts/sync-readme-exit-codes.py`, pinned by a test in the
-`Python utility tests (pocketshell)` check):
-
-<!-- BEGIN GENERATED: send exit codes (source: EXIT_CODE_TABLE in pocketshell/send.py) -->
-
-| Exit | stdout reason | Meaning |
-| ---- | ------------- | ------- |
-| 0 | `delivered` \| `already-delivered` \| `pruned` | Success. 'delivered' = injected by THIS call and journaled. 'already-delivered' = the token was already journaled, nothing was injected. 'pruned' = --prune-older-than removed N records. |
-| 2 | `bad-usage` | Invalid or missing arguments. Nothing was injected or journaled. |
-| 3 | `pane-not-found` | The pane id does not exist on the tmux server, or it is dead. Nothing was injected; the token is NOT journaled and stays retryable. |
-| 4 | `tmux-failed` | tmux is missing, no server is running, or a tmux command returned a definitive failure. This call put NOTHING into the pane and recorded no delivery, and it left the journal exactly as it found it: a claim this call took is released, and a pre-existing unresolved record it overwrote under --resend-interrupted is restored byte-for-byte. A retry therefore cannot duplicate — but 'unchanged' is not 'absent': if the token was already journaled-unresolved it still is, and the next plain call answers 'send-interrupted' rather than injecting. |
-| 5 | `send-interrupted` \| `journal-corrupt` | Delivery is genuinely UNKNOWN and the token is left journaled-unresolved, so no plain call will ever inject it again. Two ways in. Either a PREVIOUS attempt died without an answer (or left an unreadable record) and its owning process is gone, in which case this call injected nothing; or THIS call got past the point of no return — tmux accepted the paste and then the Enter failed, or the delivery could not be journaled — in which case the payload may ALREADY be in the pane. Never auto-retry either reading. Re-run with --resend-interrupted only to accept a possible duplicate. |
-| 6 | `timeout` | A tmux invocation exceeded --timeout. If the timeout hit at or after the commit the token is left in the unknown state above and the payload may ALREADY be in the pane; a retry then reports 'send-interrupted' rather than injecting again. |
-| 7 | `journal-failed` | The durable token journal could not be read or written (permissions, disk). Nothing was injected — the journal is written BEFORE the pane is touched precisely so this failure is safe. |
-| 8 | `send-in-progress` | Another send for this token is STILL RUNNING (its process is alive on this host). Nothing was injected by this call and nothing is unknown: the outcome is owned by that call. Retry shortly to read the answer — it will be 'delivered'/'already-delivered' or, if that process dies, 'send-interrupted'. --resend-interrupted does not override this: there is no unknown to resolve while the owner is alive, and forcing one would duplicate the payload. |
-
-<!-- END GENERATED: send exit codes -->
-
-(`pruned` prints the record count after the reason word: `pruned <n>`.)
-
-**The paste is the point of no return, and that is the boundary between exit 4
-and exit 5** (issue #2136). A client that branches on this table to decide
-whether to auto-retry (#2124) needs one property, and it is exactly what exit 4
-now means:
-
-> **Exit 4 ⇒ this call put nothing into the pane, and left the journal exactly
-> as it found it.**
-
-Every exit-4 site satisfies it. Failures at the pane lookup or while filling
-the paste buffer happen before the journal is written at all — nothing injected,
-token unclaimed, cleanly retryable; this is the ordinary case. A definitive
-`paste-buffer` failure (tmux answered "no", or tmux became unexecutable before
-the paste) rolls this call's claim back: for a plain call that returns the token
-to absent, and under `--resend-interrupted` the *pre-existing* unresolved record
-is restored byte-for-byte rather than erased.
-
-Note what "unchanged" does **not** mean. It does not mean "absent": a token that
-was already journaled-unresolved still is, so the next plain call answers exit 5
-rather than injecting. A retry after exit 4 can therefore never duplicate, but
-it is not guaranteed to inject.
-
-**Exit 5 in detail** — it carries two different facts, and a client must treat
-both the same way (do not auto-retry; surface the choice):
-
-- A **previous** attempt for this token died without an answer, or left an
-  unreadable record, and its owning process is gone. This call injected nothing.
-- **This** call got past the paste. tmux accepted the payload, so it **is** in
-  the pane, and then either the `send-keys Enter` failed or the delivery could
-  not be journaled. The claim is deliberately kept — rolling it back is what
-  would let a plain retry paste the payload a second time.
-
-Both readings leave the token journaled-unresolved, so the invariant is the same
-for both: no plain call will ever inject it again, and `--resend-interrupted` is
-the explicit opt-in that accepts a possible duplicate.
-
-The `Enter` step has two failure shapes — tmux answers non-zero, or tmux stops
-being executable between the paste and the `send-keys` — and they leave
-byte-identical state. They report one outcome (exit 5). Until #2136 the second
-reported exit 4, which told a client the pane was untouched while the payload
-was sitting in it.
-
-stdout is machine-readable: the first whitespace-delimited token is one of
-the reasons above; human detail goes to stderr. Every retry path drains stdin
-before exiting, so a caller piping a payload never takes SIGPIPE on a
-successful acknowledgement. (Argument validation runs *before* stdin is read,
-deliberately: a caller with an open-but-idle stdin gets `bad-usage`
-immediately instead of blocking on a payload that will never arrive.)
-
-**Durability invariant: at-most-once, except on an explicit opt-in.** A token
-is never injected a second time unless the caller passes
-`--resend-interrupted` on the injecting call itself; no sequence of failures,
-kills, races or automatic housekeeping can turn an injected token back into a
-state a plain call will inject. The journal under
-`${XDG_STATE_HOME:-~/.local/state}/pocketshell/sends/` is two-phase — a
-`pending` record is written (atomically, fsync'd) immediately before the one
-command that can put bytes into the pane, then promoted to `delivered` once
-tmux answers. A definitive tmux failure rolls that claim back, so ordinary
-errors stay cleanly retryable; rolling back means undoing *this* call, so a
-record this call created is removed and a pre-existing unresolved record it
-overwrote is restored byte-for-byte rather than erased.
-
-An unresolved record is then read against its owner process: gone ⇒ a previous
-attempt died and delivery is genuinely unknown (exit 5, resolvable with
-`--resend-interrupted`, so the state is never absorbing); still running ⇒
-nothing is unknown and the outcome belongs to that call (exit 8, retryable).
-`--resend-interrupted` does not override a live owner — there is no unknown to
-resolve, and forcing one would simply duplicate the payload.
-
-The invariant's honest edges: a definitive non-zero from `paste-buffer` is
-taken as proof nothing reached the pane; the journal directory must survive
-(delete it and the memory is gone); `--prune-older-than` is an operator
-action that *can* clear unresolved records; and exit 8 is bounded by the owner
-process's **liveness**, not by the owner's `--timeout`. A suspended owner
-(reproduced with `SIGSTOP`) holds its token in `send-in-progress` for as long
-as it stays stopped, because the liveness probe asks whether the process still
-exists, not whether it is making progress, and `--timeout` bounds the tmux
-calls of the process that passed it rather than some other process's lifetime.
-This fails safe — the payload is never duplicated and the token never becomes
-absorbing once the owner dies — and a client cannot reach it through its own
-use, since it would have to suspend its own in-flight send. Nothing reaps a
-suspended owner.
-
-Records carry a timestamp and are pruned two ways: explicitly with
-`--prune-older-than <30d|12h|90m|3600s>`, and automatically on delivery at a
-**30-day default retention** (throttled to at most once every 6 h), so the
-directory cannot grow without bound even if pruning is never invoked. The
-automatic sweep only removes **resolved** records — ageing an unknown out of
-the journal would silently make the token injectable again.
+The list and lifecycle responses use schema 3. Rows carry the aplexer id,
+workspace, tag, phase, attachment state, and agent metadata; there is no
+backend discriminator or legacy session socket. Create is idempotent for the
+same workspace and tag. Kill stops the workload and reaps the aplexer record
+before returning its JSON result.
 
 ### `pocketshell usage`
 
@@ -247,7 +152,7 @@ absent/unavailable daemon or explicitly supported method skew falls through
 to the one-shot subprocess path. Timeout, malformed-response, and
 daemon-internal failures are surfaced instead of being retried locally.
 
-All daemon-backed wrappers (`usage`, `repos`, `tree`, `jobs`, `sessions`, and
+All daemon-backed wrappers (`usage`, `repos`, `tree`, `sessions`, and
 `agents kind`) use one typed fallback boundary. It emits the safe
 `pocketshell.daemon_call` event with `reason`, `method`, `phase`, RPC code, and
 available CLI/daemon versions. It never logs RPC parameters or command output.
@@ -496,9 +401,8 @@ uv sync --group dev
 uv run pytest
 ```
 
-The tests stub `pocketshell.usage.subprocess.run` (and the `quse`/`tmuxctl`
-binary resolvers) so they run in seconds without invoking any real binary or
-hitting a provider API.
+The tests stub subprocess boundaries and the bundled aplexer resolver so
+they run in seconds without invoking a real host session.
 
 ## Release flow
 

{pocketshell-0.5.3 → pocketshell-0.5.4}/README.md

@@ -2,9 +2,25 @@
 
 Unified server-side Python utility for the [PocketShell](https://github.com/alexeygrigorev/pocketshell)
 Android client. The app probes for this single helper on each remote
-host and uses its subcommands for usage, tmux session/job metadata,
-agent conversations, QR host setup, repository discovery, environment
-files, hooks, logs, and daemon lifecycle checks.
+host and uses its subcommands for usage, aplexer session lifecycle, agent
+conversations, QR host setup, repository discovery, environment files, hooks,
+logs, and daemon lifecycle checks.
+
+## Durable workspaces
+
+The Quiet workspace-first client uses the host-side workspace membership
+contract before it has any live session to enumerate:
+
+```text
+pocketshell workspaces list --host <host> --json
+pocketshell workspaces add <path> --host <host> --json
+pocketshell workspaces remove <path> --host <host> --json
+```
+
+Membership is stored in the existing private tree registry. Each entry has a
+canonical absolute `path` for identity and a separate `display_path` for the
+path spelling shown in the UI. Adding or removing the same path repeatedly is
+safe, and `list` retains empty workspaces.
 
 ## Install
 
@@ -49,9 +65,10 @@ Top-level commands in the current helper:
 
 ```text
 pocketshell usage [provider] [--json]       # provider quota / usage
-pocketshell send --pane %3 --token <id>     # acknowledged pane delivery
-pocketshell sessions list [--by activity]   # tmux session summaries
-pocketshell jobs ...                        # tmux recurring jobs
+pocketshell sessions list --json           # schema-3 aplexer session rows
+pocketshell sessions create NAME --json      # create or reuse a session
+pocketshell sessions attach NAME             # attach to a live session
+pocketshell sessions kill NAME --json        # stop and reap a session
 pocketshell agent-log ...                   # agent conversation logs
 pocketshell repos list ...                  # local / GitHub repositories
 pocketshell github status [--json]          # gh install / auth state
@@ -68,136 +85,25 @@ flag set. Some parity subcommands still proxy through the existing host
 tools internally so their output remains byte-identical to what the app
 already parses.
 
-### `pocketshell send`
+### `pocketshell sessions`
 
-Deliver a payload into an exact tmux pane, **exactly once per token**. The
-exit status IS the acknowledgement — the client no longer has to read the
-terminal screen and guess whether its prompt landed (issue #2122, epic
-#2121).
+The session group is deliberately aplexer-only. `list`, `create`, `attach`, and
+`kill` all use the bundled `a` executable resolved next to the installed
+PocketShell interpreter; a missing or unusable aplexer is reported as an error
+instead of an empty session list.
 
 ```bash
-printf 'summarise the diff' | pocketshell send --pane %3 --token <row-id> --enter
-pocketshell send --prune-older-than 30d
+pocketshell sessions list --json
+pocketshell sessions create my-session --cwd ~/git/project --mem none --json
+pocketshell sessions attach my-session
+pocketshell sessions kill my-session --json
 ```
 
-The payload is read from **stdin as raw bytes** and delivered byte-exact
-(`load-buffer -` → `paste-buffer -d -r`, never argv). This command does not
-add bracketed-paste markers: the client already frames its payload, and
-framing twice put the inner markers into the receiving program as literal
-text (issue #1854). Callers that want bracketed paste write the framed bytes
-to stdin.
-
-Exit codes are stable. Both renderings below — this table and `--help` — are
-generated from the one `EXIT_CODE_TABLE` the code exits with, so neither can
-drift from the other (issue #2153; regenerate with
-`tools/pocketshell/scripts/sync-readme-exit-codes.py`, pinned by a test in the
-`Python utility tests (pocketshell)` check):
-
-<!-- BEGIN GENERATED: send exit codes (source: EXIT_CODE_TABLE in pocketshell/send.py) -->
-
-| Exit | stdout reason | Meaning |
-| ---- | ------------- | ------- |
-| 0 | `delivered` \| `already-delivered` \| `pruned` | Success. 'delivered' = injected by THIS call and journaled. 'already-delivered' = the token was already journaled, nothing was injected. 'pruned' = --prune-older-than removed N records. |
-| 2 | `bad-usage` | Invalid or missing arguments. Nothing was injected or journaled. |
-| 3 | `pane-not-found` | The pane id does not exist on the tmux server, or it is dead. Nothing was injected; the token is NOT journaled and stays retryable. |
-| 4 | `tmux-failed` | tmux is missing, no server is running, or a tmux command returned a definitive failure. This call put NOTHING into the pane and recorded no delivery, and it left the journal exactly as it found it: a claim this call took is released, and a pre-existing unresolved record it overwrote under --resend-interrupted is restored byte-for-byte. A retry therefore cannot duplicate — but 'unchanged' is not 'absent': if the token was already journaled-unresolved it still is, and the next plain call answers 'send-interrupted' rather than injecting. |
-| 5 | `send-interrupted` \| `journal-corrupt` | Delivery is genuinely UNKNOWN and the token is left journaled-unresolved, so no plain call will ever inject it again. Two ways in. Either a PREVIOUS attempt died without an answer (or left an unreadable record) and its owning process is gone, in which case this call injected nothing; or THIS call got past the point of no return — tmux accepted the paste and then the Enter failed, or the delivery could not be journaled — in which case the payload may ALREADY be in the pane. Never auto-retry either reading. Re-run with --resend-interrupted only to accept a possible duplicate. |
-| 6 | `timeout` | A tmux invocation exceeded --timeout. If the timeout hit at or after the commit the token is left in the unknown state above and the payload may ALREADY be in the pane; a retry then reports 'send-interrupted' rather than injecting again. |
-| 7 | `journal-failed` | The durable token journal could not be read or written (permissions, disk). Nothing was injected — the journal is written BEFORE the pane is touched precisely so this failure is safe. |
-| 8 | `send-in-progress` | Another send for this token is STILL RUNNING (its process is alive on this host). Nothing was injected by this call and nothing is unknown: the outcome is owned by that call. Retry shortly to read the answer — it will be 'delivered'/'already-delivered' or, if that process dies, 'send-interrupted'. --resend-interrupted does not override this: there is no unknown to resolve while the owner is alive, and forcing one would duplicate the payload. |
-
-<!-- END GENERATED: send exit codes -->
-
-(`pruned` prints the record count after the reason word: `pruned <n>`.)
-
-**The paste is the point of no return, and that is the boundary between exit 4
-and exit 5** (issue #2136). A client that branches on this table to decide
-whether to auto-retry (#2124) needs one property, and it is exactly what exit 4
-now means:
-
-> **Exit 4 ⇒ this call put nothing into the pane, and left the journal exactly
-> as it found it.**
-
-Every exit-4 site satisfies it. Failures at the pane lookup or while filling
-the paste buffer happen before the journal is written at all — nothing injected,
-token unclaimed, cleanly retryable; this is the ordinary case. A definitive
-`paste-buffer` failure (tmux answered "no", or tmux became unexecutable before
-the paste) rolls this call's claim back: for a plain call that returns the token
-to absent, and under `--resend-interrupted` the *pre-existing* unresolved record
-is restored byte-for-byte rather than erased.
-
-Note what "unchanged" does **not** mean. It does not mean "absent": a token that
-was already journaled-unresolved still is, so the next plain call answers exit 5
-rather than injecting. A retry after exit 4 can therefore never duplicate, but
-it is not guaranteed to inject.
-
-**Exit 5 in detail** — it carries two different facts, and a client must treat
-both the same way (do not auto-retry; surface the choice):
-
-- A **previous** attempt for this token died without an answer, or left an
-  unreadable record, and its owning process is gone. This call injected nothing.
-- **This** call got past the paste. tmux accepted the payload, so it **is** in
-  the pane, and then either the `send-keys Enter` failed or the delivery could
-  not be journaled. The claim is deliberately kept — rolling it back is what
-  would let a plain retry paste the payload a second time.
-
-Both readings leave the token journaled-unresolved, so the invariant is the same
-for both: no plain call will ever inject it again, and `--resend-interrupted` is
-the explicit opt-in that accepts a possible duplicate.
-
-The `Enter` step has two failure shapes — tmux answers non-zero, or tmux stops
-being executable between the paste and the `send-keys` — and they leave
-byte-identical state. They report one outcome (exit 5). Until #2136 the second
-reported exit 4, which told a client the pane was untouched while the payload
-was sitting in it.
-
-stdout is machine-readable: the first whitespace-delimited token is one of
-the reasons above; human detail goes to stderr. Every retry path drains stdin
-before exiting, so a caller piping a payload never takes SIGPIPE on a
-successful acknowledgement. (Argument validation runs *before* stdin is read,
-deliberately: a caller with an open-but-idle stdin gets `bad-usage`
-immediately instead of blocking on a payload that will never arrive.)
-
-**Durability invariant: at-most-once, except on an explicit opt-in.** A token
-is never injected a second time unless the caller passes
-`--resend-interrupted` on the injecting call itself; no sequence of failures,
-kills, races or automatic housekeeping can turn an injected token back into a
-state a plain call will inject. The journal under
-`${XDG_STATE_HOME:-~/.local/state}/pocketshell/sends/` is two-phase — a
-`pending` record is written (atomically, fsync'd) immediately before the one
-command that can put bytes into the pane, then promoted to `delivered` once
-tmux answers. A definitive tmux failure rolls that claim back, so ordinary
-errors stay cleanly retryable; rolling back means undoing *this* call, so a
-record this call created is removed and a pre-existing unresolved record it
-overwrote is restored byte-for-byte rather than erased.
-
-An unresolved record is then read against its owner process: gone ⇒ a previous
-attempt died and delivery is genuinely unknown (exit 5, resolvable with
-`--resend-interrupted`, so the state is never absorbing); still running ⇒
-nothing is unknown and the outcome belongs to that call (exit 8, retryable).
-`--resend-interrupted` does not override a live owner — there is no unknown to
-resolve, and forcing one would simply duplicate the payload.
-
-The invariant's honest edges: a definitive non-zero from `paste-buffer` is
-taken as proof nothing reached the pane; the journal directory must survive
-(delete it and the memory is gone); `--prune-older-than` is an operator
-action that *can* clear unresolved records; and exit 8 is bounded by the owner
-process's **liveness**, not by the owner's `--timeout`. A suspended owner
-(reproduced with `SIGSTOP`) holds its token in `send-in-progress` for as long
-as it stays stopped, because the liveness probe asks whether the process still
-exists, not whether it is making progress, and `--timeout` bounds the tmux
-calls of the process that passed it rather than some other process's lifetime.
-This fails safe — the payload is never duplicated and the token never becomes
-absorbing once the owner dies — and a client cannot reach it through its own
-use, since it would have to suspend its own in-flight send. Nothing reaps a
-suspended owner.
-
-Records carry a timestamp and are pruned two ways: explicitly with
-`--prune-older-than <30d|12h|90m|3600s>`, and automatically on delivery at a
-**30-day default retention** (throttled to at most once every 6 h), so the
-directory cannot grow without bound even if pruning is never invoked. The
-automatic sweep only removes **resolved** records — ageing an unknown out of
-the journal would silently make the token injectable again.
+The list and lifecycle responses use schema 3. Rows carry the aplexer id,
+workspace, tag, phase, attachment state, and agent metadata; there is no
+backend discriminator or legacy session socket. Create is idempotent for the
+same workspace and tag. Kill stops the workload and reaps the aplexer record
+before returning its JSON result.
 
 ### `pocketshell usage`
 
@@ -214,7 +120,7 @@ absent/unavailable daemon or explicitly supported method skew falls through
 to the one-shot subprocess path. Timeout, malformed-response, and
 daemon-internal failures are surfaced instead of being retried locally.
 
-All daemon-backed wrappers (`usage`, `repos`, `tree`, `jobs`, `sessions`, and
+All daemon-backed wrappers (`usage`, `repos`, `tree`, `sessions`, and
 `agents kind`) use one typed fallback boundary. It emits the safe
 `pocketshell.daemon_call` event with `reason`, `method`, `phase`, RPC code, and
 available CLI/daemon versions. It never logs RPC parameters or command output.
@@ -463,9 +369,8 @@ uv sync --group dev
 uv run pytest
 ```
 
-The tests stub `pocketshell.usage.subprocess.run` (and the `quse`/`tmuxctl`
-binary resolvers) so they run in seconds without invoking any real binary or
-hitting a provider API.
+The tests stub subprocess boundaries and the bundled aplexer resolver so
+they run in seconds without invoking a real host session.
 
 ## Release flow
 

{pocketshell-0.5.3 → pocketshell-0.5.4}/pyproject.toml

@@ -14,13 +14,13 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces the stamped value matches the tag;
 # scripts/check-version-coupling.sh enforces the derivation itself is
 # single-sourced. See tools/pocketshell/README.md ("Version coupling").
-version = "0.5.3"
+version = "0.5.4"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"
 authors = [{ name = "Alexey Grigorev" }]
 license = { text = "MIT" }
-keywords = ["pocketshell", "ssh", "tmux", "agents", "usage"]
+keywords = ["pocketshell", "ssh", "agents", "usage"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Environment :: Console",
@@ -65,25 +65,8 @@ dependencies = [
     # human/agent-readable default output format (#714). The Android client
     # consumes the `--json` flag instead; the host-facing default is YAML.
     "pyyaml>=6.0",
-    # Session create/resume delegates to the `tmuxctl` binary (see
-    # `pocketshell/resume.py`: `tmuxctl create-detached` / `create-or-attach`),
-    # so installing pocketshell pulls a tmuxctl that has the server-cgroup fix.
-    # >=0.3.3 is required: earlier tmuxctl started the shared tmux server inside
-    # the SSH login's `session-*.scope`, so a logout (or a per-session OOM) tore
-    # down every session at once; 0.3.3 starts the server in its own
-    # login-independent unit under robust.slice (tmuxctl#4). 0.3.0 first shipped
-    # the `create-detached` verb this CLI calls.
-    # >=0.3.5 is required as of 2026-08-26: 0.3.4 still resolves/creates
-    # sessions on the legacy shared socket only. A pinned-old pocketshell host
-    # CLI running alongside a newer interactive `tmuxctl`/`t` checkout (which
-    # does per-session servers) raced session creation for the same name onto
-    # two different sockets, so the app/desktop and an interactive `t` session
-    # silently disagreed about which sessions existed. 0.3.5 ships tmuxctl's
-    # per-session-server migration so every caller resolves sessions the same
-    # way.
-    "tmuxctl>=0.3.5",
     # aplexer ships WITH the pocketshell CLI (issue #2543). `pocketshell
-    # sessions create --backend aplexer` needs BOTH the `a` CLI and its
+    # sessions create` needs BOTH the `a` CLI and its
     # `aplexer` worker binary (aplexer/src/lib.rs::worker_executable resolves
     # the worker as a sibling of current_exe); the published wheel bundles
     # both native binaries and exposes them as the `a` / `aplexer`
@@ -98,8 +81,12 @@ dependencies = [
     # so the pinned wheel is the ONLY aplexer this CLI can run. Bumping the
     # pin is a deliberate, reviewed change.
     #
-    # 0.1.4 is required for the session tree to say WHICH agent is running.
-    # Through 0.1.3 a snapshot row's only agent-ish field was `engine`, and
+    # 0.1.5 is required for PocketShell's plain attach path. `a attach
+    # --no-status` removes aplexer's status chrome and reserved row while
+    # forwarding raw input and every PTY resize, so the Android terminal gets
+    # the full screen without a second terminal UI. 0.1.4 is also required
+    # for the session tree to say WHICH agent is running. Through 0.1.3 a
+    # snapshot row's only agent-ish field was `engine`, and
     # `engine` cannot answer that question: every session PocketShell creates
     # is `engine: "shell"` with the agent launched by hand inside it, so a
     # tree full of claude/codex/opencode sessions is indistinguishable from a
@@ -112,7 +99,7 @@ dependencies = [
     # running) and never persisted, so it cannot go stale.
     #
     # `session_enum._aplexer_rows` reads that key straight onto
-    # `LiveSession.agent` and schema 2 emits it on every row. Against 0.1.3
+    # `LiveSession.agent` and schema 3 emits it on every row. Against 0.1.3
     # the key is simply absent and every row reports `agent: null` — the
     # listing still works, it just cannot name an agent, which is the whole
     # point of the bump. tests/test_aplexer_contract.py pins the behaviour
@@ -143,7 +130,7 @@ dependencies = [
     # session tree silently lost EVERY aplexer row. Worse, a record-less
     # directory that outlives the window (a killed/crashed `a start`) bricks
     # 0.1.2's registry permanently — including `a start` itself, which runs
-    # the same scan under the lock, so `sessions create --backend aplexer`
+    # the same scan under the lock, so `sessions create`
     # stops working until someone manually `rmdir`s it.
     # tests/test_aplexer_contract.py drives the bundled binary through both
     # production probes with exactly that on-disk shape; verified red on
@@ -159,7 +146,7 @@ dependencies = [
     #   * aplexer ee4b957 — profile `executable` override (argv[0]) for Codex
     #     variants. Without it, `[profiles.zcodex] engine="codex",
     #     executable="zcodex"` resolves argv[0] to `codex`, and `pocketshell
-    #     sessions create --backend aplexer --engine codex --profile zcodex`
+    #     sessions create --engine codex --profile zcodex`
     #     dies with "a: command is not executable or was not found in PATH:
     #     codex".
     #   * aplexer d13ecb2 — preserve the provider environment for plain
@@ -172,7 +159,7 @@ dependencies = [
     #
     # There is no separate release-time guard for the aplexer version itself
     # (scripts/check-pypi-version.sh only couples pocketshell's OWN version to
-    # the release tag and says nothing about quse or tmuxctl either), so the
+    # the release tag and says nothing about quse either), so the
     # exact pin + the committed uv.lock + that contract test are the
     # enforcement.
     #
@@ -180,16 +167,15 @@ dependencies = [
     # manylinux wheels only (x86_64 + aarch64) and NO sdist, so an unmarked
     # hard dependency would make `pip install pocketshell` unresolvable on
     # macOS/Windows. PocketShell hosts are Linux; a non-Linux host simply gets
-    # no bundled aplexer at all, so `sessions create --backend aplexer` there
-    # fails loud (there is no PATH fallback — D22) while tmux, the default
-    # backend, keeps working.
+    # no bundled aplexer at all, so `sessions create` there fails loud (there
+    # is no PATH fallback — D22).
     #
-    # Install-surface note (unchanged in 0.1.4): as of 0.1.2 the wheels moved
+    # Install-surface note (unchanged in 0.1.5): as of 0.1.2 the wheels moved
     # from manylinux_2_17 to manylinux_2_28, raising the minimum glibc from
     # 2.17 to 2.28. Linux hosts older than that (CentOS 7, Ubuntu 18.04) can
     # no longer install pocketshell at all now that aplexer is a hard
     # dependency. Flagged, not solved here — see docs/aplexer-integration.md.
-    "aplexer==0.1.4; sys_platform == 'linux'",
+    "aplexer==0.1.5; sys_platform == 'linux'",
 ]
 
 [project.scripts]
@@ -243,7 +229,7 @@ exclude = [
 required-version = "==0.10.11"
 # Keep the lockfile's reproducibility cutoff project-local. The host may have
 # a rolling global `exclude-newer` policy that predates deliberately pinned
-# releases (quse 0.0.15 and tmuxctl 0.3.5); this exact value is also the
+# release (quse 0.0.15); this exact value is also the
 # `uv.lock` options cutoff and must be used when checking this lock. Moved
 # past quse 0.0.15's 2026-08-28T12:09:07Z PyPI upload for issue #2293, then
 # past aplexer 0.1.2's 2026-09-05T22:38:08Z PyPI upload (its `aplexer-client`
@@ -255,7 +241,8 @@ required-version = "==0.10.11"
 # runtime dep landed at 00:32:04Z) for the session-tree regression fix above,
 # and now past aplexer 0.1.4's 2026-09-06T16:14:52Z PyPI upload (its
 # `aplexer-client` runtime dep landed at 16:14:48Z) for the `agent` field.
-exclude-newer = "2026-09-06T17:00:00Z"
+# 0.1.5 uploaded at 21:06:11Z (client at 21:06:06Z) for plain attach.
+exclude-newer = "2026-09-08T22:00:00Z"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{pocketshell-0.5.3 → pocketshell-0.5.4}/src/pocketshell/__init__.py

@@ -1,8 +1,7 @@
 """Unified server-side Python utility for the PocketShell Android client.
 
-This package replaces the separately-installed `quse` and `tmuxctl`
-utilities the PocketShell app used to probe for. The app now probes a
-single `pocketshell` binary, which exposes the `usage`, `jobs`,
+This package replaces the separately-installed `quse` utility the PocketShell
+app used to probe for. The app now probes a single `pocketshell` binary, which exposes the `usage`,
 `agent-log`, `sessions`, `repos`, `serve`, and daemon subcommands.
 
 See https://github.com/alexeygrigorev/pocketshell/issues/170.

{pocketshell-0.5.3 → pocketshell-0.5.4}/src/pocketshell/agent_card_push.py

@@ -156,7 +156,7 @@ def card_to_data(
     Keys (mirrors the app's ``AgentCardPushPayload`` contract):
 
     - ``type`` = ``agent_card``
-    - ``session`` = the tmux session the card belongs to (deep-link target)
+    - ``session`` = the session the card belongs to (deep-link target)
     - ``host`` = best-effort host hostname for host resolution (may be empty)
     - ``card_id`` = the card id
     - ``card_type`` = e.g. ``checklist``

{pocketshell-0.5.3 → pocketshell-0.5.4}/src/pocketshell/agent_log.py

@@ -31,7 +31,7 @@ Why direct file read instead of a subprocess delegation:
 
 - There is no upstream CLI for these reads. The Android app reads them
   itself via ``ssh exec 'tail -n N <path>'``. There is no ``quse``- or
-  ``tmuxctl``-shaped binary on the host to wrap; reimplementing the
+  host-side session binary on the host to wrap; reimplementing the
   ``tail -n N`` step in Python is the smallest reasonable parity layer.
 - The JSONL files are append-only, plain text, one event per line. The
   default read path emits raw lines verbatim. The ``handoff`` path only