@phyzess/pappra 0.1.0-beta.13 → 0.1.0-beta.18

package/README.md

@@ -20,23 +20,32 @@ curl -fsSL https://raw.githubusercontent.com/phyzess/pappra/main/examples/minima
 npx @phyzess/pappra@beta init --config ./minimal-choices.json --json
 
 # Apply the same choices. Apply also installs and binds a durable runtime copy,
-# so this converges with exit code 0; add --no-runtime to leave it pending.
+# so this converges with exit code 0; add --no-runtime to skip that work and
+# leave a still-required runtime action pending.
 npx @phyzess/pappra@beta init --config ./minimal-choices.json --apply --json
 npx @phyzess/pappra@beta doctor --json
 ```
 
 `examples/minimal-choices.json` is complete for a host-free, no-graph, single-directory workspace. The example intentionally has no repositories or optional hosts.
 
-For a non-interactive derived setup, `npx @phyzess/pappra@beta init --yes --apply --json` derives repositories, knowledge sources, code engine, validation commands, excludes and hosts from discovery. `--print-choices` prints that `pappra/init-choices/1` document and writes nothing, and `init --json` without selections returns the discovery candidates plus the suggested document. JSON mode never prompts; only a TTY without selections opens the wizard.
+For a non-interactive derived setup, `npx @phyzess/pappra@beta init --yes --apply --json` derives repositories, knowledge sources, code engine, validation commands, excludes and hosts from discovery; with an existing workspace plus `--reconfigure` it keeps the current represented selections instead of deriving new ones, and `--print-choices --reconfigure` prints those current choices. `--print-choices` normally prints the derived `pappra/init-choices/1` document and writes nothing, and `init --json` without selections returns the discovery candidates plus the suggested document. JSON mode never prompts.
 
 Development from a checkout works the same way: `pnpm install --frozen-lockfile`, `pnpm build`, then invoke `dist/cli/main.js` by absolute path from the target workspace.
 
-`init --apply` also installs a durable runtime copy of the executing package under the
-Pappra data directory and binds it in `machine.json`, so an npx/dlx bootstrap survives
-cache eviction and the command converges with exit code `0`. Pass `--no-runtime` to leave
-that action pending instead; the result is then `ok:true` with
-`status:"external-actions-pending"` and a nonzero exit, which is a partial configuration
-write rather than a claim that a runtime exists.
+`init` never writes during planning. `--apply` writes the planned files through a managed
+journal. By default it then verifies an existing runtime for the workspace's recorded runtime
+version and reuses it when the manifest, package contents, executable and smoke check all pass;
+otherwise it packs and installs the current package under the Pappra data directory and binds
+that runtime in `machine.json`. So an npx/dlx bootstrap survives cache eviction. If the current
+package version differs from the workspace target, a previously installed verified target
+runtime may still be reused; when none is reusable the configuration is applied and runtime
+setup fails afterwards with a nonzero exit. Pass `--no-runtime` to suppress runtime verification,
+installation and binding for that invocation. When a runtime action is still required afterwards,
+the configuration is applied, that action stays pending, and the result is `ok:true` with
+`status:"external-actions-pending"` and exit `0` for the requested configuration-only work.
+A workspace that already has a bound runtime for its target and needs no file changes can instead
+report `ok:true`, apply status `no-changes` and exit `0`; `initComplete` then stays `false`,
+because that invocation verified no runtime.
 
 For a new workspace or a new machine, `pappra onboard --dry-run --json` shows the plan and
 the host version matrix; `pappra onboard --yes --apply-host --json` applies config, runtime
@@ -51,12 +60,101 @@ npx @phyzess/pappra@beta runtime status --json
 npx @phyzess/pappra@beta runtime verify --json
 ```
 
