ace-hitl 0.17.0 → 0.23.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ab176a502d7a751a22e89f461245046caa44d71943897b7f27b6d5ffdd10c84
-  data.tar.gz: f789375f072b07f087462b78fd2d2fb7a9ae45e167eedbd413a11fe09e9ead0e
+  metadata.gz: a9186e91db61d509bafd0c44d8ad023ed208614ad8cbfe749d3b49b0bbf10772
+  data.tar.gz: 151a5ad5cda6dc92256a7f2f604249858c04666c23a5a6ce85c9347dbf4640f4
 SHA512:
-  metadata.gz: b6f1c00953d56deac3fe8e7099a1aac527681b1314aeda336c7691de04bf7ab40af33c8815ddcac76777e02151609c555cb0f4f0be2276e8a7b8ab0359b3a9ae
-  data.tar.gz: 19e978992b0041ae887a26d743555fe69b8292fd01c763c488bef96e6feecb00c3437f58909d015eeaefa21884b552b203af47f94e583b2feef4e8bc3f4e06fc
+  metadata.gz: 8f6a6ef440d4404df3868ddc1e416032a09a1b59eb36e9d9a9317f214939677a5c58a724ec8cebd10bf88a7d5d1f412671f724be0957dd54c938b54cf06a1c44
+  data.tar.gz: 6dd4dae6d026e1167dcb7225188f7b5e73fd9fbfc4fde1625e1988daf4fb4922b2e8a477e5f142c68aad6032a806512fc6506ab0ad05eb71aed144627965e137

data/CHANGELOG.md

