@naxodev/apnea 0.2.0 → 0.2.2

package/README.md

@@ -86,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**                                                 |
@@ -94,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,9 +121,14 @@ See [`docs/protocol/config.md`](docs/protocol/config.md) for the budget-floor ar
 ```text
 /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
 ```
 
+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.
+
 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.

package/SECURITY.md

@@ -17,6 +17,42 @@ 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.** Apnea reclaims a valid dead
+  owner after the grace period. An atomic `<lock-path>.reclaim` directory serializes stale
+  removers across their token check and canonical rename, preserving every replacement owner.
+  A crashed remover can leave this guard behind. Apnea never reclaims the guard automatically:
+  doing so would introduce the same ownership race. If an error reports a stranded guard, stop
+  all Apnea processes using that lock before manually removing the reported guard path.
+  Malformed locks require manual cleanup after verifying that 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)