pocketshell 0.5.8__tar.gz → 0.5.9__tar.gz

pocketshell-0.5.9/.gitattributes

@@ -0,0 +1,2 @@
+tests/gateway/fixtures/task-object-authority.ps1 -text
+release/inputs/** -text

pocketshell-0.5.8/README.md → pocketshell-0.5.9/PKG-INFO

@@ -1,3 +1,40 @@
+Metadata-Version: 2.5
+Name: pocketshell
+Version: 0.5.9
+Summary: Unified server-side Python utility for the PocketShell Android and desktop clients.
+Project-URL: Homepage, https://github.com/PocketShell-io/pocketshell-cli
+Project-URL: Issues, https://github.com/PocketShell-io/pocketshell-cli/issues
+Author: Alexey Grigorev
+License: MIT
+License-File: LICENSE
+Keywords: agents,pocketshell,ssh,usage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: aplexer==0.1.8; sys_platform == 'linux'
+Requires-Dist: click>=8.2.0
+Requires-Dist: cryptography>=42
+Requires-Dist: google-auth>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: quse>=0.0.15
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.0; extra == 'dev'
+Provides-Extra: link
+Requires-Dist: websockets<17,>=15; extra == 'link'
+Provides-Extra: tray
+Requires-Dist: pillow>=10.0.0; extra == 'tray'
+Requires-Dist: pystray>=0.19.5; extra == 'tray'
+Description-Content-Type: text/markdown
+
 # pocketshell
 
 Unified server-side Python utility for the [PocketShell](https://github.com/PocketShell-io/pocketshell)
@@ -57,6 +94,8 @@ 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 sessions warnings [--json]     # unacknowledged crash/OOM warnings
+pocketshell sessions ack [NAME] [--json]     # acknowledge crash warnings
 pocketshell agent-log ...                   # agent conversation logs
 pocketshell repos list ...                  # local / GitHub repositories
 pocketshell github status [--json]          # gh install / auth state
@@ -65,6 +104,11 @@ pocketshell hooks ...                       # Claude/Codex/OpenCode hooks
 pocketshell logs ...                        # server-side trace sink
 pocketshell daemon ...                      # IPC daemon lifecycle
 pocketshell serve --dir PATH [--port N]     # foreground static HTTP server
+pocketshell gateway enroll|run|show         # gateway host agent (docs/gateway.md)
+pocketshell login [--label T] [--no-open]   # device-flow account login (docs/account.md)
+pocketshell whoami [--json]                 # show the logged-in account
+pocketshell logout                          # revoke and delete the CLI session
+pocketshell keys add|generate|list|public|remove|passwd  # device-password SSH key vault (docs/keys.md)
 ```
 
 Run `pocketshell --help` or `pocketshell <command> --help` for the live
@@ -84,6 +128,8 @@ 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
+pocketshell sessions warnings --json
+pocketshell sessions ack my-session
 ```
 
 The list and lifecycle responses use schema 3. Rows carry the aplexer id,
@@ -92,6 +138,13 @@ 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.
 
+Crash/OOM warnings are ack-gated: when aplexer records a session as
+OOM-killed, dead without an exit, or finalized with a fatal error, a durable
+warning rides every human `sessions list` (and `sessions warnings` lists them
+all) and survives until an explicit `sessions ack NAME` — or a bare
+`sessions ack` for everything. The JSON listing is untouched; the banner
+stays hidden on bundled aplexer builds without the warnings subcommand.
+
 ### `pocketshell usage`
 
 ```text
@@ -331,6 +384,15 @@ Android app (extraction: PocketShell-io/pocketshell#2643). The `version` in
    refuses to publish if `dist/` does not carry exactly the tagged version,
    and publishes to PyPI.
 3. Hosts pick it up with `uv tool upgrade pocketshell`.
+4. **Reinstall THIS box's own CLI and smoke-check it**
+   (`scripts/reinstall-box-cli.sh vX.Y.Z`). This machine is both the dev box
+   and the live server the phone connects to; a green publish does not touch
+   the `uv tool`-installed binary, so skipping this step ships a release the
+   phone cannot actually use (the 2026-09-10 `workspaces` outage — issue
+   #15). The script overrides the global 7-day `exclude-newer` cutoff (a
+   just-published version is invisible to it), forces the reinstall at the
+   tagged version, and fails unless `pocketshell --version` reports the tag
+   and `pocketshell workspaces list --host <h> --json` exits 0.
 
 CI (`.github/workflows/ci.yml`) runs the pytest suite plus the packaging and
 frozen-lock guards on every PR and every push to `main`. The first

pocketshell-0.5.8/PKG-INFO → pocketshell-0.5.9/README.md

@@ -1,34 +1,3 @@
-Metadata-Version: 2.5
-Name: pocketshell
-Version: 0.5.8
-Summary: Unified server-side Python utility for the PocketShell Android and desktop clients.
-Project-URL: Homepage, https://github.com/PocketShell-io/pocketshell-cli
-Project-URL: Issues, https://github.com/PocketShell-io/pocketshell-cli/issues
-Author: Alexey Grigorev
-License: MIT
-License-File: LICENSE
-Keywords: agents,pocketshell,ssh,usage
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Software Development
-Classifier: Topic :: System :: Monitoring
-Requires-Python: >=3.11
-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
-Provides-Extra: dev
-Requires-Dist: pytest>=8.4.0; extra == 'dev'
-Requires-Dist: ruff>=0.15.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
 # pocketshell
 
 Unified server-side Python utility for the [PocketShell](https://github.com/PocketShell-io/pocketshell)
@@ -88,6 +57,8 @@ 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 sessions warnings [--json]     # unacknowledged crash/OOM warnings
+pocketshell sessions ack [NAME] [--json]     # acknowledge crash warnings
 pocketshell agent-log ...                   # agent conversation logs
 pocketshell repos list ...                  # local / GitHub repositories
 pocketshell github status [--json]          # gh install / auth state
@@ -96,6 +67,11 @@ pocketshell hooks ...                       # Claude/Codex/OpenCode hooks
 pocketshell logs ...                        # server-side trace sink
 pocketshell daemon ...                      # IPC daemon lifecycle
 pocketshell serve --dir PATH [--port N]     # foreground static HTTP server
+pocketshell gateway enroll|run|show         # gateway host agent (docs/gateway.md)
+pocketshell login [--label T] [--no-open]   # device-flow account login (docs/account.md)
+pocketshell whoami [--json]                 # show the logged-in account
+pocketshell logout                          # revoke and delete the CLI session
+pocketshell keys add|generate|list|public|remove|passwd  # device-password SSH key vault (docs/keys.md)
 ```
 
 Run `pocketshell --help` or `pocketshell <command> --help` for the live
@@ -115,6 +91,8 @@ 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
+pocketshell sessions warnings --json
+pocketshell sessions ack my-session
 ```
 
 The list and lifecycle responses use schema 3. Rows carry the aplexer id,
@@ -123,6 +101,13 @@ 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.
 
+Crash/OOM warnings are ack-gated: when aplexer records a session as
+OOM-killed, dead without an exit, or finalized with a fatal error, a durable
+warning rides every human `sessions list` (and `sessions warnings` lists them
+all) and survives until an explicit `sessions ack NAME` — or a bare
+`sessions ack` for everything. The JSON listing is untouched; the banner
+stays hidden on bundled aplexer builds without the warnings subcommand.
+
 ### `pocketshell usage`
 
 ```text
@@ -362,6 +347,15 @@ Android app (extraction: PocketShell-io/pocketshell#2643). The `version` in
    refuses to publish if `dist/` does not carry exactly the tagged version,
    and publishes to PyPI.
 3. Hosts pick it up with `uv tool upgrade pocketshell`.
+4. **Reinstall THIS box's own CLI and smoke-check it**
+   (`scripts/reinstall-box-cli.sh vX.Y.Z`). This machine is both the dev box
+   and the live server the phone connects to; a green publish does not touch
+   the `uv tool`-installed binary, so skipping this step ships a release the
+   phone cannot actually use (the 2026-09-10 `workspaces` outage — issue
+   #15). The script overrides the global 7-day `exclude-newer` cutoff (a
+   just-published version is invisible to it), forces the reinstall at the
+   tagged version, and fails unless `pocketshell --version` reports the tag
+   and `pocketshell workspaces list --host <h> --json` exits 0.
 
 CI (`.github/workflows/ci.yml`) runs the pytest suite plus the packaging and
 frozen-lock guards on every PR and every push to `main`. The first

pocketshell-0.5.9/docs/account.md

@@ -0,0 +1,193 @@
+# Account login: `pocketshell login` / `logout` / `whoami`
+
+`pocketshell login` connects this machine to your PocketShell account with a
+device-authorization flow, like `gh auth login` or `aws sso login`. It's built
+for machines where pasting a token is awkward: an SSH session, a headless box,
+or a laptop with no browser session. Gateway commands such as
+`pocketshell gateway enroll` then get their short-lived broker token on their
+own, so you never handle a token yourself.
+
+```text
+pocketshell login [--label TEXT] [--no-open] [--force]
+pocketshell whoami [--json]
+pocketshell logout
+```
+
+## Logging in
+
+```console
+$ pocketshell login
+To log in, open:  https://app.pocketshell.io/device?code=BCDF-GHJK
+Confirm the code shown in the browser matches: BCDF-GHJK
+The page will ask you to type its last 4 characters before approving.
+Waiting for approval (Ctrl+C to cancel)...
+Logged in as you@example.com.
+```
+
+1. The CLI asks the broker for a pairing (`POST /auth/device/start`) and
+   labels it `user@hostname`, or the value of `--label` (at most 80 printable
+   characters). The approval page shows this label so you can tell which
+   machine is asking.
+2. It prints the code and the verification URL. If a browser is available
+   and you didn't pass `--no-open`, it also opens the pre-filled URL. The
+   code must have the form `XXXX-XXXX`, using only the letters
+   `BCDFGHJKLMNPQRSTVWXZ` and the digits `2`-`9`. `login` refuses any other
+   code and doesn't print it.
+3. Sign in on the page, check that the code and label match what the
+   terminal shows, type the code's last 4 characters when the page asks
+   (it asks even when you opened the pre-filled link), and approve.
+4. The CLI polls at the interval the broker asks for, and adds 5 seconds
+   whenever the broker answers `slow_down`. It stops with a clear message
+   when you deny the request or the code expires (10 minutes). Press Ctrl+C
+   to cancel cleanly (exit 130).
+5. The CLI checks the new session with `GET /cli/session` and then saves it.
+
+You can review and revoke your CLI sessions at
+<https://app.pocketshell.io/device/sessions>. `whoami` prints this link too.
+
+If you're already logged in with a session that hasn't expired, `login`
+refuses to replace it and exits 1. Run `pocketshell logout` first, or run
+`pocketshell login --force`. With `--force`, the old session is revoked
+once the new one is saved. You don't need `--force` to replace an expired
+session.
+
+## Commands that use the login
+
+The session token never leaves this machine except to talk to the broker
+that issued it. That broker's URL is stored with the session at login, and
+`whoami`, `logout` and every token mint use only that stored URL.
+`POCKETSHELL_BROKER_URL` is ignored for an existing session. If it is set to
+a different broker (by accident, or by a hostile `.envrc`), the command
+refuses to send the session anywhere and tells you to unset the variable or
+run `pocketshell login --force` for that broker. Other commands call
+`pocketshell.account.mint_gateway_token()` to exchange it for a broker JWT
+(`POST /cli/gateway/token`). That JWT is valid for at most 5 minutes and is
+the same token `POST /gateway/token` mints for the app. If the broker answers
+401, the commands report "run `pocketshell login`".
+
+## `whoami`
+
+`whoami` prints the account, the session label, the broker and the expiry,
+followed by the link where you can review or revoke sessions,
+<https://app.pocketshell.io/device/sessions>. It also checks the session with
+the broker. If the broker can't be reached, it
+shows the local copy and marks it `verified: no`, with a warning on stderr.
+`--json` prints:
+
+```json
+{"broker_url": "...", "email": "...", "expires_at": 1767225600,
+ "label": "you@laptop", "logged_in": true, "token_id": "...", "verified": true}
+```
+
+When you're not logged in, `whoami --json` prints `{"logged_in": false}` and
+exits 1. When `POCKETSHELL_BROKER_URL` points to a different broker than the
+one you logged in to, `whoami` doesn't contact any broker. It shows the local
+copy as `verified: no` and prints a warning.
+
+## `logout`
+
+`logout` revokes the session on the broker (`POST /cli/logout`, best effort)
+and deletes the credentials file. If the broker can't be reached, the file
+is still deleted, and a warning says how long the session stays valid on
+the server. The same happens when `POCKETSHELL_BROKER_URL` names a different
+broker: the session isn't sent there. A `401` from the broker means the
+session is already gone (revoked, expired, or idle for 14 days) and counts
+as logged out.
+
+The one exception is `429 rate_limited`: the broker throttles a network
+after too many failed bearer lookups, and the session was **not** revoked.
+`logout` then keeps the credentials file, exits 1 and asks you to run
+`pocketshell logout` again shortly, so the still-valid session doesn't end
+up orphaned on the server. Elsewhere a `429` on `/cli/session` or
+`/cli/gateway/token` is reported as "the broker is rate limiting requests,
+try again shortly" — never as "not logged in", and it never deletes the
+credentials file.
+
+## Credentials file
+
+`${XDG_CONFIG_HOME:-~/.config}/pocketshell/credentials.json`:
+
+```json
+{"version": 1, "broker_url": "...", "access_token": "psc_...", "token_id": "...",
+ "email": "...", "expires_at": 1767225600, "label": "you@laptop"}
+```
+
+- **Written atomically and private from the start.** The directory is created
+  with mode 0700, and an existing directory you own is tightened to 0700. The
+  file is written to a new temporary name opened with
+  `O_CREAT|O_EXCL|O_NOFOLLOW` and mode 0600, fsynced, and moved into place with
+  `os.replace`. The token is never on disk with wider permissions, even for a
+  moment. There's no chmod after the write.
+- **Checked before every read.** The file is ignored, and treated as "not
+  logged in" with a message explaining why, when it is a symlink or not a
+  regular file, isn't owned by you, can be read or written by your group or
+  other users, or sits in a directory that others can write to. The message
+  never includes the file's contents. A file that's only too permissive still
+  holds your own token, so `pocketshell logout` revokes it before deleting it.
+  For a symlink or a file someone else owns, `logout` just removes the entry
+  and doesn't contact the broker.
+
+SSH private keys are not part of the account. `pocketshell keys` keeps
+them in a separate device-password vault, `key-vault.json`, in the same
+directory and with the same file checks. That vault never leaves this
+device. See [keys.md](keys.md).
+
+## Network and trust
+
+- Only HTTPS, with TLS verification always on. Redirects aren't followed,
+  because they would replay the `Authorization` header somewhere else. Every
+  request has a timeout, and response bodies are capped at 64 KiB.
+- Environment proxies and CA overrides are ignored for every request that
+  carries a token (the session token here, the gateway JWT in
+  `pocketshell gateway`): `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY` (either
+  case) and `NO_PROXY` have no effect, and the trust store is the platform's
+  compiled-in default CA file/directory, not `SSL_CERT_FILE`/`SSL_CERT_DIR`.
+  If your network needs a proxy or a private CA to reach the broker, these
+  commands won't work there. If no CA bundle exists at the default location
+  (e.g. a python.org macOS build without "Install Certificates"), TLS
+  verification fails rather than falling back to the environment.
+- Beyond those variables and `POCKETSHELL_BROKER_URL` (see above), the
+  process environment is trusted. An `.envrc` or profile that can set
+  `PYTHONPATH`, `LD_PRELOAD` and the like can run code inside the CLI
+  process, which no CLI can defend against.
+- Responses must be strict JSON objects: valid UTF-8, no duplicate keys, no
+  NaN or Infinity. Every field the CLI uses is type-checked.
+- Requests never carry an `Origin` header (the broker refuses
+  browser-originated calls to the CLI endpoints).
+- Tokens and the device code go only in the `Authorization` header or the JSON
+  body. They never appear in a URL, argv, a child process's environment, logs,
+  exception messages, or a `repr`.
+- Anything the server sends that the CLI prints (user code, email, label,
+  error codes) has control, escape and invisible format characters removed
+  first.
+- `login` prints or opens a verification URL only when it is plain `https://`
+  on the trusted approval origin, `https://app.pocketshell.io`. If the broker
+  sends any other URL, `login` doesn't show or open it. It prints a warning,
+  shows `https://app.pocketshell.io/device` and the code instead, and keeps
+  waiting. A broker, including one an `.envrc` points to, can't send you to a
+  look-alike approval page.
+- The pre-filled link (`verification_uri_complete`) is printed or opened only
+  when it is exactly `<verification_uri>?code=<the printed code>`. Otherwise
+  `login` prints the plain verification URL and the code, so a broker can't
+  pre-fill a different code on the trusted page than the one your terminal
+  shows. The page also makes you type the code's last 4 characters, so
+  approving always means comparing it with the terminal.
+- The gateway token from `/cli/gateway/token` must look like a JWT (three
+  base64url segments with a JSON header). Its `expires_at` must fall within
+  300 seconds plus 5 minutes of clock skew from now.
+
+## Configuration
+
+| Variable | Meaning |
+| --- | --- |
+| `POCKETSHELL_BROKER_URL` | Broker base URL for `login` (default: the production broker). Must be `https://` with no credentials, query or fragment. An existing session always uses the broker stored with it, and the command refuses to run when this variable names a different one. |
+| `POCKETSHELL_DEV_WEB_ORIGIN` | Staging and development only: the trusted approval origin, as a bare `https://host[:port]`. It's honored only when `POCKETSHELL_BROKER_URL` is also set. |
+| `POCKETSHELL_BROKER_INSECURE_DEV=1` | Development and tests only: also allows `http://` when the host is loopback (`127.0.0.0/8`, `::1`, `localhost`). |
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success. `logout` also exits 0 when you weren't logged in. |
+| 1 | Error, or not logged in. The message goes to stderr as `error: ...`. |
+| 130 | `login` was cancelled with Ctrl+C. |

pocketshell-0.5.9/docs/architecture.md

@@ -0,0 +1,167 @@
+# PocketShell package architecture
+
+PocketShell is a host-side CLI. The source tree is organized around the
+feature boundary exposed to the client, not around the historical order in
+which individual issues added files.
+
+## Target tree
+
+```text
+src/pocketshell/
+├── __main__.py                  # python -m pocketshell
+├── cli.py                       # root Click composition and daemon lifecycle
+├── github.py                    # one-file `github status` integration
+├── serve.py                     # one-file foreground HTTP integration
+├── agents/                      # agent domain
+│   ├── kind.py                  # `pocketshell agents kind`
+│   ├── conversations/            # conversation-log discovery and handoff
+│   │   ├── cli.py               # `pocketshell agent-log`
+│   │   ├── handoff.py           # compact cross-agent handoff export
+│   │   ├── messages.py          # conversation message extraction
+│   │   ├── readers.py           # bounded JSONL reads
+│   │   ├── resolve.py           # provider log resolution
+│   │   └── roots.py             # provider storage roots
+│   └── launch/                  # launch application and execution support
+│       ├── cli.py               # `pocketshell agent`
+│       ├── command.py            # argv construction
+│       ├── environment.py        # launch environment policy
+│       ├── run.py                # process execution
+│       ├── spec.py               # aplexer launch specs
+│       └── trust.py              # provider trust preparation
+├── cards/                       # typed agent→app cards
+│   ├── types/                   # registry and concrete card behaviors
+│   │   ├── registry.py
+│   │   ├── checklist.py
+│   │   └── note.py
+│   └── push.py                  # card FCM notification adapter
+├── daemon/                      # Unix-socket JSON-RPC server/client
+├── engines/                     # engine registry and harness probes
+├── env/                         # .env/.envrc parsing and persistence
+├── hooks/                       # agent hook installation and event handlers
+│   └── providers/               # provider-specific configuration formats
+│       ├── claude.py
+│       └── codex.py
+├── logs/                        # normalized host-side event log
+├── profiles/                    # aplexer profile discovery/resolution
+├── attachments/                 # uploaded attachment domain
+│   ├── cli.py                   # `pocketshell prune-attachments`
+│   └── prune.py                 # TTL and size-cap policy
+├── push/                        # FCM transport and usage-reset pushes
+├── repos/                       # local/remote repository discovery
+├── runtime/                     # shared host-runtime primitives
+│   ├── aplexer.py               # bundled `a` backend adapter
+│   ├── console_scripts.py       # interpreter-anchored console-script dirs
+│   ├── cgroups.py               # cgroup/proc agent classifier
+│   ├── memcap.py                # session memory-cap policy
+│   └── sessions.py              # live-session wire model and probing
+├── sessions/                    # aplexer session lifecycle commands
+├── tree/                        # durable tree/workspace registry
+│   ├── workspaces/              # workspace membership subdomain
+│   │   ├── membership.py        # durable workspace records
+│   │   └── cli.py               # `pocketshell workspaces`
+│   └── ...                       # tree registry and reconciliation
+└── usage/                       # the complete usage boundary
+    ├── cli.py                   # live/cache/reset-events command modes
+    ├── quse.py                  # thin process boundary to quse
+    ├── capture/                 # cache, history, durability, quarantine
+    └── reset/                   # reset detection and event persistence
+```
+
+The remaining root modules are deliberately small integrations shared by more
+than one feature package. A new multi-file feature belongs in a package; a
+single-file external-tool adapter does not need a package solely to gain an
+`__init__.py`.
+
+## Ownership rules
+
+- `cli.py` only composes public command objects and owns daemon lifecycle
+  callbacks. Feature behavior stays in the feature package.
+- A feature package's `__init__.py` is its public compatibility surface. Code
+  inside the package imports implementation modules directly to avoid circular
+  imports through the public surface.
+- `runtime` owns host primitives shared by unrelated feature packages:
+  aplexer resolution, cgroup/proc classification, memory-cap policy, and live
+  session enumeration. It has no eager feature-package imports.
+- `sessions` owns aplexer lifecycle commands and delegates shared policy and
+  enumeration to `runtime`.
+- `agents` owns three related but separate domains: launch preparation and
+  execution under `launch/`, conversation discovery and handoff under
+  `conversations/`, and live process-kind detection in `kind.py`. The plural
+  `agents` command and singular `agent` command remain separate Click
+  commands.
+- `attachments` owns the uploaded-attachment domain. `cli.py` is only the
+  command surface; `prune.py` contains the deletion policy and filesystem
+  sweep.
+- `tree` owns the registry and reconciliation. Workspace membership is a
+  nested subdomain under `tree/workspaces/`; live session enumeration is
+  imported from `runtime`, never duplicated in the tree store.
+- `cards` owns card persistence and delivery. Concrete card behavior and its
+  registry live under `cards/types/`, while FCM notification construction
+  remains in `cards/push.py`; `push` owns usage-reset transport.
+- `hooks/providers` owns provider-specific configuration formats; installation
+  orchestration and generated handlers remain in the parent `hooks` package.
+- `usage` owns PocketShell-specific persistence and client integration:
+  capture history, reset-event detection, daemon caching, and push hooks.
+  Provider collection, provider schemas, and provider-specific formatting
+  belong to `quse`; PocketShell should not reimplement them.
+
+## Dependency direction
+
+```text
+root CLI
+  └── feature public surfaces
+        ├── feature implementation modules
+        ├── shared host adapters (runtime, daemon, filesystem stores)
+        └── external providers (quse, gh, FCM)
+```
+
+Implementation modules may depend downward on shared adapters, but shared
+adapters must not import Click command registration. Persistence code should
+be reusable by both a CLI command and a daemon handler. The daemon method
+table is an application-composition boundary and may import feature handlers;
+transport and protocol modules underneath it must stay reusable. Usage and
+push intentionally share capture paths and reset-event records, so that
+cross-domain dependency is documented rather than hidden behind re-exports.
+Tests should patch the module that owns the symbol being exercised rather than
+a re-exporting package.
+
+## Usage boundary with quse
+
+`quse` is the provider backend: it discovers credentials, calls provider APIs,
+normalizes provider records, and formats provider-owned output. PocketShell is
+the host integration: it optionally proxies through its daemon, converts
+successful live readings into the client wire format, persists captures,
+detects resets across captures, and sends best-effort notifications.
+
+When a transformation is provider/schema logic, it should be implemented and
+tested in `quse`; when it is PocketShell state or client transport logic, it
+stays in `pocketshell.usage`.
+
+## Aplexer boundary
+
+The checked-out aplexer implementation is the source of truth for the
+session runtime and for agent launch resolution. PocketShell must consume that
+authority rather than grow a parallel implementation.
+
+| Aplexer owns | PocketShell keeps |
+| --- | --- |
+| Engine/profile configuration and discovery (`a engines`, `a profiles`) | Picker-facing labels, usage-provider metadata, host availability probes, and the optional PocketShell presentation/config layer in `engines/` and `profiles/` |
+| Launch argv, profile environment, provider-key removal, cwd, and skip-permission arguments (`a launch-spec`) | Folder `.env`/`.envrc` exports, explicit profile-to-directory UX, Claude trust seeding, binary preflight, and the thin `launch-spec` adapter |
+| Session creation/claiming, worker and workload lifecycle, PTY/history/cgroup containment, `start`, `snapshot`, `status`, `attach`, `kill`, and `forget` | Schema-3 rows, display-name/target resolution, idempotent create policy, memory-cap policy, attach chrome suppression, JSON envelopes, and client-facing recovery diagnostics |
+| Query-time agent/profile detection for a recorded session | `agents.kind_for_panes`, which classifies arbitrary pane PIDs and therefore has a different input and client contract |
+
+The `runtime/aplexer.py` module is only the bundled-binary integrity and
+subprocess boundary. `runtime/sessions.py` is only a client-wire model and
+normalizer. Neither is a second session backend.
+
+The old host-side launch metadata hooks were removed because they were no-op
+compatibility shims after aplexer became the owner of session metadata. The
+old host-side dead-record reaper was removed for the same reason: `a start`
+owns workspace/tag reclamation, while `a kill` reports whether its own final
+record removal succeeded. PocketShell does not issue a second `forget --force`
+or inspect workload PIDs to reproduce those lifecycle decisions. The
+remaining native engine/profile launch code is intentionally fallback and
+presentation code for custom PocketShell configuration and hosts where the
+`a` launcher probe is disabled; it is not authoritative on the normal Linux
+path. Any future removal of that fallback must first migrate those custom
+configuration fields into aplexer.