@@ -7,6 +7,152 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.1] - 2026-10-18
+
+### Fixed
+
+- Terminal routes are machine-scoped (round-9 review H1): the adapter now
+  reads the route's `machine` (defaults to `hitl.machine`) and refuses a
+  panel recipient on a different machine instead of delivering to a
+  local pane that merely shares the panel name and reporting a false
+  `delivered`. The refusal mirrors the hermes adapter, so both shipped
+  adapters apply the same address check.
+
+### Changed
+
+- Docs only: `docs/usage.md` now documents that route delivery requires
+  a panel-form recipient (folder-form recipients have no shipped delivery
+  route and are refused per-route), the per-route refusal semantics of
+  both shipped adapters, per-route `unavailable` retention for unknown
+  adapters, dotted route-name rejection, and the absolute `reply_to`
+  folder. `HitlConfigLoader.normalize` notes that mixing flat/shaped
+  config documents across tiers can invert cascade precedence.
+
+## [0.23.0] - 2026-10-18
+
+### Fixed
+
+- Adapters deliver to the event's recipient, not just the route's own
+  destination (PR #383 audit F1): the terminal adapter sends to the
+  recipient's `panel` (the route `pane` remains the fallback only for
+  legacy recipient-less events) and explicitly refuses a folder-form
+  recipient it cannot serve — never a silent send to the route pane.
+  Flat hitl config documents are no longer silently dropped (F11):
+  `.ace/hitl/config.yml` without the `hitl:` key now merges over the
+  shipped defaults instead of being shadowed by them. The default reply
+  address is built from the resolved sender folder (F6): an absolute
+  path that identifies the originating worktree, so two worktrees on
+  one machine never share a reply address (the relative `root_dir`
+  setting stays relative in config). Route names containing a dot
+  (e.g. `captain.telegram`) are rejected before any delivery attempt
+  (F10): delivery retention keys route names literally and a dot would
+  nest frontmatter keys, breaking retry/skip — `send` now fails closed
+  with `InvalidRouteError` naming the route.
+
+### Changed
+
+- An unknown adapter on one route no longer aborts the whole send
+  (PR #383 audit F5): the route is retained as `unavailable` with the
+  resolution error as its reason (never a bare `in_flight` marker), the
+  remaining routes still deliver, and the send still reports overall
+  delivery failure.
+
+## [0.22.0] - 2026-10-18
+
+### Added
+
+- Retention and redelivery of undelivered messages (8xg.t.sbz.1.3 / L2.4):
+  `send` now persists each route's last outcome, failure reason, and attempt
+  timestamp on the event's own file (`delivery.<route>` frontmatter — the
+  single state owner per ADR-034; no journal or queue). Default `send`
+  retries only undelivered or unknown-result routes and skips confirmed
+  delivered ones; `--force` redelivers every route and `--dry-run` reports
+  the retry/skip decisions without delivering. A `in_flight` marker written
+  before each attempt means a crashed send leaves an unknown result that the
+  next `send` retries — at-least-once semantics: a retry may duplicate, and
+  every rendering carries the same `(case <ID>)` + task binding so
+  recipients dedup by ID (exactly-once is not promised). Redelivery retries
+  the delivery, never the assignment. `list --delivery undelivered|delivered`
+  discovers retained events; `show` prints a per-route `Delivery:` block
+  with the retained failure reason. Redelivering an all-delivered event is a
+  no-op success (`nothing to retry (use --force to redeliver)`).
+
+## [0.21.0] - 2026-10-18
+
+### Added
+
+- Configurable adapter delivery routes (8xg.t.sbz.1.2 / L2.3): `ace-hitl
+  send <ref>` delivers a persisted event through the routes configured under
+  `hitl.adapters.routes` — the sender interface is adapter-independent, so
+  switching transports is pure configuration (no assignment or coworker
+  change). Every route reports its own result line; one route's success never
+  hides another's failure and an unavailable adapter never silently reroutes
+  (per-route isolation, fail-closed unknown-adapter/no-route errors).
+  Built-in `terminal` adapter pushes the shared event text to a pane via any
+  `ace-runtime` terminal (tmux/herdr); `ace-hitl-hermes` 0.8.0 ships the
+  `hermes` adapter entrypoint (publishes the shared rendering to the channel
+  folder; identical resend is idempotent, different-bytes collision fails
+  without overwrite, missing folder is `unavailable`). New adapters register
+  through the duck-typed `Ace::Hitl::Adapters` registry
+  (`lib/ace/hitl/adapters/<name>.rb` entrypoint — a future Nervus adapter
+  needs no ace-hitl change). Shared rendering (`Atoms::HitlEventText`):
+  `[HITL question]`/`[HITL report <result>]` prefix, `Reply-To:` on questions
+  only, task/assignment/step context. Delivery results are reported, not
+  persisted — retention and redelivery of undelivered messages is
+  8xg.t.sbz.1.3.
+
+## [0.20.0] - 2026-10-18
+
+### Added
+
+- Recipient addressing and Reply binding (8xg.t.sbz.1.1 / L2.2): `ace-hitl
+  create ... --to <name>` resolves a configured recipient into an explicit
+  address — machine + events folder + case ID (folder form, ID stamped from
+  the new event) or machine + panel — read from the `hitl` cascade
+  (`machine`, `default_recipient`, `recipients:<name>:{machine,folder|panel}`).
+  Questions record a `reply_to` address (sender machine + events folder + own
+  case ID) so answers bind to the original case and the right agent;
+  task/assignment/step stay context, never an ID substitute. Local Reply is
+  unchanged: `update <ref> --answer` bound by exact ID with strict ambiguity
+  and explicit not-found — no write to a foreign event. Unknown recipient
+  names, malformed configured addresses, and a missing `hitl.machine` fail
+  closed before anything is written. `show`/create output print
+  `Recipient:`/`Reply-To:`; `HitlEvent#recipient`/`#reply_to` expose the
+  address hashes for adapters (delivery itself lands in 8xg.t.sbz.1.2/.1.3;
+  local write is not delivery).
+
+## [0.19.0] - 2026-10-18
+
+### Fixed (review PR #383, round 3)
+
+- Report events carry no `kind` (loader returns nil), so question-oriented
+  `list --kind` filters never mix reports into a clarification list.
+
+### Added
+
+- Report events: the same `ace-hitl` file interface now records work-done/error notifications alongside questions. `ace-hitl create "..." --type report --result success|error [--body line]... [--task REF]` writes an event with status `recorded`, a `## Report` body, task/assignment/step references, and its own ID. Reports never await an answer: `wait`, `update --answer`, and `update --resume` on a report fail fast with an explicit error (exit 1); generic `--set/--add/--remove/--move-to` still work so an overseer can archive processed reports.
+- `--type question` is now written explicitly on new question events (loader defaults keep existing files without `type` valid questions); `--task` is accepted for both types; `list --type question|report` filters by type; `show` prints `Type:`/`Result:` and list gains the `recorded` status symbol.
+- Library guards: `HitlManager#update(answer:)` raises `NotAnswerableError` on reports before any file mutation; `wait_for_answer` and `dispatch_resume` return `{status: :report}` without sleeping.
+
+### Notes
+
+- Local write is not delivery: `recorded` means the report is persisted in `.ace-local/hitl/`, not that it reached the overseer. Remote addressing, reply routing, and configurable adapters land in 8xg.t.sbz.1.1–.1.3.
+
+## [0.18.0] - 2026-10-18
+
+### Removed
+
+- Remove the installed Lab provider and its attempt-bound managed HITL path: `Providers::Lab::AssignmentBinding`, `ProtectedAssignmentBinding`, the provider `ask`/native-delivery methods, the `ask` CLI command, and the Herdr-native delivery client in `LiveClient` (the old ace-assign `AttemptCoordinator`/journal identity).
+- Remove the second-commander proposal surface: the `proposal` CLI command, `Lifecycle::Proposals`, the proposal policy/evaluator, proposal frames, and the publication HITL binding tied to the removed publication authority.
+- Remove managed and TLS `serve` modes: `serve` requires `--operator-only` and fails clearly otherwise.
+- Remove the unused old-lab Root Overseer reverse-address channel: `Lifecycle::Overseer`, the `overseer-send`/`overseer-pending`/`overseer-ack` CLI commands, the default `mo` responder, the `ACE_HITL_OVERSEER_CHANNEL_ROOT`/`/lab/state/overseer-channel` default, and the `[decyzja]`/`[pytanie]`/`[info]` response policy. Generic HITL transport and the ready lifecycle surface are unchanged; there is no replacement queue or relay for this role policy.
+- Remove the now-dead `LifecycleCommand::STDIN_READER` constant (`deliver` reads stdin inline) and add a Duty projection regression test covering the answer-delivered pending state and mixed effect visibility.
+
+### Changed
+
+- `LiveClient` keeps the requester-side authenticated boundary operations (`wait`, `status`, `pending`); the lifecycle/relay transport (`Lifecycle::*`) remains for `ace-hitl-hermes`.
+- Drop the now-unused `ace-assign` and `ace-herdr` runtime dependencies (the managed attempt binding required them); re-lock the workspace Gemfile.lock locally.
+
 ## [0.17.0] - 2026-10-16
 
 ### Added

