sayfirst-cli 0.3.0__tar.gz → 0.3.2__tar.gz

{sayfirst_cli-0.3.0 → sayfirst_cli-0.3.2}/CHANGELOG.md

@@ -6,6 +6,32 @@ declares; a release with no section fails the gate.
 
 ## Unreleased
 
+## 0.3.2
+
+- The contract and the boundary move to 0.3.2, which carries security fixes.
+  Under `sayfirst instrument run`, an act a person approved now runs once;
+  asked again, it waits under a new approval.
+- The pages say that an allow produced by an approval carries no grant.
+
+## 0.3.1
+
+- **`instrument verify` says how a run ended when the program raised, too.** The harness said
+  its own ending only for a program that returned, so a program that ended on an exception before
+  a line of it was seen — a script that does not compile, a module whose bytecode another Python
+  wrote — left no ending behind, and the command answered `4` and « the verification did not run
+  to a conclusion »: « the control plane could not be asked », about a plane that had answered.
+  It now answers `7`, « the verifier never saw the program's own code start », naming the
+  exception the program ended on; the program's own traceback is still printed. For the same
+  reason, a program that caught the abort of an unreadable chain and then raised an exception of
+  its own now gets the chain's ending (`4`, the transport's own problem code and sentence) rather
+  than the generic one.
+- The contract and the boundary move to 0.3.1, released with this client.
+- A `python` the shell cannot find is refused as before (64), and the refusal now names
+  the `python3` on the same PATH.
+- Every program the README and the quickstart run is spelled `python3 …`; the
+  quickstart starts the daemon again before section 7, shows a closed epoch verified,
+  and says how long a rejection stands.
+
 ## 0.3.0
 
 - **`--socket` is optional for a per-user profile**, on every verb that opens a connection. Given

