@naxodev/apnea 0.1.0 → 0.2.1

package/README.md

@@ -20,8 +20,7 @@ only rebinds roles to profile names that already exist.
   `dist/cli.js` with a `#!/usr/bin/env bun` shebang, and npm does not enforce the `engines.bun`
   key. If you install `@naxodev/apnea` globally with only `node` on `PATH`, the `apnea` command
   will fail on first invocation — this is the most likely first-run failure for a new user.
-- **herdr**, for pane-based dispatch. The optional `floating` pane style additionally needs
-  **herdr ≥ 0.7.4** plus the linked plugin (see [`docs/protocol/config.md`](docs/protocol/config.md)).
+- **herdr**, for reusable interactive pane dispatch.
 - **jj or git.** Per [ADR 0007](docs/adr/0007-jj-first-commits.md), if neither is present
   auto-commit is refused.
 - **At least one agent CLI** — `pi`, `claude`, or `codex`.
@@ -53,8 +52,7 @@ Optionally put it on `PATH`, e.g. `ln -s "$(pwd)/dist/cli.js" ~/.local/bin/apnea
 
 ## Sixty-second quickstart
 
-1. `apnea setup` — writes global profiles to `~/.config/apnea/config.json` (and the herdr
-   `apnea` plugin, if herdr is present).
+1. `apnea setup` — writes global profiles to `~/.config/apnea/config.json`.
 2. `apnea start "<goal>"` — starts a run against your working copy.
 3. `apnea status` — a read-only snapshot of where the run stands and what to call next.
 
@@ -88,7 +86,7 @@ of them went stale; a reader could not tell which.
 | `start <goal>`        | `workflow_start`        | `[--allow-dirty] [--slug=name]` _(CLI only)_ | start a run                                                    |
 | `resume` / `abandon`  | `workflow_start`        |                                              | resume or abandon                                              |
 | `status`              | `workflow_status`       |                                              | read-only snapshot                                             |
-| `dispatch <kind>`     | `dispatch_role`         | `[--rework]`                                 | launch a role                                                  |
+| `dispatch <kind>`     | `dispatch_role`         | `[--rework] [--redeliver]`                   | launch or explicitly redeliver a role                          |
 | `wait`                | `workflow_wait`         | `[--poll=<ms>] [--budget=<ms>]` _(CLI only)_ | wait for the pending artifact                                  |
 | `commit [message]`    | `workflow_commit_phase` | `[--done]`                                   | verify + commit phase                                          |
 | `reset-rounds <gate>` | —                       | `[--i-am-human]` _(CLI only)_                | **human only**                                                 |
@@ -96,6 +94,18 @@ of them went stale; a reader could not tell which.
 Prefix with `/` inside Pi (`/apnea status`), or run it as a shell command (`apnea status`).
 `/apnea-start` and `/apnea-status` are short aliases.
 
+`--rework` remains through 0.2.x as a deprecated assertion. Persisted review state selects and
+authorizes rework even when callers omit the flag. Caller input grants authority only for
+ambiguous version-1 plan or code migration. `--redeliver` reuses matching pending ownership without
+advancing the round. Use it only after proving the prior pane is dead; a manual dispatch with no
+pane requires the operator to request redelivery explicitly. Apnea persists whether pending work
+crossed a manual or interactive boundary. Interactive ownership without a saved pane id refuses as
+ambiguous. Legacy null-pane ownership has no safe discriminator and also refuses redelivery.
+Before any redelivery checks or mutations, Apnea reads the pending artifact. A complete artifact
+refuses redelivery and directs the caller to `workflow_wait`; review artifacts count as complete only
+with a valid verdict and legal, schema-valid rework metadata. Malformed or incomplete artifacts
+continue through normal liveness validation.
+
 `reset-rounds` is not a Pi tool. It exists only as `apnea reset-rounds` and `/apnea reset-rounds`.
 Only the CLI gates it — it refuses unless stdin/stdout are a terminal and a human retypes the gate
 key, or passes `--i-am-human`. The slash command has no such gate: `/apnea` is already a human at
@@ -109,14 +119,19 @@ See [`docs/protocol/config.md`](docs/protocol/config.md) for the budget-floor ar
 ### Setup flags
 
 ```text
-/apnea setup              # ~/.config/apnea/config.json from PATH (+ herdr apnea plugin when herdr is present)
+/apnea setup              # ~/.config/apnea/config.json from PATH
 /apnea setup --project    # also .apnea/config.json role→profile only