data/README.md

@@ -1,137 +1,80 @@
 # ace-hitl
 
-`ace-hitl` manages ACE human-in-the-loop (HITL) events in `.ace-local/hitl/`.
+Human-in-the-loop (HITL) event files for ACE agents and operators.
+
+> **State owner:** `.ace-local/hitl/` -- HITL event markdown files owned by
+> `ace-hitl`. Other tools must not write there directly. The agent event
+> history is local and untracked. The canonical flow is
+> [docs/lab-flow.md](../docs/lab-flow.md).
 
 Canonical workflow and skill for agents:
 
 - Workflow: `wfi://hitl`
 - Skill: `as-hitl`
 
-## Commands
-
-- `ace-hitl create` creates a HITL event
-- `ace-hitl ask` asks a human via HITL and forwards the request through a provider adapter (`--provider`, default `lab`); ONE operation: local event + relay request through the authenticated boundary (`--assignment/--attempt/--project` managed binding, effect callback flags)
-- `ace-hitl list` lists HITL events with filters (`--scope current|all`, all statuses by default)
-- `ace-hitl show` renders event details, path, or raw content (`--scope current|all`)
-- `ace-hitl update` updates frontmatter, answer content, and folder location
-- `ace-hitl wait` polls a specific HITL event until answered (`--poll-every`, `--timeout`)
-- `ace-hitl deliver` answers a pending relay request from stdin (configured transport operation through the boundary); executes the declared effect callback (non-OTP kinds)
-- `ace-hitl consume` consumes one own relay request's answer (indefinite by default; `--timeout` bounds only the local wait)
-- `ace-hitl cancel` cancels with an audited reason (the only way to abandon a request)
-- `ace-hitl pending` / `ace-hitl states` / `ace-hitl duty` transport projections (pending, public lifecycle records, pending + escalated)
-- `ace-hitl serve` runs the authenticated store boundary service (peer-credential UNIX socket; trusted grants authorize the transport)
-
-Multi-user HITL state (spec 8wq.t.34i) is the PRIVATE state of the
-`ace-hitl serve` boundary: identity comes from kernel peer
-credentials, transport authority from the trusted grants document,
-and OTP secrets are held in service memory only — never in files,
-logs, or projections.
-- `ace-hitl overseer-send` / `ace-hitl overseer-pending` / `ace-hitl overseer-ack` the Overseer reverse-address response channel
-
-`ace-hitl` is a blocker-resolution tool, not a global dashboard:
-
-- linked worktree default: local (`--scope current`)
-- main checkout default: operator view (`--scope all`)
-
-Use `ace-overseer status` for a global worktree dashboard.
-
-## Provider adapters
-
-`ace-hitl ask --question ... --assignment ... --attempt ...` creates a scoped
-request through authenticated IPC. The managed coordinator verifies the exact
-active native owner and reverse address; caller environment variables cannot
-supply authority. No Lab daemon or Work binding is used.
-
-`Ace::Hitl::LiveClient` provides explicit in-process `deliver`, `watch`, `wait`,
-`status`, `pending`, and signed `reconcile`. `watch` returns a thread owned by
-its calling agent. Native delivery commits an incarnation-bound event through
-Herdr Inbox and registers it through Assign. Queue acceptance and wake do not
-prove consumption. Only an event-bound signed native observation verified by
-Herdr and journaled by Assign completes delivery. Business callbacks have
-separate authorization and receipts and are never rerun by native retries.
-
-Pane-less `wait --request ID` consumes an existing authorized request over IPC;
-it neither creates a native target nor proves a business effect. OTP answers
-use that protected path with their authorized operation; no OTP bytes or OTP
-hash enter the shared envelope, folder or native inbox.
+## What exists today
+
+`ace-hitl` manages HITL events stored as markdown files under `.ace-local/hitl/`.
+An event records a question or decision, its context (assignment/step), its
+status, and the answer — or a report (work done / error) that never awaits an
+answer. This is the local, file-based path; it needs no
+listener, daemon, or database.
+
+| Command | Purpose |
+|---------|---------|
+| `ace-hitl create` | Create a question event (kind, questions, assignment/step context, resume instructions) or a report event (`--type report --result success\|error --body ... --task ...`) |
+| `ace-hitl list` | List events with status/kind/type/tag/folder/scope filters |
+| `ace-hitl show` | Render event details, path, or raw markdown |
+| `ace-hitl update` | Update frontmatter, write an answer, or move the event |
+| `ace-hitl wait` | Poll one question event until it is answered (reports are rejected) |
+| `ace-hitl send` | Deliver an event through the configured adapter routes; per-route results retained on the event, redelivery retries undelivered/unknown routes |
+
+`ace-hitl` is a blocker-resolution tool, not a global dashboard: in a linked
+worktree it defaults to local (`--scope current`); in the main checkout it uses
+the operator view (`--scope all`). Use `ace-overseer status` for a worktree
+dashboard.
 
 ## Examples
 
 ```bash
-ace-hitl list
-ace-hitl list --scope all
-ace-hitl create "Which auth strategy?" --kind decision --question "JWT or sessions?"
-ace-hitl ask --question "Proceed with deploy?" --assignment assign685 --attempt attempt685 --effect-arg /bin/false --effect-cwd /tmp
-ace-hitl ask --question "Proceed with deploy?" --provider lab --assignment assign685 --attempt attempt685
+ace-hitl create "Which auth strategy?" --kind decision \
+  --question "JWT or sessions?" --assignment abc123 --step 020
+ace-hitl create "Work done" --type report --result success \
+  --body "Implemented JWT login" --task 8xg.t.sbz.1.0
+ace-hitl list --status pending
+ace-hitl list --type report
 ace-hitl show abc123 --content
-ace-hitl show abc123 --scope current
 ace-hitl update abc123 --answer "Use JWT with server-side refresh tokens."
-ace-hitl wait abc123
-ace-hitl update abc123 --answer "Use JWT with server-side refresh tokens." --resume
+ace-hitl update abc123 --move-to archive
+ace-hitl wait abc123 --poll-every 600 --timeout 14400
 ```
 