{sayfirst_cli-0.3.0 → sayfirst_cli-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sayfirst-cli
-Version: 0.3.0
+Version: 0.3.2
 Summary: The product command-line interface of the sayfirst control plane
 Project-URL: Repository, https://github.com/fredaime/sayfirst-cli
 Project-URL: Documentation, https://github.com/fredaime/sayfirst-cli/blob/main/README.md
@@ -15,8 +15,8 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Requires-Python: <3.15,>=3.12
-Requires-Dist: sayfirst-boundary==0.3.0
-Requires-Dist: sayfirst-contract==0.3.0
+Requires-Dist: sayfirst-boundary==0.3.2
+Requires-Dist: sayfirst-contract==0.3.2
 Description-Content-Type: text/markdown
 
 <!-- SPDX-License-Identifier: Apache-2.0 -->
@@ -36,10 +36,13 @@ anything that matters: *may I do this, with these arguments, as this account?*
   person can read, over a Unix socket that tells it who is asking from the
   kernel's own credentials. No URL, no token, nothing to leak (article 6).
 - **The program never decides.** It asks, and it does only what was allowed:
-  the boundary (`sayfirst-boundary`) holds the grant for exactly one execution.
+  the boundary (`sayfirst-boundary`) holds the grant a policy allow serves, for the run;
+  an allow that a person's approval produced carries no grant — it runs the act
+  once, and the same act asked again waits under a new approval.
 - **A person is in the loop by construction, not by dashboard.** A suspension
   is a wait. `sayfirst approvals approve` ends it once, the deadline comes from
-  the policy, and a rejection is final.
+  the policy, and a rejection stands until that deadline, or until the daemon
+  restarts.
 - **Every decision leaves a record**, and `sayfirst evidence export` saves a
   bundle a third party verifies offline, with the contract alone.
 - **The evidence is honest about itself.** An export of an epoch the daemon has
@@ -60,7 +63,7 @@ flowchart LR
 ```console
 $ uv tool install sayfirst-cli --with-executables-from sayfirst-control-plane --with-executables-from sayfirstd
 $ sayfirst-daemon up --quickstart
-$ sayfirst instrument run --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument run --pack subprocess --scope local -- python3 my_agent.py
 ```
 
 The first installs the client (`sayfirst`), the daemon (`sayfirst-daemon`) and
@@ -69,7 +72,7 @@ install` takes one package, so the other two ride on `--with-executables-from`.
 The second writes a readable starter policy and a per-user configuration under
 `~/.sayfirst/quickstart/` **if they are not there**, starts the real daemon in
 the background, and says « ready » only once that daemon has answered. The third
-runs a program you already have, under the `python` you named, with every
+runs a program you already have, under the `python3` you named, with every
 process it starts asked about first:
 
 ```console
@@ -81,7 +84,7 @@ policy: ~/.sayfirst/quickstart/policy.toml
 evidence: ~/.sayfirst/quickstart/evidence
 integrity grade: observability (the caller can write the store; the chain detects accidental corruption only)
 …
-$ sayfirst instrument run --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument run --pack subprocess --scope local -- python3 my_agent.py
 hello
 ```
 
@@ -103,7 +106,7 @@ restarted — and running `up --quickstart` again never writes over it.
 
 ```console
 $ sayfirstd status            # what the daemon says about itself
-$ sayfirst instrument verify --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument verify --pack subprocess --scope local -- python3 my_agent.py
 $ sayfirst-daemon down        # stops the daemon `up` started, and only that one
 ```
 
@@ -111,16 +114,14 @@ $ sayfirst-daemon down        # stops the daemon `up` started, and only that one
 a person's answer, the proof, the chain read back and exported — and every
 command on that page was run, in that order, before it was written down.
 
-### What the index holds today
+### What the index holds
 
-`sayfirst-cli` 0.2.0 is on the Python index, with `sayfirst-contract`,
-`sayfirst-boundary`, `sayfirst-contract-stub` and `sayfirst-conformance`. That
-release **predates the three commands above**: it requires `--socket`, reads
-`--pack` as a directory only, and refuses `python` as the first word of a
-target. `sayfirst-control-plane` and `sayfirstd` are **not on the index** as
-this is written. Until a release carries this page, build the distributions from
-checkouts of the two repositories and install those — the quickstart's first
-section gives the three lines, and they are what its walk used.
+Everything the three commands above need is on the Python index at 0.3.2:
+`sayfirst-cli`, the `sayfirst-contract` it speaks and the `sayfirst-boundary` a
+governed program holds its grants in, and the control plane's
+`sayfirst-control-plane` and `sayfirstd`. The first command installs all five
+and builds nothing. A checkout builds the same thing — the quickstart's first
+section gives the three lines.
 
 Installed on its own, the client brings three distributions and no more: the
 command, the contract it speaks, and the boundary in which a governed program
@@ -142,12 +143,13 @@ verified, and one answer rendered as it was given: allow, deny or suspend, and
 **It puts the boundary in front of somebody else's program.** `sayfirst
 instrument run --pack PACK … -- <program>` runs a program with the named effects
 asked about first, reversibly and writing nothing anywhere; a program spelled
-`python app.py` is handed, whole command and all, to the interpreter that was
-named, so it keeps its own environment's dependencies; `instrument verify`
-runs it again under the interpreter's own audit hook and proves, from that and
-the scope's evidence chain alone, that every effect of a named kind was preceded
-by a decision; `instrument apply` is reserved for the committed code
-modification and refuses, saying so. `sayfirst packs list` prints the packs this
+`python3 app.py` (or `python app.py` inside an activated environment) is
+handed, whole command and all, to the interpreter that was named, so it keeps
+its own environment's dependencies; `instrument verify` runs it again under the
+interpreter's own audit hook and proves, from that and the scope's evidence
+chain alone, that every effect of a named kind was preceded by a decision;
+`instrument apply` is reserved for the committed code modification and refuses,
+saying so. `sayfirst packs list` prints the packs this
 distribution ships — `database`, `http-client`, `subprocess` — each of which
 `--pack` takes by that name, while a pack of your own is a directory spelled
 with a separator, `--pack ./own-pack` ([`docs/PACKS.md`](docs/PACKS.md)). A program whose effects are
@@ -247,7 +249,7 @@ contract is built from a checkout of the control plane's repository, at the tag
 this client pins:
 
 ```console
-$ SAYFIRST_CONTRACT_SOURCE=../sayfirst-control-plane SAYFIRST_CONTRACT_REF=v0.3.0 ./scripts/gate.sh
+$ SAYFIRST_CONTRACT_SOURCE=../sayfirst-control-plane SAYFIRST_CONTRACT_REF=v0.3.2 ./scripts/gate.sh
 ```
 
 The workflow does the same and carries no credential of any kind: a fork can
@@ -274,9 +276,9 @@ GitHub's private reporting, never a public issue — [`LICENSE`](LICENSE),
 
 ## Status
 
-**0.2.0 is the first public release**, 2026-09-17. What is *not* here is named
-too, because a surface a reader assumes is an overclaim: `connect`, `profile`,
-`whoami`, `integrate` and `version` are in
+**0.2.0 is the first public release**, 2026-09-17. 0.3.2 is the current one.
+What is *not* here is named too, because a surface a reader assumes is an
+overclaim: `connect`, `profile`, `whoami`, `integrate` and `version` are in
 [`docs/PARTITION.md`](docs/PARTITION.md) and none of them exists here.
 
 Next, and only what a document in this tree already says: the `evidence` grade of

{sayfirst_cli-0.3.0 → sayfirst_cli-0.3.2}/QUICKSTART.md

@@ -7,13 +7,16 @@ Python program you already have:
 ```console
 $ uv tool install sayfirst-cli --with-executables-from sayfirst-control-plane --with-executables-from sayfirstd
 $ sayfirst-daemon up --quickstart
-$ sayfirst instrument run --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument run --pack subprocess --scope local -- python3 my_agent.py
 ```
 
 Everything on this page was run, in this order, before it was written down: the
-commands are pasted from that run, and so are their answers. The run used
-distributions built from this tree and installed by the first command, in a
-shell with neither repository on any path, under a home directory made for it;
+commands are pasted from that run, and so are their answers. The run installed
+0.3.2 with the first command from wheels built from the two release trees,
+given `--no-index` (the walk ran before 0.3.2 reached the index; « From
+checkouts instead » below is that install), on a PATH with `python3` and no
+`python`, in a shell with neither repository on any path, under a home
+directory made for it;
 its paths are written here the way they read under an ordinary account (`~`, and
 `/run/user/1000` for the runtime directory). Your identifiers, timestamps and
 hashes will differ; the shapes will not.
@@ -22,21 +25,29 @@ hashes will differ; the shapes will not.
 
 - Linux or macOS. The control plane listens on a local socket and reads who
   is calling from the kernel; there is no port and nothing that takes a token.
-- Python 3.12, 3.13 or 3.14, and [`uv`](https://docs.astral.sh/uv/). The walk
-  used uv 0.12.
-- A home directory that only you can write. The daemon refuses to put its
-  socket below a directory a group can write and that is not sticky
-  (`socket_directory_unprotected`), and it says so instead of starting.
+- Python 3.12, 3.13 or 3.14 as `python3` on your PATH (Linux distributions
+  and macOS name it that; inside an activated virtual environment `python`
+  works too), and [`uv`](https://docs.astral.sh/uv/). The walk used
+  uv 0.12.
+- A home directory that only you can write. The daemon refuses to start if
+  the socket's directory, or any directory on the way to it, can be written
+  by a group or by others and is not sticky (`socket_directory_unprotected`),
+  and likewise for the policy's directory and those above it
+  (`policy_unavailable_at_start … exposed: group_write`); either way it says
+  so instead of starting.
 
 ## 1. Install
 
 ```console
 $ uv tool install sayfirst-cli --with-executables-from sayfirst-control-plane --with-executables-from sayfirstd
- + sayfirst-boundary==0.3.0
- + sayfirst-cli==0.3.0
- + sayfirst-contract==0.3.0
- + sayfirst-control-plane==0.3.0
- + sayfirstd==0.3.0
+Resolved 5 packages in 3ms
+Prepared 5 packages in 6ms
+Installed 5 packages in 1ms
+ + sayfirst-boundary==0.3.2
+ + sayfirst-cli==0.3.2
+ + sayfirst-contract==0.3.2
+ + sayfirst-control-plane==0.3.2
+ + sayfirstd==0.3.2
 Installed 1 executable from `sayfirst-control-plane`: sayfirst-daemon
 Installed 1 executable from `sayfirstd`: sayfirstd
 Installed 1 executable: sayfirst
@@ -49,14 +60,11 @@ other two ride on `--with-executables-from`; three separate `uv tool install`
 lines, or `pip install sayfirst-cli sayfirst-control-plane sayfirstd` in an
 environment of your own, install the same thing.
 
-**What the index holds is not yet what this page installs.** `sayfirst-cli`
-0.2.0 is on the index and predates everything below: it has no default socket,
-reads `--pack` as a path only, and refuses `python` as the first word of a
-target. `sayfirst-control-plane` and `sayfirstd` are not on the index at all as
-this is written. Until a release carries this page, install from checkouts of
-the two repositories,
+**From checkouts instead.** A contributor installs the same thing from the two
+repositories' trees,
 <https://github.com/fredaime/sayfirst-control-plane> and
-<https://github.com/fredaime/sayfirst-cli> — which is what the walk did:
+<https://github.com/fredaime/sayfirst-cli>: build the wheels, then install them
+with nothing fetched.
 
 ```console
 $ (cd /path/to/sayfirst-control-plane && uv build --all-packages --wheel --out-dir ~/wheels)
@@ -64,9 +72,9 @@ $ (cd /path/to/sayfirst-cli && uv build --wheel --out-dir ~/wheels)
 $ uv tool install --no-index --find-links ~/wheels sayfirst-cli --with-executables-from sayfirst-control-plane --with-executables-from sayfirstd
 ```
 
-`--no-index` keeps the install to the wheels you built: nothing is fetched, so
-what runs is exactly those two trees — and two of the five distributions are
-not on the index to be fetched anyway.
+`--no-index` keeps the install to the wheels you built: the index carries the
+same version numbers, and an installer allowed to look there could take the
+published files instead of your trees.
 
 ## 2. Start a control plane
 
@@ -82,7 +90,7 @@ grade re-evaluation interval: 30 seconds
 privacy provider: none (captured content is recorded as given)
 evidence emission: delivering
 log: ~/.sayfirst/quickstart/daemon.log
-pid: 1622067
+pid: 741184
 wrote: ~/.sayfirst/quickstart/policy.toml
 wrote: ~/.sayfirst/quickstart/daemon.toml
 stop: sayfirst-daemon down
@@ -100,13 +108,15 @@ Everything lives in one private directory (`0700`, files `0600`):
 
 ```console
 $ ls -la ~/.sayfirst/quickstart
-drwx------ 3 you you  160 .
--rw------- 1 you you    0 daemon.lock
--rw------- 1 you you   75 daemon.log
--rw------- 1 you you  259 daemon.run.json
--rw------- 1 you you  596 daemon.toml
-drwx------ 5 you you  120 evidence
--rw------- 1 you you 3008 policy.toml
+total 16
+drwx------ 3 you you  160 Sep 29 01:06 .
+drwx------ 3 you you   60 Sep 29 01:06 ..
+-rw------- 1 you you    0 Sep 29 01:06 daemon.lock
+-rw------- 1 you you   76 Sep 29 01:06 daemon.log
+-rw------- 1 you you  260 Sep 29 01:06 daemon.run.json
+-rw------- 1 you you  598 Sep 29 01:06 daemon.toml
+drwx------ 5 you you  120 Sep 29 01:06 evidence
+-rw------- 1 you you 3008 Sep 29 01:06 policy.toml
 ```
 
 `daemon.run.json` is what `up` knows about the daemon it started: its pid, the
@@ -142,7 +152,7 @@ subprocess.run(["echo", "hello"], check=True)
 ```
 
 ```console
-$ sayfirst instrument run --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument run --pack subprocess --scope local -- python3 my_agent.py
 hello
 ```
 
@@ -162,27 +172,51 @@ that. Three things in that line are worth a sentence each.
   one name. Nothing is searched for, and whoever answers is still verified to be
   your own account's process before a byte is sent. `--socket PATH` overrides
   it, and system mode always names it.
-- **`python` means your `python`.** The program is handed to the interpreter
+- **`python3` means your `python3`.** The program is handed to the interpreter
   you named, found the way your shell finds it, with the boundary installed in
   that process — so a program living in a project's environment keeps its own
-  dependencies:
+  dependencies. Here `~/project` has an environment of its own
+  (`uv venv`, then `uv pip install humanize`) holding a package the `sayfirst`
+  tool does not, and `real_agent.py` uses it:
+
+```python
+import sys
+
+import humanize
+
+print("hello from the project's own interpreter")
+print("running under", sys.prefix)
+print("imported:", humanize.naturalsize(1_000_000))
+```
+
+  In `~/project`, with its environment activated, `python3` is that
+  environment's:
 
 ```console
-$ sayfirst instrument run --pack subprocess --scope local -- python real_agent.py
+$ . .venv/bin/activate
+$ sayfirst instrument run --pack subprocess --scope local -- python3 real_agent.py
 hello from the project's own interpreter
 running under ~/project/.venv
-imported: a dependency only the project has
+imported: 1.0 MB
 ```
 
-  An agent started as a console script rather than as `python …` is handed
+  Without the activation the same command finds the system `python3`, and the
+  program stops at its import (`ModuleNotFoundError: No module named 'humanize'`).
+
+  An agent started as a console script rather than as `python3 …` is handed
   over the same way: `-- ./myagent` reads the executable's shebang
   (`#!…/.venv/bin/python`) and runs it under that interpreter. Named without an
   interpreter (`-- my_agent.py`, or `-- -m package`), a program runs inside the
   interpreter that carries `sayfirst` itself, which as a `uv` tool has none of
   your project's packages. A runner in that place — `-- uv run app.py` — is
   refused, because it would pick an interpreter the boundary is not in; name the
-  interpreter instead. The named interpreter has to be Python 3.12 or later, and
-  interpreter options (`python -u …`) are not carried.
+  interpreter instead. The named interpreter has to be Python 3.12 or later. An
+  option after the interpreter's name is refused (`-- python3 -u real_agent.py`
+  exits `64`: « found no file to run at '-u' »); an option the interpreter also
+  reads from the environment reaches it that way —
+  `PYTHONUNBUFFERED=1 sayfirst instrument run …` runs the program unbuffered.
+  A `python` the shell cannot find is refused (`64`), and the refusal says the
+  same PATH has a `python3`.
 
 What the control plane recorded, read back from it:
 