-A workspace that already has a valid `.pappra/workspace.json` is never rewritten silently.
-`init --yes --reconfigure --apply` rebuilds it from discovery (for example to move the
-recorded runtime version to the running package), backing the previous file up under
-`.pappra/local/backups`. Apply also reports advisory `nextActions`: `pappra code prepare`
-for a selected code engine and `pappra docs scan --apply` to register documents from the
-configured knowledge sources.
+Runtime content hashes now use UTF-8 byte ordering, independent of system locale.
+Beta.15 uses `pappra/runtime-manifest/2` with an explicit digest scheme and does not
+migrate old beta state. Unsupported formats are reported as incompatible, separately
+from corrupted content. Use the current package with `init --reconfigure --apply` to
+initialize its runtime; existing state is preserved until explicitly removed.
+Verification never rewrites a manifest to adopt an unexpected digest.
+Runtime removal refuses unknown cross-workspace references;
+`--force` is an explicit override after checking other workspaces.
+
+Interrupted installations can be inspected and recovered explicitly:
+
+```sh
+pappra repair --root /path/to/workspace --json
+pappra repair --root /path/to/workspace --apply
+pappra repair --runtime-version 0.1.0 --json
+pappra repair --runtime-version 0.1.0 --apply
+```
+
+`repair` finds the nearest workspace from a subdirectory and previews incomplete journals plus
+install, knowledge and checkpoint writer locks. Add `--install-id <uuid>`
+to select one incomplete journal. `--apply` reclaims a lock only when its recorded owner is
+provably dead, rolls back files with verified ownership, and restores journaled reconfiguration
+backups. For runtimes it removes only journal-owned staging, or finalizes an already published
+copy whose manifest and contents still match, without executing the runtime. Live or unknown
+owners, modified files, invalid journals and unproven backup paths are preserved and reported.
+Reconfiguration holds the same workspace lock and journal through replacements and creations.
+Files created before their inode reached the journal remain in place, with an explicit
+preservation audit; their ownership is not adopted. Lock publication is atomic, so a new
+writer never exposes an empty named owner record. `doctor` reports dead or unknown writers
+and points to the same repair surface.
+
+For copied or moved beta workspaces, stop every affected writer before explicitly starting
+fresh local state; this preserves the old bytes instead of migrating machine bindings:
+
+```sh
+pappra repair --reset-local --json                 # read-only plan
+pappra repair --reset-local --all-writers-stopped --apply
+pappra init --yes --apply
+```
+
+The old tree remains under ignored `.pappra/local-archive/<id>`. Reset has its own recoverable
+journal and refuses verified live owners. The stopped-writers flag is an operator assertion
+for unknown/imported ownership, not process stop proof. For a single malformed or empty lock,
+`repair --quarantine-unowned-locks --apply` provides the same explicit stop-all-writers
+precondition and preserves the lock plus a receipt in private quarantine. Never use either
+escape while a writer is alive or paused.
+
+Every first private-state write creates `.pappra/local/.gitignore` with a final `*`
+rule, including writes performed without init. Checkpoint payloads retain tracked
+diffs, but untracked files contribute only their path, object type and content digest;
+their contents and symlink target text are not copied into the checkpoint.
+
+A workspace that already has a valid `.pappra/workspace.json` is never rewritten silently: a
+plain `init` reuses it and only plans missing local state. `--reconfigure` is the explicit opt-in
+that re-derives `workspace.json` from the current selections, and it preserves the workspace
+identity, `extensions`, `continuity`, custom validation entries with their original checkout
+binding, and existing local machine settings; the previous file is backed up under
+`.pappra/local/backups`. `--yes --reconfigure` therefore keeps the represented selections instead
+of re-deriving them from discovery, while `--config <file> --reconfigure` applies explicitly
+supplied edits.
+
+Knowledge sources and the document destination are different settings. `knowledge.sources` lists
+existing rules and documents that stay in place and are only registered later by
+`pappra docs scan --apply`; `knowledge.newDocuments` is merely the destination for future
+authored documents and is not created by `init`. Apply also reports advisory `nextActions`:
+`pappra code prepare` for a selected code engine and `pappra docs scan --apply` to register
+documents from the configured knowledge sources.
+
+### Interactive init
+
+A TTY opens the full wizard only when selections are actually needed: a plain `init` in a
+workspace that already has a valid configuration reuses it and asks only for missing local
+state, and `--reconfigure` is what opens the editor. The workspace name, new-document
+destination and excludes are editable text fields seeded with the current or derived value, so
+the suggested value is visible and can be changed before submitting; an invalid entry is
+reported at that field and re-asked. Repository and knowledge sections pre-select the current
+choices and offer **Add existing repository…** and **Add existing knowledge file or folder…**.
+That action inspects only the workspace-relative path you type: it checks portability,
+canonical containment, workspace exclusions, nested-workspace boundaries, unsafe symlinks and,
+for repositories, that the path is the exact Git checkout root. It never scans ancestors or the
+home directory, never reads document bodies, and empty knowledge folders are valid sources.
+Advanced preferences are opt-in (`Keep current advanced settings` is the default), sections after
+the first offer `Back` alongside `Review selections`, the review screen can reopen one section, and
+`Cancel` (also Ctrl-C) discards the draft before anything is written. Graph/symbols/preparation
+choices, validation candidates and host declarations are recorded preferences only: `init` does not
+install, index, execute or wire them.
+
+A TTY run that collected selections without `--apply` prints the plan and then asks one
+confirmation when configuration writes are planned; declining exits `130` with no files written.
+`--apply` never prompts, `--config` without `--apply` stays a preview even on a TTY, and an empty
+read-only plan performs no runtime work and asks nothing. `--print-choices` prints the
+`pappra/init-choices/1` document and writes nothing, `--config` reads that document,
+`--yes`/`--no-interactive` derive selections non-interactively, and `--json` never prompts.
+Exit `0` means the requested work completed. `--no-runtime` deliberately defers runtime work
+and keeps `initComplete:false`; a failure in a requested runtime step returns nonzero.
 
 Optional examples have prerequisites rather than generated files: code-graph and
 host commands require the selected external CLI/support, and collaboration