+/apnea setup --force      # replace profiles; required to replace malformed global JSON
 /apnea setup --agents-md  # also write/refresh an AGENTS.md loop primer at the repo root
 ```
 
-`pane_style` (`regular` default, `floating` opt-in) lives in config; floating needs herdr ≥ 0.7.4
+Setup never silently destroys malformed JSON. Without `--force`, malformed existing global JSON
+is left byte-for-byte unchanged and setup refuses. `--force` atomically replaces it and reports
+the replacement. Malformed existing project config always fails closed.
 
-- the linked plugin — see [`docs/protocol/config.md`](docs/protocol/config.md).
+After upgrading from a version with floating panes, old copied
+`~/.config/apnea/herdr-plugin` files are inert. Apnea does not unlink or delete them; remove that
+directory manually if you no longer need it.
 
 The `@naxodev/pi-apnea` adapter applies Pi-specific role launch behavior. The core package remains
 host-neutral.
@@ -129,8 +144,8 @@ UI in v1.**
 **What you can rely on:** the loop, the artifact contract, and the CLI are implemented, and the
 extension suite is green — CI runs it on every pull request.
 
-**What may still change:** the command surface and config shape may move before `1.0`. This is
-`0.1.0` — breaking changes will land in minor bumps, not patches.
+**What may still change:** the command surface and config shape may move before `1.0`. Breaking
+changes will land in minor bumps, not patches.
 
 **Non-goals for v1:** worktrees, parallel coders, push/PR automation, memory store, native
 CLAUDE.md injection, force-approve, config UI.

package/SECURITY.md

@@ -17,6 +17,38 @@ this tool at a repository.
 - **Planner-authored verify commands execute at the commit gate**, in the project working
   directory, in the same trust domain as the coder writing source. Their output goes to
   `verify.log`.
+- **Git phase commits bypass hooks by design.** Apnea stages into an isolated index, writes and
+  validates the exact tree, creates it with `commit-tree`, then compare-and-swaps the branch ref.
+  Running hooks after validation would let them change the committed tree. Apnea preserves
+  `commit.gpgsign=true` by asking `commit-tree` to sign, but it does not run commit-msg,
+  pre-commit, or post-commit policy hooks. The validated tree is written to the real index before
+  the ref moves, so index failure cannot advance the branch. An unrelated external Git process can
+  still race that real-index replacement; the repository lock coordinates Apnea processes, not
+  arbitrary Git clients.
+- **Repository locks identify owners by PID plus a random token.** The token prevents one owner
+  from deleting a replacement lock. Apnea never reclaims dead or malformed locks automatically:
+  it reports the validated lock path and requires manual cleanup after the user verifies no owner
+  remains. PID reuse can keep a dead lock looking live because there is no portable
+  process-creation identity across supported platforms; this also fails closed. Global setup waits
+  only when the recorded PID is currently live; it never retries stale or malformed ownership.
+- **Setup serializes account-global configuration and role resources.** Every setup holds one
+  same-user lock keyed by the canonical account home for its full read/merge/write and role-agent
+  materialization. Setup takes this global lock before an optional repository lock. Global config
+  replacement is atomic, rejects symlink components, and fsyncs the file and parent directory
+  where the platform supports it. Malformed global JSON remains byte-for-byte unchanged unless a
+  human passes `--force`; the result explicitly reports a forced replacement. Malformed project
+  config always fails closed.
+- **Persisted inputs are bounded regular UTF-8 files.** Config, state, setup `AGENTS.md`, and
+  workflow artifacts are opened once and read through the descriptor. Apnea rejects non-regular
+  files, invalid UTF-8, and inputs over 1 MiB before parsing. Descriptor checks avoid a separate
+  stat/read race. Existing project and account-home symlink confinement still applies.
+- **State-owned artifact paths cannot escape the repository.** `pending_artifact`,
+  `current_phase_package`, and `current_code_review` must be relative paths below `.apnea/`.
+  Absolute paths, NULs, backslashes, empty components, and `.` or `..` components make state
+  corrupt.
+- **Project-path checks reject existing symlink components but cannot provide `openat` semantics.**
+  Node does not expose a portable directory-descriptor traversal API, so a hostile same-user
+  process can still race a checked parent component before the final filesystem operation.
 
 See [`docs/protocol/config.md`](docs/protocol/config.md) (Trust model section) and
 [`docs/adr/0006-config-trust-model.md`](docs/adr/0006-config-trust-model.md) for the full

package/briefs/orchestrator.md

@@ -13,11 +13,11 @@ You schedule an Apnea **Run**. You do not implement product code, edit app sourc
 1. Start run (clean tree unless allow-dirty / resume). **Start only writes state — do not stop here.**
 2. Immediately dispatch **planner** (`kind=plan`) → wait for plan artifact.
 3. Dispatch **reviewer** (plan review) → wait for verdict.
-4. On `CHANGES_REQUIRED`, re-dispatch planner then reviewer (new round).
+4. On `CHANGES_REQUIRED`, dispatch planner then reviewer. Persisted state advances the round.
 5. On `APPROVED`, dispatch planner for **phase package**.
 6. Dispatch **coder** with phase package path.
 7. Dispatch **reviewer** (code review) → wait.
-8. On `CHANGES_REQUIRED` with `rework: code` or no rework field, re-dispatch coder with `rework=true`, then reviewer.
+8. On `CHANGES_REQUIRED` with `rework: code` or no rework field, dispatch coder, then reviewer. Persisted state advances the round.
 9. On `CHANGES_REQUIRED` with `rework: phase_package`, dispatch planner for the revised phase package, then coder and reviewer. The package dispatch advances the review round automatically.
 10. On `APPROVED`, commit phase (run verify commands first).
 11. Repeat from phase packaging until planner reports no remaining phases.
@@ -26,6 +26,7 @@ You schedule an Apnea **Run**. You do not implement product code, edit app sourc
 ## Rules
 
 - One outstanding Dispatch at a time.
+- Never infer or authorize rework from caller input, except an explicit `rework=true` assertion for ambiguous version-1 plan or code state. `workflow_wait` persists every new required target, and `dispatch_role` consumes it.
 - Read verdicts only from artifact front-matter.
 - Never push remotes or open PRs.
 
@@ -40,7 +41,7 @@ don't, the orchestrator still owns recovery.
    - Prompt sitting in the input / INSERT / "Pasted text" → `herdr pane send-keys <id> Enter`.
    - Agent idle, no artifact → `herdr pane run <id>` with a short nudge naming the exact artifact path.
    - Agent working / API retrying → `workflow_wait` again (do not re-dispatch yet).
-   - Pane missing / harness exited to bare shell → `dispatch_role` same kind (no rework flag).
+   - Pane missing / harness exited to bare shell → `dispatch_role` same kind with `redeliver=true` (no rework flag).
 3. Only escalate after recovery failed twice, or on: round cap, dirty reviewer tree, illegal step, VCS confusion.
 
 ## Escalate (after recovery fails)