@@ -195,12 +229,12 @@ grade re-evaluation interval: 30 seconds
 privacy provider: none (captured content is recorded as given)
 evidence emission: delivering
 $ sayfirst evidence history --scope local --from 1 --all
-1 composition daemon 2b12918b5588b2e3b50efa80fb7035ead2d2579537d991118f92b05bc0c0cfb3
-2 grade b5b86aba-5d1b-4b47-8059-38783a488547 7f6c25dfac3eac4ee6174aff24630eaf8f8804d96436a0daf160644e8195806f
-3 grade 7750b836-8ee2-4d2b-8de5-2c9d96b16e75 ca6a3b37ba461f63b70ae8b6d16641c4b1d446be7fbb428a9d50db38c2c55d1e
-4 grade 0db649e3-d5c9-4145-b05a-feb2ed6c1344 23ca566a49a282624fc21c1a65f467c2d437350682d0ad6dfe131e429f76fdc7
-5 effect 0db649e3-d5c9-4145-b05a-feb2ed6c1344 13776e23385f7a6fa0aff7a01af3a3e090ea3be27a7e9aeab83f93cb09dee791
-…
+1 composition daemon b7e07cc5149332bda660b2bfd874409cc3c43c3fcc545bcdfe434eeca08d7992
+2 grade 5ca3ce19-2d93-44de-839a-a25148efacc4 8e500b2d2f634f07ed10e70b769b0d170821bd07d9121c5fcdabbb914fdf4d66
+3 grade bc12e161-76be-4939-80d2-711c7ba145d8 614359e106f698383cc7da518ebd5714be580e70acf0ae9e3b9141b40a83ecb4
+4 effect bc12e161-76be-4939-80d2-711c7ba145d8 effeb84e48ae71368bd796198d1a49c256c4f7c381f72d11d3e7dc5567355d5e
+5 grade 8abbfb3c-a3b1-4ca1-8f74-fc732ffa7caa c5a7e9be2d2af3fd0dbb3d691caa7a4019a06dcf1dea34417acece0cb91753ea
+6 grade 8af05baa-2b94-47f9-acdc-3d9dbd51850e 55e018d5ba3cfd56f7e812351b3a6762bb3006e0209eaf30a27cb722c008167a
 next_from: none
 ```
 
@@ -213,10 +247,10 @@ and change one word — `outcome = "allow"` to `outcome = "deny"`. Save. Nothing
 is restarted; the daemon reads the file when it decides.
 
 ```console