-## Testing
-
-This package has deterministic fast and scoped integration tests.
-
-- Deterministic test coverage lives under `test/fast/`.
-- This migration does not introduce `test/feat/` or `test/e2e/` for this package.
-
-Verification commands:
-
-- `ace-test ace-hitl`
-- `ace-test ace-hitl all`
+## Transport boundary
+
+> The installed Lab provider and the attempt-bound managed HITL path (`ask`,
+> provider assignment binding, native Herdr delivery, managed/TLS `serve`) were
+> removed with the old authority model. The local file-based HITL events above
+> remain the active path. The lifecycle/relay transport (`Lifecycle::*`) and
+> its commands remain for `ace-hitl-hermes` and other adapters; `serve` supports
+> `--operator-only` only. Second-commander proposals are removed as well.
+>
+> **L2 status:** report/question distinction, recipient addressing
+> (`--to`, `reply_to`), adapter-route delivery (`send` with the built-in
+> terminal adapter and `ace-hitl-hermes` as the hermes adapter), and
+> retention/redelivery of undelivered messages (per-route records on the
+> event; `send` retries undelivered/unknown routes, `--force` redelivers
+> with the same case ID) are available. `ace-hitl-hermes` remains an
+> adapter package; tmux/Herdr remain transports.
 
-## Ownership Boundary
-
-`ace-hitl` owns HITL-specific event semantics and markdown contract.
-
-`ace-support-items` remains generic support infrastructure and should not absorb HITL-specific domain behavior.
-
-## Unassigned operator questions
-
-`ace-hitl operator-question ID --project lab-config --question "Which option?"`
-creates a nonsecret question under an explicit installed operator grant. An
-optional `--plan` adds question context; `--options A,B` supplies bounded choices.
-The owner binds the exact Captain-visible body including this context and choices. It does not create an Assign execution,
-request a command, grant a decision, or permit OTP/effects. Stable IDs support
-exact retries after lost responses, restart and consumption; changed content,
-principal, project or context is refused. `ace-hitl read ID` returns authenticated
-nonsecret facts; existing `consume ID` retrieves the requester's answer and
-replays its terminal receipt.
-
-The public Ruby client exposes `operator_question(id:, project:, question:,
-plan: "", options: [])`, `read`, and the existing pending/deliver/consume/cancel
-methods. The request records the actual kernel peer UID/name. No caller can supply
-requester attribution, assignment, attempt, OTP, effect or publication fields.
-Secret-shaped questions, context, choices and answers are refused.
-
-An operator-only service uses the existing owner and Unix protocol:
+## Testing
 