@@ -64,6 +162,22 @@ requires an explicit controller. `--controller pi-rpc` is the host-directs/Pi-ex
 path, verified end to end against Pi 1.3.0; see [Pi RPC collaboration](docs/pi-rpc.md).
 They are not needed for the core workflow above.
 
+For a fresh controller-owned visible Pi TUI, use `pappra session plan` then
+`pappra session start --config <absolute-file>`. The controller preserves normal
+Pi configuration, selects an explicit OpenRouter model, journals terminal input
+and exposes a private status/fence/stop endpoint. See
+[managed Pi sessions](docs/managed-pi-session.md). Opt-in SDK mode pins Pi 1.4.0
+and observes native queues and dialogs within its owned runtime. External writers
+and unowned descendants remain outside that proof. [Controlled resume](docs/managed-pi-resume.md)
+checks process death and current task authority before reopening an idle session;
+[provider diagnostics](docs/managed-provider-diagnostics.md) retain redacted transport details.
+Threshold-driven checkpoint
+and bundle capture are available through [automatic handoff](docs/automatic-handoff.md);
+ownership transfer still requires the existing supported transition contract.
+[Role plans](docs/collaboration-role-plan.md) support an optional planner before
+independent writers and a final reviewer; [event orchestration](docs/collaboration-role-orchestration.md)
+dispatches ready assignments and aggregates authoritative results.
+
 ## What it manages
 
 - **Workspace configuration:** `.pappra/workspace.json` and checkout-local `.pappra/local/machine.json`.