-$ sayfirst instrument run --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument run --pack subprocess --scope local -- python3 my_agent.py
 Traceback (most recent call last):
   …
-sayfirst_boundary.errors.Denied: denied: process.spawn (policy_denies, 48293af4-5ab0-4c92-b16b-f0ca974a490b)
+sayfirst_boundary.errors.Denied: denied: process.spawn (policy_denies, 47339de8-e6c3-4b2f-8c91-7eaa6a53aa26)
 $ echo $?
 1
 ```
@@ -231,10 +265,10 @@ suspension or an unreachable control plane as a denial too.
 Now `outcome = "suspend"`:
 
 ```console
-$ sayfirst instrument run --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument run --pack subprocess --scope local -- python3 my_agent.py
 Traceback (most recent call last):
   …
-sayfirst_boundary.errors.Suspended: suspended: process.spawn awaits approval 55fc6d74-275b-4250-9a7f-58871bfc5bf1
+sayfirst_boundary.errors.Suspended: suspended: process.spawn awaits approval 93684c01-f9e8-4f27-9ad8-6c2be85306c5
 $ echo $?
 5
 ```
@@ -242,38 +276,41 @@ $ echo $?
 Nothing ran, and a person is being waited for. Read the wait, then end it:
 
 ```console
-$ sayfirst approvals show --approval 55fc6d74-275b-4250-9a7f-58871bfc5bf1 --scope local
-approval: 55fc6d74-275b-4250-9a7f-58871bfc5bf1
-decision: 45faca76-852a-4991-a5fb-bc2190e42325
+$ sayfirst approvals show --approval 93684c01-f9e8-4f27-9ad8-6c2be85306c5 --scope local
+approval: 93684c01-f9e8-4f27-9ad8-6c2be85306c5
+decision: ace43a8a-88ad-4907-8e91-4e978af85604
 state: pending