-```sh
-ace-hitl serve --operator-only --group ace-hitl-project \
-  --socket /run/ace-hitl-project/lifecycle.sock --store-root /var/lib/ace-hitl-project \
-  --grants-path /etc/ace-hitl-project/authorization.yml
+```bash
+bin/ace-test ace-hitl
+bin/ace-test ace-hitl all
 ```
 
-The root-controlled grants document must explicitly name `hitl.service_uid`,
-`hitl.operator_uids`, `hitl.transport_uids` and each UID's exact project list in
-`authorization.principals`. Operator grants never interpret an empty project list
-as all projects. Existing trusted-file ownership/traversal checks apply. The
-operator-only binding refuses managed requests and requires no Assign journal.
-Admission and requester grants are checked again on reads, answer transitions,
-retries and terminal replay; transport delivery retains its independent project
-grant. Revocation preserves request and terminal history. Operator questions
-cannot be consumed as native execution or authorized-operation claims.
-
-`ping` advertises the supported `request_contexts` (`managed` and/or
-`operator-question`), not a grant to create or execute work. Hermes project
-routes may require `request_contexts: ["operator-question"]` at startup. The
-shared contract uses a closed tagged union of managed execution requests and
-operator questions; neither missing IDs nor an unknown schema select a fallback.
-
-One Unix UID with both roles is one OS trust domain. Use a distinct transport
-principal where Captain reply isolation is required. Source tests using one UID
-for both roles do not prove that isolation. Domain adapters must separately
-preserve legacy unresolved host questions and prove the installed group handoff;
-this API never migrates or deletes that legacy history.
+## Ownership boundary
+
+`ace-hitl` owns HITL event semantics and the markdown contract.
+`ace-support-items` remains generic support infrastructure and does not absorb
+HITL-specific behaviour.