@@ -95,7 +209,12 @@ The check runs the source policy, type checks, formatting, deterministic tests a
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.13`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.13`, because pre-release versions are never republished.
+Pappra is development software (`0.1.0-beta.14`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.14`, because pre-release versions are never republished.
+
+The deterministic runner removes inherited `PAPPRA_*` controls and isolates global/system
+Git configuration. Test cases inject required Pappra variables explicitly. Native provider
+acceptance is run separately against its selected test file, rather than enabled by ambient
+opt-in flags during `pnpm check`.
 
 The deterministic suite covers synthetic workspaces, fixtures and local process boundaries. It does not establish real-model behavior, native host callability on every platform, CodeGraph completeness, Windows/Linux parity or production performance. A host adapter version pin is an observed support claim, not proof that a particular native installation will load or run correctly.
 

package/assets/integrations/skills/pappra/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pappra
-description: Use Pappra workspace knowledge, checkpoint/resume, and selected-repository code intelligence from any supported coding agent. Use when a task needs durable handoff context, workspace documents, or bounded code navigation.
+description: Use Pappra workspace knowledge, checkpoint/resume, selected-repository code intelligence, and task-scoped cross-harness collaboration from any supported coding agent. Use when a task needs durable handoff context, workspace documents, bounded code navigation, or a visible/direct multi-agent collaboration workflow.
 ---
 
 # Pappra
@@ -20,15 +20,28 @@ index, or new writer.
    the workspace selected by the current root. Never infer a workspace from an
    unrelated session. `pappra docs scan --apply` registers discovered documents;
    `pappra runtime install --apply` keeps a durable copy of this package.
-5. For a new bounded collaboration request, build an explicit
-   `pappra/collaboration-goal/1` from the user's objective and named choices,
-   run `pappra collab prepare --goal <file> --domain-root <dir>`, admit against a fresh capability
-   card, then use `pappra collab run` with the reviewed controller. `--controller
-pi-rpc` launches a real owned Pi session and is verified for Pi 1.3.0. Never
-   turn prose into identity, approval, or capability claims.
+5. For task-scoped collaboration, read `references/environment.md` first to
+   choose direct versus visible Herdr operation, bootstrap or reuse the
+   receiving instance, and bind its routing identity. Then read
+   `references/collaboration.md` and build the shared strict
+   `pappra/collaboration-goal/1` from explicit choices. The installed CLI accepts
+   `pappra collab prepare --goal <file> --domain-root <dir>`; it has no preview
+   mode, so it mutates task state, claims resources and registers the initial
+   ASSIGN once authorized. MCP `collab_prepare` accepts `{ domainRoot, goal }`
+   and rejects the retired flat objective form. Neither prepares a capability
+   card; derive and preflight actual runtime evidence separately, and notify the
+   already-registered ASSIGN rather than sending a duplicate. Visible peers are
+   the default collaboration channel; the owned Pi `pi-rpc` run remains a
+   separate explicit option, and fixtures are explicit only. Never turn prose
+   into identity, approval, or capability claims.
 
 ## One-request collaboration
 
+Visible collaboration uses `references/environment.md` plus the persisted
+message/notify loop in `references/collaboration.md`. The owned `collab run`
+flow described here is the separate Pi RPC option, not a substitute for a
+visible participant.
+
 `pappra collab prepare --goal <file> --domain-root <dir>` requires an explicit
 shared domain. It validates the canonical domain/tasks/task/private namespace
 before writing any task metadata and again around each write, so a task-root or
@@ -61,6 +74,14 @@ No approval is auto-answered, no cancel is inferred from an acknowledgement, and
 arbitrary PID is adopted. Do not launch a model or real user session without
 the task's explicit authorization.
 
+## Recovery and parallel work
+
+Use `pappra collab work-run --request <abs-request.json>` for a read-only plan and add `--apply` only when the existing assignments, current capability cards, coordinator authority, resource claims and visible participant binding are ready. Work-run notifies only registered participants; it does not create sessions, merge, accept reports, or replay ambiguous delivery.
+
+Use `pappra collab recovery-run --request <abs-request.json>` to inspect one guarded recovery action; add `--apply` only with exact current session/cwd/harness/pane and a digest-pinned task-local binding. Recovery is a bounded single wake, not generic outage recovery: there is no reconnect trigger, hidden worker, approval automation, or replay after an unknown effect.
+
+For an explicitly selected Pi package, `pappra host bundle --host pi --out <new-private-dir> --recovery-config <abs-private-config.json>` exports the recovery extension and its private sibling config. Add `--transition-extension` to export the separate `/collab-transition` command extension. Exports do not install, trust, enable, load, launch, or transfer anything; review and install packages explicitly. Native quiescence and interactive Pi session takeover remain unsupported, and task retirement is not native session archive.
+
 ## Boundaries
 
 - Hooks are local and bounded. They do not read transcripts, run commands,