-requested_at: 2026-09-23T02:05:45.453931Z
-deadline: 2026-09-23T02:10:45.453931Z
+requested_at: 2026-09-28T23:06:51.035245Z
+deadline: 2026-09-28T23:11:51.035245Z
 resolved_at: not stated
 reason: not stated
-$ sayfirst approvals approve --approval 55fc6d74-275b-4250-9a7f-58871bfc5bf1 --scope local --reason "checked by hand"
-approval: 55fc6d74-275b-4250-9a7f-58871bfc5bf1
-decision: 45faca76-852a-4991-a5fb-bc2190e42325
+$ sayfirst approvals approve --approval 93684c01-f9e8-4f27-9ad8-6c2be85306c5 --scope local --reason "checked by hand"
+approval: 93684c01-f9e8-4f27-9ad8-6c2be85306c5
+decision: ace43a8a-88ad-4907-8e91-4e978af85604
 state: approved
-requested_at: 2026-09-23T02:05:45.453931Z
-deadline: 2026-09-23T02:10:45.453931Z
-resolved_at: 2026-09-23T02:05:45.642267Z
+requested_at: 2026-09-28T23:06:51.035245Z
+deadline: 2026-09-28T23:11:51.035245Z
+resolved_at: 2026-09-28T23:06:51.216909Z
 reason: checked by hand
 person: user:you
