pocketshell 0.4.44__tar.gz → 0.4.45__tar.gz

{pocketshell-0.4.44 → pocketshell-0.4.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pocketshell
-Version: 0.4.44
+Version: 0.4.45
 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
@@ -21,8 +21,8 @@ Requires-Python: >=3.11
 Requires-Dist: click>=8.2.0
 Requires-Dist: google-auth>=2.0.0
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: quse==0.0.11
-Requires-Dist: tmuxctl>=0.3.3
+Requires-Dist: quse==0.0.14
+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'
@@ -91,6 +91,7 @@ pocketshell env ...                         # .env / .envrc management
 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 qr-share ...                    # SSH host QR import payloads
 ```
 
@@ -118,42 +119,69 @@ 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, and `--help` documents them (rendered from the same
-table the code exits with, so they cannot drift):
+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` | Injected by this call and journaled. |
-| 0 | `already-delivered` | The token was already journaled; nothing injected. |
-| 0 | `pruned <n>` | `--prune-older-than` removed `n` records. |
-| 2 | `bad-usage` | Invalid/missing arguments. Nothing injected or journaled. |
-| 3 | `pane-not-found` | Pane missing or dead. Not journaled; stays retryable. |
-| 4 | `tmux-failed` | tmux missing / no server / a definitive tmux failure. This call never recorded a delivery. Usually the pane was never touched and the token is left unclaimed, but not always — see the note below before auto-retrying. |
-| 5 | `send-interrupted` or `journal-corrupt` | A previous attempt for this token died without an answer (its process is gone). Delivery is genuinely UNKNOWN and nothing was injected now. |
-| 6 | `timeout` | A tmux call exceeded `--timeout`. |
-| 7 | `journal-failed` | The journal could not be read/written. Nothing injected. |
-| 8 | `send-in-progress` | Another send for this token is STILL RUNNING. Nothing injected, nothing unknown — retry shortly to read that call's answer. |
-
-**Exit 4 in detail** — a client that branches on this table to decide whether
-to auto-retry (#2124) must not read `tmux-failed` as "clean slate". It
-guarantees only that this call never recorded a *delivery*. It does **not**
-guarantee the token is unjournaled, and in one narrow case it does not
-guarantee the pane is untouched:
-
-- Failure at the pane lookup, or while filling the paste buffer — both happen
-  before the journal is written at all: nothing injected, token unclaimed,
-  cleanly retryable. This is the ordinary case.
-- A definitive `paste-buffer` failure rolls this call's claim back. For a plain
-  call that returns the token to absent (cleanly retryable). Under
-  `--resend-interrupted` the *pre-existing* unresolved record is restored
-  byte-for-byte rather than erased, so the token stays journaled-unresolved and
-  the next plain call answers exit 5, not a fresh injection.
-- tmux disappearing between a successful paste and the `Enter`: the payload
-  **is** in the pane, the pending record is deliberately kept, and the next
-  plain call answers exit 5.
-
-A plain retry after exit 4 is therefore always *safe* — it re-reads the journal
-and answers exit 5 rather than duplicating — but it is not guaranteed to inject.
+| 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
@@ -213,8 +241,15 @@ pocketshell usage codex     # filter to a single provider
 
 The output shape is byte-identical to `quse [provider] [--json]`. When
 the IPC daemon is running, `usage --json` dispatches `usage.fetch` over
-the daemon socket and uses the daemon's short TTL cache; otherwise it
-falls through to the one-shot subprocess path.
+the daemon socket and uses the daemon's short TTL cache; otherwise an
+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
+`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.
 
 If `quse` is not installed, `pocketshell usage` exits with code 127 and
 prints an install hint to stderr.
@@ -304,6 +339,34 @@ unauthenticated the `hint` tells them to run `gh auth login`. The only
 network access is whatever `gh auth status` itself performs (a token-validity
 check); the command does NOT call the GitHub API.
 
+### `pocketshell serve`
+
+Serve a folder over HTTP for a client-owned SSH port forward:
+
+```bash
+pocketshell serve --dir /path/to/site
+pocketshell serve --dir /path/to/site --port 8080 --bind 127.0.0.1
+```
+
+The server binds `127.0.0.1` by default. Omitting `--port` (or passing
+`--port 0`) lets the OS select a free port; after binding, stdout contains
+exactly one stable JSON line with the selected port:
+
+```json
+{"port":43123}
+```
+
+The process stays in the foreground so the caller owns its lifetime: keep the
+SSH exec channel alive while the site is needed and terminate that process
+when the view closes or the connection is lost. There is no detached server
+registry or `--stop` command in this contract. HTTP access logs and errors go
+to stderr, keeping stdout parseable.
+
+Requests serve static files with stdlib MIME detection. A directory resolves
+to its `index.html` when present; paths are resolved before the containment
+check, so parent traversal and symlinks that leave the selected directory are
+rejected rather than served.
+
 ### `pocketshell qr-share`
 
 Builds a `pocketshell.ssh-import.v1` payload from an `~/.ssh/config`
@@ -443,39 +506,54 @@ maintainer cuts an Android release tag (`vX.Y.Z`), the
 [`Build`](../../.github/workflows/build.yml) workflow assembles the APK
 and **also** builds the Python sdist + wheel and publishes them to PyPI.
 
-### Version coupling
-
-Two files must agree on the release version:
-
-- `app/build.gradle.kts` -> `versionName = "X.Y.Z"`
-- `tools/pocketshell/pyproject.toml` -> `version = "X.Y.Z"`
-
+### Version coupling (tag-derived, issue #2356)
+
+Neither side is a hand-maintained literal any more. Both derive from the git
+tag being built, via the single shared script
+[`scripts/derive-version.sh`](../../scripts/derive-version.sh):
+
+- `app/build.gradle.kts` computes `versionCode`/`versionName` at Gradle
+  configuration time by shelling out to `scripts/derive-version.sh`.
+- `tools/pocketshell/pyproject.toml`'s committed `version` field is a
+  placeholder. The release workflow's "Stamp pyproject.toml version from
+  tag" step overwrites it (in the ephemeral CI checkout, never committed)
+  from `scripts/derive-version.sh version-name --ref <tag>` immediately
+  before building the sdist/wheel.
+
+[`scripts/check-version-coupling.sh`](../../scripts/check-version-coupling.sh)
+verifies the derivation script is the SOLE source of truth (its own
+self-test, Gradle's resolved version matching a direct script invocation,
+and both consumers referencing the script by path rather than an
+independent reimplementation) — it runs per-push in `tests.yml`.
 [`scripts/check-pypi-version.sh`](../../scripts/check-pypi-version.sh)
-enforces this. The release workflow runs it with `--check-tag vX.Y.Z`
-before publishing, so a tag pushed with mismatched versions fails the
-job loudly before anything reaches PyPI.
-
-Run it locally before tagging:
+verifies, at tag-publish time, that the freshly-stamped
+`pyproject.toml` version equals what `scripts/derive-version.sh` derives
+for the tag being published:
 
 ```bash
-scripts/check-pypi-version.sh                  # local match check
 scripts/check-pypi-version.sh --check-tag vX.Y.Z
 ```
 
-### Bumping a release
+### Cutting a release
+
+There is no version-bump commit or PR. The tag itself is the version
+declaration:
 
 1. Pick the next semantic version after the latest GitHub Release/tag.
-2. Update **both** version sources in the same commit:
-   - `app/build.gradle.kts` -> bump `versionName` (and `versionCode`).
-   - `tools/pocketshell/pyproject.toml` -> bump `version` to the
-     same value as `versionName`.
-3. Run `scripts/check-pypi-version.sh` to confirm they match.
-4. Commit the bump on `main`, push, and run the emulator release
-   validation gate (`scripts/release-emulator-validation.sh`) as
-   described in [`process.md`](../../process.md) -> "Release Builds".
-5. Push the tag with `scripts/push-release-tag.sh`. The tag-triggered
+2. Run the emulator release validation gate
+   (`scripts/release-emulator-validation.sh`) against the current `main`
+   HEAD, as described in [`process.md`](../../process.md) -> "Release
+   Builds".
+3. Push the tag with `scripts/push-release-tag.sh vX.Y.Z ...`. It creates
+   the tag locally FIRST and verifies `scripts/derive-version.sh` derives
+   the expected `versionName` (and a strictly-monotonic `versionCode`
+   versus the previous tag) from it before pushing — so a derivation bug
+   is caught before the tag ever reaches `origin`. The tag-triggered
    `Build` workflow then:
-   - builds and uploads the APK + creates the GitHub Release
+   - builds and uploads the APK (its `versionCode`/`versionName` come from
+     the tag via `app/build.gradle.kts`'s own derivation) + creates the
+     GitHub Release
+   - stamps `tools/pocketshell/pyproject.toml`'s version from the tag
    - runs `scripts/check-pypi-version.sh --check-tag vX.Y.Z`
    - builds the Python sdist + wheel
    - publishes them to PyPI via OIDC trusted publishing

{pocketshell-0.4.44 → pocketshell-0.4.45}/README.md

@@ -59,6 +59,7 @@ pocketshell env ...                         # .env / .envrc management
 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 qr-share ...                    # SSH host QR import payloads
 ```
 
@@ -86,42 +87,69 @@ 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, and `--help` documents them (rendered from the same
-table the code exits with, so they cannot drift):
+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` | Injected by this call and journaled. |
-| 0 | `already-delivered` | The token was already journaled; nothing injected. |
-| 0 | `pruned <n>` | `--prune-older-than` removed `n` records. |
-| 2 | `bad-usage` | Invalid/missing arguments. Nothing injected or journaled. |
-| 3 | `pane-not-found` | Pane missing or dead. Not journaled; stays retryable. |
-| 4 | `tmux-failed` | tmux missing / no server / a definitive tmux failure. This call never recorded a delivery. Usually the pane was never touched and the token is left unclaimed, but not always — see the note below before auto-retrying. |
-| 5 | `send-interrupted` or `journal-corrupt` | A previous attempt for this token died without an answer (its process is gone). Delivery is genuinely UNKNOWN and nothing was injected now. |
-| 6 | `timeout` | A tmux call exceeded `--timeout`. |
-| 7 | `journal-failed` | The journal could not be read/written. Nothing injected. |
-| 8 | `send-in-progress` | Another send for this token is STILL RUNNING. Nothing injected, nothing unknown — retry shortly to read that call's answer. |
-
-**Exit 4 in detail** — a client that branches on this table to decide whether
-to auto-retry (#2124) must not read `tmux-failed` as "clean slate". It
-guarantees only that this call never recorded a *delivery*. It does **not**
-guarantee the token is unjournaled, and in one narrow case it does not
-guarantee the pane is untouched:
-
-- Failure at the pane lookup, or while filling the paste buffer — both happen
-  before the journal is written at all: nothing injected, token unclaimed,
-  cleanly retryable. This is the ordinary case.
-- A definitive `paste-buffer` failure rolls this call's claim back. For a plain
-  call that returns the token to absent (cleanly retryable). Under
-  `--resend-interrupted` the *pre-existing* unresolved record is restored
-  byte-for-byte rather than erased, so the token stays journaled-unresolved and
-  the next plain call answers exit 5, not a fresh injection.
-- tmux disappearing between a successful paste and the `Enter`: the payload
-  **is** in the pane, the pending record is deliberately kept, and the next
-  plain call answers exit 5.
-
-A plain retry after exit 4 is therefore always *safe* — it re-reads the journal
-and answers exit 5 rather than duplicating — but it is not guaranteed to inject.
+| 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
@@ -181,8 +209,15 @@ pocketshell usage codex     # filter to a single provider
 
 The output shape is byte-identical to `quse [provider] [--json]`. When
 the IPC daemon is running, `usage --json` dispatches `usage.fetch` over
-the daemon socket and uses the daemon's short TTL cache; otherwise it
-falls through to the one-shot subprocess path.
+the daemon socket and uses the daemon's short TTL cache; otherwise an
+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
+`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.
 
 If `quse` is not installed, `pocketshell usage` exits with code 127 and
 prints an install hint to stderr.
@@ -272,6 +307,34 @@ unauthenticated the `hint` tells them to run `gh auth login`. The only
 network access is whatever `gh auth status` itself performs (a token-validity
 check); the command does NOT call the GitHub API.
 
+### `pocketshell serve`
+
+Serve a folder over HTTP for a client-owned SSH port forward:
+
+```bash
+pocketshell serve --dir /path/to/site
+pocketshell serve --dir /path/to/site --port 8080 --bind 127.0.0.1
+```
+
+The server binds `127.0.0.1` by default. Omitting `--port` (or passing
+`--port 0`) lets the OS select a free port; after binding, stdout contains
+exactly one stable JSON line with the selected port:
+
+```json
+{"port":43123}
+```
+
+The process stays in the foreground so the caller owns its lifetime: keep the
+SSH exec channel alive while the site is needed and terminate that process
+when the view closes or the connection is lost. There is no detached server
+registry or `--stop` command in this contract. HTTP access logs and errors go
+to stderr, keeping stdout parseable.
+
+Requests serve static files with stdlib MIME detection. A directory resolves
+to its `index.html` when present; paths are resolved before the containment
+check, so parent traversal and symlinks that leave the selected directory are
+rejected rather than served.
+
 ### `pocketshell qr-share`
 
 Builds a `pocketshell.ssh-import.v1` payload from an `~/.ssh/config`
@@ -411,39 +474,54 @@ maintainer cuts an Android release tag (`vX.Y.Z`), the
 [`Build`](../../.github/workflows/build.yml) workflow assembles the APK
 and **also** builds the Python sdist + wheel and publishes them to PyPI.
 
-### Version coupling
-
-Two files must agree on the release version:
-
-- `app/build.gradle.kts` -> `versionName = "X.Y.Z"`
-- `tools/pocketshell/pyproject.toml` -> `version = "X.Y.Z"`
-
+### Version coupling (tag-derived, issue #2356)
+
+Neither side is a hand-maintained literal any more. Both derive from the git
+tag being built, via the single shared script
+[`scripts/derive-version.sh`](../../scripts/derive-version.sh):
+
+- `app/build.gradle.kts` computes `versionCode`/`versionName` at Gradle
+  configuration time by shelling out to `scripts/derive-version.sh`.
+- `tools/pocketshell/pyproject.toml`'s committed `version` field is a
+  placeholder. The release workflow's "Stamp pyproject.toml version from
+  tag" step overwrites it (in the ephemeral CI checkout, never committed)
+  from `scripts/derive-version.sh version-name --ref <tag>` immediately
+  before building the sdist/wheel.
+
+[`scripts/check-version-coupling.sh`](../../scripts/check-version-coupling.sh)
+verifies the derivation script is the SOLE source of truth (its own
+self-test, Gradle's resolved version matching a direct script invocation,
+and both consumers referencing the script by path rather than an
+independent reimplementation) — it runs per-push in `tests.yml`.
 [`scripts/check-pypi-version.sh`](../../scripts/check-pypi-version.sh)
-enforces this. The release workflow runs it with `--check-tag vX.Y.Z`
-before publishing, so a tag pushed with mismatched versions fails the
-job loudly before anything reaches PyPI.
-
-Run it locally before tagging:
+verifies, at tag-publish time, that the freshly-stamped
+`pyproject.toml` version equals what `scripts/derive-version.sh` derives
+for the tag being published:
 
 ```bash
-scripts/check-pypi-version.sh                  # local match check
 scripts/check-pypi-version.sh --check-tag vX.Y.Z
 ```
 
-### Bumping a release
+### Cutting a release
+
+There is no version-bump commit or PR. The tag itself is the version
+declaration:
 
 1. Pick the next semantic version after the latest GitHub Release/tag.
-2. Update **both** version sources in the same commit:
-   - `app/build.gradle.kts` -> bump `versionName` (and `versionCode`).
-   - `tools/pocketshell/pyproject.toml` -> bump `version` to the
-     same value as `versionName`.
-3. Run `scripts/check-pypi-version.sh` to confirm they match.
-4. Commit the bump on `main`, push, and run the emulator release
-   validation gate (`scripts/release-emulator-validation.sh`) as
-   described in [`process.md`](../../process.md) -> "Release Builds".
-5. Push the tag with `scripts/push-release-tag.sh`. The tag-triggered
+2. Run the emulator release validation gate
+   (`scripts/release-emulator-validation.sh`) against the current `main`
+   HEAD, as described in [`process.md`](../../process.md) -> "Release
+   Builds".
+3. Push the tag with `scripts/push-release-tag.sh vX.Y.Z ...`. It creates
+   the tag locally FIRST and verifies `scripts/derive-version.sh` derives
+   the expected `versionName` (and a strictly-monotonic `versionCode`
+   versus the previous tag) from it before pushing — so a derivation bug
+   is caught before the tag ever reaches `origin`. The tag-triggered
    `Build` workflow then:
-   - builds and uploads the APK + creates the GitHub Release
+   - builds and uploads the APK (its `versionCode`/`versionName` come from
+     the tag via `app/build.gradle.kts`'s own derivation) + creates the
+     GitHub Release
+   - stamps `tools/pocketshell/pyproject.toml`'s version from the tag
    - runs `scripts/check-pypi-version.sh --check-tag vX.Y.Z`
    - builds the Python sdist + wheel
    - publishes them to PyPI via OIDC trusted publishing

{pocketshell-0.4.44 → pocketshell-0.4.45}/pyproject.toml

@@ -4,11 +4,17 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pocketshell"
-# Must equal `versionName` in app/build.gradle.kts on every release tag.
-# scripts/check-pypi-version.sh enforces this; .github/workflows/build.yml
-# runs that check before publishing to PyPI. See
-# tools/pocketshell/README.md ("Release flow") for the bump procedure.
-version = "0.4.44"
+# PLACEHOLDER (issue #2356, Phase 4 of epic #2350): this value is NEVER read
+# for a real release. The publish-pypi job in .github/workflows/build.yml
+# overwrites this field (in its ephemeral CI checkout only, never committed)
+# from `scripts/derive-version.sh version-name --ref <tag>` — the SAME
+# derivation app/build.gradle.kts uses for the Android versionName — right
+# before building the sdist/wheel, so both sides derive from the git tag
+# being released and can never independently drift.
+# 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.4.45"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -36,17 +42,17 @@ dependencies = [
     "click>=8.2.0",
     # Usage backend + single source of truth for the unified provider schema
     # (issue #1318). Pinned exactly: `pocketshell usage --json` expects quse's
-    # provider-keyed `--json` document (per provider: status +
-    # short_term/long_term {percent_remaining, reset_at, window} + error) and
-    # fails loudly on any schema drift, so the version is frozen, not a range.
-    # 0.0.11 (#1564): quse labels each Codex window from its actual
-    # `limit_window_seconds` instead of assuming primary==5h / secondary==7d,
-    # and omits a window Codex drops (`present: false`) as a null placeholder
-    # rather than a phantom "0% / unavailable" ghost row. Codex temporarily
-    # removed the 5h window, so its `primary_window` now carries the WEEKLY
-    # (604800s) span — the old positional labels mislabeled weekly data as a
-    # "5h window" with a 5-day reset and left a "7d" ghost.
-    "quse==0.0.11",
+    # provider-keyed `--json` document and fails loudly on schema drift, so the
+    # version is frozen, not a range. The published 0.0.14 wheel is the
+    # five-provider legacy shape with `short_term` / `long_term` records. The
+    # host boundary translates those records into canonical `windows`; it also
+    # accepts a separate top-level `windows` producer contract for newer or
+    # custom producers, without treating that shape as PyPI 0.0.14 provenance.
+    # Canonical-only providers such as OpenCode Go belong to that separate
+    # contract, not to the published-wheel provider list. 0.0.13 (#2195)
+    # historically added the `grok` provider; 0.0.11 (#1564) labeled each
+    # Codex window from its actual `limit_window_seconds`.
+    "quse==0.0.14",
     # FCM HTTP v1 push delivery (#690): service-account OAuth2 bearer minting
     # for `pocketshell push` / the `usage --capture` reset-push send. Imported
     # lazily and fail-soft — a host without it (or without a Firebase
@@ -64,7 +70,15 @@ dependencies = [
     # 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.
-    "tmuxctl>=0.3.3",
+    # >=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",
 ]
 
 [project.scripts]
@@ -111,6 +125,13 @@ exclude = [
     "/dist",
 ]
 
+[tool.uv]
+# 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.14 and tmuxctl 0.3.5); this exact value is also the
+# `uv.lock` options cutoff and must be used when checking this lock.
+exclude-newer = "2026-08-27T22:00:00Z"
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]