@mrciphersmith/keryx 0.2.154 → 0.2.156

package/README.md

@@ -32,6 +32,11 @@ It also ships **an agent runtime of its own**, built directly on that context:
 durable sessions, an allow/ask/deny policy engine, kernel-enforced sandboxing,
 child agents and evidence-gated completion. Keep using Codex, Claude or Cursor,
 run `keryx shell`, or do both — they all read the same project brain.
+You can delegate the work, not the responsibility: a managed flow freezes its
+acceptance criteria before the work starts, lets them change only through a
+recorded update with a reason, and completes only when every one is confirmed
+against recorded evidence — under a named owner, with every confirmation and
+the completion itself signed.
 
 ```bash
 npm install -g @mrciphersmith/keryx
@@ -253,19 +258,55 @@ What is in it today:
   over stdio — so an ACP client (an editor, typically) can launch keryx as a
   subprocess, open a session bound to a project, and drive a real harness turn
   with streamed `session/update` notifications instead of one dump at the end.
+  The session gets keryx's own read-only project tools — graph, wiki, memory,
+  flow status, skills, repo map, related tests, health status and
+  `search_code` — wherever `keryx shell` would offer them (same gate, same
+  definitions), alongside file reads, `shell_exec` and `apply_patch`; web
+  tools, keryx's own MCP servers, subagents and bus tools are left out on
+  purpose. keryx advertises the commands it handles over ACP — `/help`,
+  `/model`, `/reasoning`, `/status` — and answers them itself. The model is
+  the editor's model picker (a `configOptions` entry of category `model`,
+  listing what keryx can run here): switch it there or with `/model`, and it
+  applies from the next turn without touching `keryx shell`'s saved choice.
   A gated tool call is asked through `session/request_permission` rather than
   approved locally — only an explicit allow runs it, and an `allow_always`
   answer is remembered by the client, never persisted by keryx — and
   `session/cancel`, `session/list`, and `session/load` (replaying a session
   created anywhere, including one from `keryx shell`) are all implemented.
-  Writes and shell execution stay local unconditionally (no `fs/write_text_file`
+  With no `--provider`/`--model` a session starts on the provider and model
+  `keryx shell` saved (run `keryx shell` once and pick one); with nothing configured it
+  still answers `initialize` and refuses `session/new` with a message saying
+  what to configure — it never answers with a test stand-in. The client's own
+  stdio MCP servers from `mcpServers` are started for that session, their
+  tools offered through `search_tool`/`use_tool` with every call asked, one
+  running set shared by the threads that send the same list, and stopped when
+  the connection ends or `keryx acp` is sent SIGTERM/SIGINT; `http`/`sse` entries and a server that
+  fails to start are reported to the client by name, and the session still
+  opens. Writes and shell execution stay local unconditionally (no `fs/write_text_file`
   or `terminal/*` calls, whatever the client advertises), and there is no
   HTTP/WebSocket transport, no authentication over this wire, and no
-  `session/resume`/`close`/`delete`/`set_mode`/`set_config_option`. Verified
-  against the published v1 schema and this repo's own scripted test client,
-  not yet against a shipping IDE. See [the CLI
-  reference](docs/docs/cli-reference.md#acp) for the full method table and
-  what keryx does when a capability is absent.
+  `session/resume`/`close`/`delete`/`set_mode`. Verified
+  against the published v1 schema and this repo's own scripted test client;
+  Zed has been driven against it by hand, and no shipping IDE is part of the
+  automated tests. See [the CLI
+  reference](docs/docs/cli-reference.md#acp) for the full method table, the
+  tool roster and why each exclusion, the commands, and what keryx does when a
+  capability is absent.
+- **ACP client — foreign agents under keryx's policy.** The other direction:
+  `keryx agents external run gemini-acp --task "…"` launches an external ACP
+  agent (Gemini CLI's `--experimental-acp`) as a subprocess and drives it as
+  its client, inside a disposable git worktree. keryx advertises only what it
+  serves (`fs.readTextFile`; `fs.writeTextFile` with `--write`; never
+  `terminal`), serves every `fs/*` request itself — confined by real path to
+  the worktree — and answers every `session/request_permission` through its
+  own approval gate with the mode lowered to `ask`: only an explicit allow
+  selects `allow_once`, `allow_always` is never chosen, and an unattended run
+  refuses anything that needs a human. The agent gets keryx's context as a
+  read-only `serve-mcp` launched from the running build, and every run is a
+  keryx session with its decisions, fs requests, usage and cost (or
+  `missing`). Honest limit: an agent's own internal tools never reach ACP, so
+  keryx cannot see or gate them — the disposable worktree is what contains
+  them. See the [ACP client guide](docs/docs/guides/acp-client.md).
 - **Plans that survive the turn.** For multi-step work, the agent can keep a
   structured execution plan in the session's own `plan.json` — beside the
   transcript, not inside the Slate — so closing a Slate (or a Flow reporting
@@ -394,15 +435,86 @@ Grouped by what you are trying to do, not by internal module layout.
 **Operate agents**
 
 - **tasks** — an agent-first Task Manager driven by `keryx flow`, with frozen
-  acceptance criteria and status gates.
+  acceptance criteria and status gates. Each flow can name an accountable
+  human **owner** (`flow init --owner`/`flow owner set`, never inferred), and
+  `ac confirm`/`complete` append an honest, append-only **signature** — who
+  acted, when, and what was signed, with its basis (`stated`/`derived`/
+  `unknown`) stated rather than assumed. A flow can also require a
+  terminal-minted **confirmation token** (`flow init --require-confirmation`,
+  `flow confirm`) that no agent tool can mint. It adds friction for an agent
+  but does not prove a person was present. `flow recover` returns a flow left
+  in `completing` by an interrupted run. See
+  [TM-02](docs/decisions/keryx-harness/TM-02-flow-owner-and-signed-completion.md)
+  and [TM-03](docs/decisions/keryx-harness/TM-03-terminal-confirmation-token.md).
 - **triggers** — declared automation over `.metaproject/triggers.json` (a
   repository event or a cron/systemd schedule): `reconcile`/`rebuild` keep the
-  graph and wiki current, `open-flow`/`flow-next` open or report on Task
-  Manager work. `keryx trigger install` extends the same hook files `sync
-  install-hooks` and `update` already write into, rather than owning its own;
-  `keryx trigger schedule` prints a cron line or systemd unit pair and runs no
-  daemon of its own. Every fired run is recorded and gated by a project-wide
-  spend ceiling and a run lock. See the [CLI reference](docs/docs/cli-reference.md#trigger).
+  graph and wiki current, `open-flow` opens Task Manager work, and `flow-next`
+  either reports a flow's next task or — with a `dispatch` block — dispatches a
+  keryx agent to work it unattended: in a throwaway worktree on a
+  `trigger/<flow>-<task>` branch that is never pushed, its commands and its
+  health gate inside a mandatory hardened sandbox (network off, home and
+  credentials hidden, allow-listed environment), every would-be-approval
+  denied and recorded, spend reserved before the first model call, tokens and
+  USD recorded, and a per-trigger spend ceiling on top of the project-wide one.
+  `keryx trigger install` extends the same hook files `sync install-hooks` and
+  `update` already write into; `keryx trigger schedule` prints a cron line or
+  systemd unit pair (with a real `OnCalendar=`) and runs no daemon of its own. Triggered runs and a manual
+  `sync --apply`/`gdgraph build` share one maintenance lock (manual waits,
+  triggered refuses). In the TUI, the sidebar's **Triggers** section lists the
+  event-fired triggers. Each row shows the last outcome and its age, and a `NET`
+  marker when the agent gets the host network. The section also shows project
+  trigger spend and any open spend reservations. `/triggers` (or a click)
+  opens a list+detail modal with the full unattended posture. There, `r` then
+  `y` runs one now as `keryx trigger run <name>` in a child process of the same
+  build, bound by the same locks, budgets and refusals as the CLI. See the
+  [CLI reference](docs/docs/cli-reference.md#trigger).
+- **schedule**: scheduled agent tasks in the background. Say it in the shell ("schedule a task every
+  4 hours to check my open PRs"), use `/schedule`, or run `keryx schedule add`. keryx shows a
+  **confirmation card** listing the cadence and next runs, the prompt, the runner and its budget,
+  the network mode, and every granted tool with the account it acts as. It also shows exactly what
+  will be installed. Nothing is written until you say yes. After that, keryx stores the schedule in a
+  per-machine, gitignored store and installs a `systemd --user` timer (launchd on macOS, cron
+  elsewhere) that runs `keryx trigger run <name>` unattended. The run leaves a report in
+  `.metaproject/data/trigger/reports/`.
+  - **Granted tools** (`gh pr list/view/checks`, `gh issue list/view`, `gh run list`) run
+    **outside** the sandbox with your credentials. The model sees only redacted output, and the
+    token never enters the sandbox, the model context or the report.
+  - **Network:** the agent's shell network is `off`, `full`, or `allowlist` (Linux
+    only) — reaches only the domains you name, through a loopback proxy keryx runs
+    outside the sandbox; it governs only the agent's own shell commands, never the
+    model call or a granted tool. See the [CLI reference](docs/docs/cli-reference.md#schedule).
+  - **Refusals:** the unattended floor is unchanged, and an entry edited after you confirmed it is
+    refused (`grants-changed`).
+  - **Tracking:** every run is spend-bounded and appears in `keryx trigger status` and
+    `keryx governance report`.
+  - **Management:** `keryx schedule list|show|pause|resume|run|remove`. In `keryx shell`:
+    - the sidebar's **Schedules** section shows each schedule's next run and last outcome;
+    - `/schedules` (or a click) opens the detail: Overview, Grants, Runs, Report;
+    - `p` pauses or resumes, `r` then `y` runs it now, `d` then `y` deletes it;
+    - a run finished in the background shows up without a restart.
+  - **Limits:** the machine must be on. systemd and launchd catch up one missed run after a boot or
+    wake; cron does not. Without linger, a user timer does not run while you are logged out, and
+    keryx never enables linger for you. The hardened sandbox is Linux-only.
+
+  See the [CLI reference](docs/docs/cli-reference.md#schedule).
+- **governance** — `keryx governance report`, one read-only report unifying what
+  is already recorded: review-round spend per flow (USD and tokens, with a
+  rounds-with-cost/rounds-total count for partial coverage), project-wide
+  trigger spend (never attributed to a flow — the run record carries no flow
+  reference), who confirmed each acceptance criterion and who signed
+  completion (with identity basis), and every `flow complete` attempt's gate
+  outcomes. A figure nobody recorded is reported as "not recorded", never as
+  zero. Writes `.metaproject/data/governance/artifacts/latest.{md,json}`, the
+  same convention `keryx health run` uses; `--all-projects` also covers every
+  project in the user-global registry. In the TUI, the sidebar's
+  **Governance** row shows `no report — click to run`,
+  `unreadable — click for reason`, `running…`, `last report <date>` or
+  `failed — click to retry`. With no report, a click
+  (or `/governance`) runs the report in the background, and the row updates
+  when it finishes. With a report, a click opens it in a scrollable modal,
+  where `r` re-runs it. Sessions written by `keryx agents external run` appear
+  in `/sessions` marked `acp:<agent>`. See the
+  [CLI reference](docs/docs/cli-reference.md#governance).
 - **security** — deterministic secrets / PII / prompt-injection / egress
   scanning, redaction, and a policy gate at agent write seams, with a committed
   evaluation corpus.
@@ -414,7 +526,8 @@ Grouped by what you are trying to do, not by internal module layout.
   (Facts / Work / Know-how) overview, evidence-linked wrap-up proposals with owner
   review, and a fail-closed runtime policy guard. Driven by `keryx workspace`
   (`keryx modules enable sac` to turn it on); accepting a proposal into real
-  project knowledge always passes through a human `confirm-review`, which
+  project knowledge always passes through an approval-gated `confirm-review`
+  (friction for an agent, not proof of a person — see TM-03), which
   refuses a security-flagged proposal until `--acknowledge-security` records
   that someone read the findings. The TUI's `/review` modal offers the same
   acknowledgement as an explicit `[s]` action, never as an automatic fallback
@@ -580,9 +693,12 @@ graph falls back to its deterministic resolver when a grammar is absent.
 | ripgrep is external | `keryx ctx rg` needs `rg` on `PATH` | Install ripgrep, or let the agent read files directly |
 | Model commands need a credential | Four of the five commands above exit non-zero without one; `wiki enrich` exits `0` and marks the affected pages skipped | Everything else runs deterministically offline |
 | External agents are read-only, and unproven against a live vendor process | A delegated CLI can read and search but never write; `worktree-write` is refused with a named reason. The parent gets the child's result and nothing before it — supervision of a running external child is not implemented. Everything is verified offline against recorded transcripts | Use keryx's own child agents for work that must mutate the tree |
-| `keryx trigger`'s `flow-next` action only reports | It records the next task's status into the run record; it never dispatches an agent turn to work it | Dispatch the reported task yourself, or through a flow orchestrator |
-| Trigger spend ceiling is project-wide | `open-flow`/`flow-next` triggers share one ceiling with every other recorded trigger cost; there is no per-trigger override | Watch `keryx trigger status`'s recorded cost |
-| Trigger-run lock does not cover interactive commands | A person running `keryx sync --apply` / `keryx gdgraph build` by hand can still race a triggered `reconcile`/`rebuild` | Avoid running those by hand while triggers may be firing |
+| A dispatched `flow-next` task is "done" by checks, not review | `task done` means normal end + a commit on the trigger branch + `keryx health gate` passing in the worktree; nobody has read the diff | Review and merge the `trigger/<flow>-<task>` branch yourself |
+| `trust` dispatch needs Linux + a working bubblewrap | The hardened unattended sandbox (network off, home hidden, allow-listed env) is bwrap-only; without it — or on macOS — a `trust` dispatch refuses before starting | Use `permissionMode: "ask"` (read-only), or run triggers on a Linux host with bwrap |
+| `dispatch.network: true` is the host's full network | The agent's commands then reach the internet and every host loopback service; the model call never needs it (it is made outside the sandbox) | Leave `network` off; review the `trigger/*` branch before installing or building it |
+| The unattended text floor is defence in depth | It can be spelled around (quoting, `$(…)`, interpreters); the boundary is the sandbox, not the floor | Keep `dispatch.network` off unless the task truly needs it |
+| A killed dispatch keeps its spend reserved | Its reservation counts against both ceilings until closed | `keryx trigger status`, then `keryx trigger resolve <runId> --spent <usd>` |
+| Dispatch cost is priced from your declared rates | keryx has no price table; wrong `rates` make both ceilings wrong by the same factor | Set `rates` from your provider's price list |
 
 Full detail, including known defects and platform caveats:
 [limitations](docs/docs/limitations.md).