-$ sayfirst instrument run --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument run --pack subprocess --scope local -- python3 my_agent.py
 hello
 ```
 
 That run is the one execution the person's act authorised: run it once more and
 it waits again, under a new approval. Running it *while* the wait is open
 returns the same approval rather than opening a second. `approvals reject` ends
-a wait the other way, and the next run is denied with `approval_rejected`.
+a wait the other way: every run of the same program is then denied with
+`approval_rejected` until that wait's deadline — five minutes here, since the
+rule you edited names no `review_deadline_seconds` — and a restart of the daemon
+forgets it.
 
 ## 5. Prove it
 
 Put the rule back to `"allow"`, and ask for proof rather than a run:
 
 ```console
-$ sayfirst instrument verify --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument verify --pack subprocess --scope local -- python3 my_agent.py
 hello
 governed subprocess subprocess.Popen process.spawn events=1
 inspected: subprocess
@@ -296,7 +333,7 @@ alone on stdout.
 
 ```console
 $ sayfirst-daemon down
-SayFirst Control Plane stopped (pid 1622067)
+SayFirst Control Plane stopped (pid 741184)
 policy and evidence are kept under ~/.sayfirst/quickstart
 ```
 
@@ -315,6 +352,11 @@ $ sayfirstd status
 socket: /run/user/1000/sayfirst/daemon.sock (the per-user default; no --socket was given)
 verified: false (server_uid None, expected None)
 unreachable: [Errno 2] No such file or directory
+```
+
+It exits `4`, like every read that could not ask.
+
+```console
 $ sayfirst ask --capability process.spawn
 socket: /run/user/1000/sayfirst/daemon.sock (the per-user default; no --socket was given)
 verified: false (server_uid not stated, expected not stated)
@@ -322,7 +364,7 @@ could not ask: unreachable: [Errno 2] No such file or directory
 retryable: true
 $ echo $?
 4
-$ sayfirst instrument run --pack subprocess --scope local -- python my_agent.py
+$ sayfirst instrument run --pack subprocess --scope local -- python3 my_agent.py
 socket: /run/user/1000/sayfirst/daemon.sock (the per-user default; no --socket was given)
 nothing is there now, so an effect these packs name will fail closed; `sayfirst-daemon up --quickstart` starts a control plane at that address
 Traceback (most recent call last):
@@ -343,6 +385,14 @@ escape.
 
 ## 7. Asking by hand, and reading back
 
+Section 6 left the control plane stopped; start it again:
+
+```console
+$ sayfirst-daemon up --quickstart
+SayFirst Control Plane ready
+…
+```
+
 The same three outcomes without a program. `--scope` defaults to `local` for
 `ask`, and every other read names it:
 
@@ -352,22 +402,22 @@ verified: true (server_uid 1000, expected 1000)
 outcome: allow
 reason: policy_allows
 capability: process.spawn in scope local
-decision: 52ff1ab5-8813-4230-9ca4-2f272612c64d at 2026-09-23T02:05:47.180188Z
+decision: 86c6debb-715a-4f28-9aa8-75026a395f48 at 2026-09-28T23:06:52.489393Z
 policy version: sha256:efc1746cea9b50cb31aa5c9f08de996cbefabc34a09d4250d8b68f67c709a5dc
 $ sayfirst ask --capability net.egress
 verified: true (server_uid 1000, expected 1000)
 outcome: suspend
 reason: policy_requires_review
 capability: net.egress in scope local
-decision: 5cb90b68-bb1a-4674-ae2d-97a1bd9c5797 at 2026-09-23T02:05:47.255248Z
+decision: 30fac8bc-d1a1-4058-a7c4-1ff62e4db58d at 2026-09-28T23:06:52.574755Z
 policy version: sha256:efc1746cea9b50cb31aa5c9f08de996cbefabc34a09d4250d8b68f67c709a5dc
-approval: d058eee2-4ecc-488c-837d-037e206c1247
+approval: 335902ec-3ece-4b06-8856-9d45ef78e2e2
 $ sayfirst ask --capability database.open
 verified: true (server_uid 1000, expected 1000)
 outcome: deny
 reason: policy_absent
 capability: database.open in scope local
-decision: c6284ad7-f77b-4367-a50d-977489e2f6f7 at 2026-09-23T02:05:47.335332Z
+decision: e2791157-0385-4a79-86d0-abfb97cd83b4 at 2026-09-28T23:06:52.655469Z
 policy version: sha256:efc1746cea9b50cb31aa5c9f08de996cbefabc34a09d4250d8b68f67c709a5dc
 ```
 
@@ -379,18 +429,18 @@ rule saying no.
 One decision, explained in the daemon's own words and traced into the chain:
 
 ```console
-$ sayfirst explain --scope local --decision 474856fc-e891-46ac-844c-efa30cc9322f
-decision_ref: 474856fc-e891-46ac-844c-efa30cc9322f
+$ sayfirst explain --scope local --decision 86c6debb-715a-4f28-9aa8-75026a395f48
+decision_ref: 86c6debb-715a-4f28-9aa8-75026a395f48
 scope: local
 capability: process.spawn
 outcome: allow
 reason: policy_allows
 rule_id: local-processes-run
 policy_version: sha256:efc1746cea9b50cb31aa5c9f08de996cbefabc34a09d4250d8b68f67c709a5dc
-decided_at: 2026-09-23T02:05:47.410354Z
+decided_at: 2026-09-28T23:06:52.489393Z
 …
-$ sayfirst trace --scope local --decision 474856fc-e891-46ac-844c-efa30cc9322f | tail -1
-chain: sequence 34, entry_hash 0d00934b16b3dc0004d7e13c884b83aec61a79dfb6d43278dab3530d1f8250d7, grade observability
+$ sayfirst trace --scope local --decision 86c6debb-715a-4f28-9aa8-75026a395f48 | tail -1
+chain: sequence 23, entry_hash ee313608e9c4f09b747c7ec9ac5d817e0945bbeb7b9f267f76f1d2c2c4e935d5, grade observability
 ```
 
 Every read is itself recorded: `history`, `explain`, `trace` and `export` each
@@ -409,15 +459,60 @@ chain: intact
 coverage: unknown
 issue: coverage_unknown
 verification: intact
-saved: bundle.json (36 entries)
+saved: bundle.json (29 entries)
+```
+
+### A closed epoch, verified
+
+`down` closes the daemon's evidence epoch and `up` opens the next, and only a range
+inside a closed epoch can be checked whole. The history shows where the epoch closed —
+the `recovery` entry just before the next `composition`:
+
+```console
+$ sayfirst evidence history --scope local --from 1 --all | grep -E 'recovery|composition'
+1 composition daemon b7e07cc5149332bda660b2bfd874409cc3c43c3fcc545bcdfe434eeca08d7992
+19 recovery daemon f36c43ff25d8a0c15b64dd55a089127fcab352ffa056420c536314ad63c76a3b
+20 composition daemon 17c41de74accb1d7b03bf8864229f370c446623d9f528eae1f5387c22cb6463e
+```
+
+Export up to that entry with `--to`:
+
+```console
+$ sayfirst evidence export --scope local --from 1 --to 19 --out closed.json
+local_check: unverifiable
+manifest: recomputes
+chain: intact
+coverage: complete
+verification: intact
+saved: closed.json (19 entries)
+```
+
+Coverage is `complete` — nothing in that range is missing — and the check still says
+`unverifiable`, exit `7`, because section 4 put a person in that range: an approval,
+and every decision that follows from one — the run it authorised, and any
+`approval_rejected` denial — re-derives as `unverifiable` with the cause
+`reason_outside_recipe`. A policy file cannot re-derive a human act, and the
+verifier says so rather than counting it (`--json` shows each decision's
+cause). A range with no person's act in it verifies — here the same epoch up
+to the suspension's own entry, before anyone answered it (`sayfirst trace` on
+the suspended decision names its sequence):
+
+```console
+$ sayfirst evidence export --scope local --from 1 --to 10 --out quiet.json
+local_check: confirmed
+manifest: recomputes
+chain: intact
+coverage: complete
+verification: intact
+saved: quiet.json (10 entries)
 ```
 
-After a `down` and an `up`, the range that ends at the closed epoch's last entry
-exports with coverage `complete`; `sayfirst evidence exports DIRECTORY`
-re-verifies every saved bundle with the contract distribution alone, no daemon
-needed. A decision a person granted re-derives as `unverifiable` with the cause
-`reason_outside_recipe`, by design: an approval cannot be re-derived from a
-policy file, and the verifier says so rather than counting it.
+The epoch `up` opened in this section is still open, so a range inside it is
+`coverage: unknown` until the next `down` closes it.
+
+`sayfirst evidence exports DIRECTORY` re-verifies every saved bundle with the contract
+distribution alone, no daemon needed, and exits with the worst result among them.
+An export never writes over a file: naming one that exists is refused (`64`).
 
 ## 8. A control plane of your own
 
@@ -430,9 +525,12 @@ serving per_user at /run/user/1000/sayfirst/daemon.sock (acl: checked)
 ```
 
 `daemon.toml` names the mode, the policy file and the evidence directory, all
-absolute; `~/.sayfirst/quickstart/daemon.toml` is a working example. Given a
-`[socket] path`, the daemon serves there instead, and every client command
-takes the same path as `--socket`:
+absolute; `~/.sayfirst/quickstart/daemon.toml` is a working example. Stop the
+quickstart daemon first (`sayfirst-daemon down`), or give the copy an
+`[evidence] path` and a `[socket] path` of its own: two daemons never share an
+evidence directory (`decision_store_unusable`) nor an address (`socket_in_use`),
+and the second refuses to start. Given a `[socket] path`, the daemon serves
+there instead, and every client command takes the same path as `--socket`:
 
 ```console
 $ sayfirst ask --capability process.spawn --socket /srv/sayfirst/daemon.sock