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

package/assets/integrations/skills/pappra/references/environment.md

@@ -0,0 +1,360 @@
+# Visible collaboration workflow
+
+Choose the collaboration channel before preparing a task, and keep the two
+environment choices distinct from the work itself: a channel decides where a
+participant runs and how messages reach it. It never grants permissions,
+capabilities, ownership, or task success. Existing guidance starts after
+participants exist; this reference covers the entry path from a new authorized
+request to a bound, ready receiving instance.
+
+## 1. Detect the environment, not the installed tools
+
+Inspect only the non-sensitive Herdr markers and caller IDs, for example:
+
+```nu
+$env.HERDR_ENV? == '1'
+```
+
+- **False or absent** — use **direct mode**: keep the current session as
+  coordinator and use the host's own supported tools. Do not query a Herdr
+  server, inspect its focus, split panes, or open a terminal merely because a
+  `herdr` binary is installed. A binary, an open window, or an old pane ID in a
+  task record proves no caller affiliation. Do not print the process
+  environment.
+- **True** — you are inside a Herdr caller. Read that installation's own
+  `herdr --skill` and the relevant `--help` before acting (pane ids and flags
+  are version-sensitive), then resolve the current caller, for example
+  `herdr pane current --current`. If the claim cannot be resolved
+  unambiguously, record **herdr unavailable** with the reason and fall back to
+  direct mode only when the user's instructions allow it.
+- The UI-focused pane is never a fallback. Do not spoof `HERDR_*` values.
+- If the task requires visible delivery and it is unavailable, report the
+  blocker. Do not start a hidden duplicate of the required participant.
+
+A failed inherited `pane current --current` lookup is not enough to conclude
+that native collaboration is unavailable. For a moved pane or a persistent
+app-server with stale inherited context, inspect the current task's known
+caller binding and the named live agent metadata. An unambiguous task-bound
+caller can use `pane current --pane <id>` and Pappra's `--caller-pane` route.
+Compare the actual harness, cwd and reported session where available; never
+choose a pane merely because it is focused. If identity remains ambiguous,
+report that exact gap and do not dispatch. Route evidence is not process proof.
+
+`pappra collab message notify` supports two caller routes. The default requires
+the inherited Herdr context; `--caller-pane <id>` names the sender pane
+explicitly for hosted or stale inherited contexts. Either way the pane is
+routing evidence, not process authentication, and recorded delivery evidence
+stays `process_affiliation: "not-established"`.
+
+## 2. Decide participants and bootstrap the receiving instance
+
+Pick participants, roles, harness, and configuration from the task rather than a
+fixed agent count. Everyone can implement, review, or verify; assign by need.
+
+Reuse an existing peer only when all of the following match what the task will
+bind: current agent name, pane, harness, cwd, native session (where the host
+reports one), and the capabilities the assignment will require. Otherwise, when
+a new visible participant is authorized, create a **sibling** shell pane with
+the task's cwd and the installed layout/`--no-focus` options you verified above,
+start the intended interactive agent there, and keep the user's focus unchanged.
+Do not add worktrees, workspaces, or tabs just to get a pane, and never take over
+an arbitrary idle pane.
+
+### One-time bounded discovery contact
+
+A newly started interactive instance has not told you its identity yet. Before
+any task preparation that depends on it, make exactly **one** bounded,
+read-only discovery contact through the installed visible tool (for example the
+installed `herdr agent prompt` command; confirm its syntax from
+`herdr --help`/`--skill`). Ask only for:
+
+- the agent/host name and harness actually running;
+- the exact native session identity the host accepts (or an explicit "unknown"
+  when the host cannot report one);
+- the actual cwd and configuration/model in use;
+- where the instance can leave a bounded native evidence file (for example a Pi
+  session JSONL path) if that evidence route exists.
+
+State explicitly in that contact that it is a read-only identity handshake: do
+not start implementation, do not answer approvals, do not change settings, and
+reply with the identity packet only. This contact is **bootstrap**, not a
+product notification and not an ASSIGN. It must be clearly separate from normal
+`COLLAB_MESSAGE` delivery, which needs a binding that does not exist yet.
+
+If that first contact route is unavailable (direct mode without a visible
+channel, missing host capability, refused prompt), report the concrete blocker.
+Do not fabricate a runtime card, assume a session identity, or launch an owned
+child as a stand-in for the visible participant.
+
+Starting and contacting the interactive instance is not a readiness check and
+not permission to dispatch source work. Do not send an implementation prompt at
+this point, and do not substitute the isolated pilot launcher or bypass host
+approvals. Preserve the daily native model, tools, MCP, hooks, and permission
+settings.
+
+## 3. Bind routing metadata
+
+Record the observed routing identity in the existing task-local binding
+`pappra/collab-binding/1`. Use the discovered values; use JSON `null` (not a
+quoted string) only when the host genuinely cannot report a native session. A
+null/unknown worker session can be recorded for routing, but it cannot be bound
+to an admitted work assignment: the goal schema requires an exact assignee
+session, so report the identity blocker instead of preparing work for an
+unknown instance.
+
+```json
+{
+  "schema": "pappra/collab-binding/1",
+  "task_id": "<task-id>",
+  "task_root": "/absolute/domain/tasks/<task-id>",
+  "channel": "herdr",
+  "participants": [
+    {
+      "agent_id": "<coordinator-agent>",
+      "harness": "<codex|pi|claude>",
+      "cwd": "/absolute/coordinator/cwd",
+      "herdr_agent": "<named-coordinator-agent>",
+      "pane_id": "<wN:pN>",
+      "native_session_id": "<exact-coordinator-session>"
+    },
+    {
+      "agent_id": "<worker-agent>",
+      "harness": "<codex|pi|claude>",
+      "cwd": "/absolute/receiving/cwd",
+      "herdr_agent": "<named-worker-agent>",
+      "pane_id": "<wN:pN>",
+      "native_session_id": "<exact-worker-session-or-null>"
+    }
+  ]
+}
+```
+
+Placeholders such as `<task-id>` and `<exact-worker-session>` are literal
+substitution points, not values. A pane ID is not a native session ID, and this
+binding is routing metadata, not a second ownership store and not proof that a
+native session exists. Revalidate it before later sends, resume, or handoff.
+
+## 4. Prepare the task and admit the new assignment
+
+`pappra collab prepare` is **not** a preview command: it has no plan/apply mode.
+With explicit operator/agent authorization it writes the private task record and
+prepared files, claims the listed resources, and registers the initial
+`ASSIGN`. Do not run it expecting a dry run, and do not treat the message-level
+`send`/`notify` plan behavior as applying to preparation. Resource, message,
+binding, handoff, and recovery commands are the ones with plan/apply modes; see
+`references/collaboration.md`.
+
+```sh
+# Mutates task/prepared state and claims. Requires explicit authorization.
+pappra collab prepare \
+  --goal /abs/example/goal.json \
+  --domain-root /abs/example/domain
+```
+
+Preparation creates no declared capability template or card. If you need a
+derivation template, write one yourself from the assignment's expected
+capabilities and mark it clearly as declared, for example:
+
+```json
+{
+  "schema": "harness-collab/capabilities/1",
+  "agent_id": "<worker-agent>",
+  "session_id": "<exact-worker-session-or-null>",
+  "harness": "<pi|codex|claude>",
+  "surface": "cli",
+  "configuration_id": "<observed-configuration>",
+  "cwd": "/absolute/receiving/cwd",
+  "observed_at": "<ISO time from actual evidence>",
+  "evidence_level": "declared",
+  "skills": [],
+  "tools": [{ "id": "<expected-tool>", "state": "declared" }]
+}
+```
+
+A declared template is not evidence and cannot authorize a launch. Derive a
+runtime card from evidence the receiving instance actually produced (native
+session/events), and save only the returned `card`; derivation prints a result
+wrapper and writes nothing:
+
+```nu
+# Literal example values: substitute the real harness and absolute paths.
+let harness = "pi"
+let assignment = "/abs/example/assignment.json"
+let template = "/abs/example/card.declared.json"
+let execution = "/abs/example/execution.json"
+let session = "/abs/example/pi-session.jsonl"
+let deriveArgs = [
+  'collab' 'capabilities' 'derive'
+  '--harness' $harness
+  '--assignment' $assignment
+  '--template' $template
+  '--execution' $execution
+  '--session' $session
+  '--json'
+]
+let derived = (^pappra ...$deriveArgs | from json)
+if $derived.status != 'derived' { error make {msg: $"derive refused: ($derived.status)"} }
+$derived.card | to json | save --raw /abs/example/card.runtime.json
+```
+
+For Codex or Claude replace the session flag with the events flag accepted by
+the installed command (`pappra collab capabilities derive --help`), and set
+`--harness` to the participant's actual harness. `save --raw` refuses to
+overwrite, so use a new path. Observation time and
+freshness come from the native evidence; replaying old artifacts does not
+refresh them. If the evidence route does not exist, record the blocker instead
+of inventing a card, then check reported readiness:
+
+```sh
+pappra collab preflight \
+  --assignment /abs/example/assignment.json \
+  --capabilities /abs/example/card.runtime.json --json
+```
+
+Ready is not authorization, locking, or dispatch. A declared, stale,
+mismatched, or missing-evidence card stays refused; fix the evidence or report
+the gap.
+
+## 5. Dispatch once and return a correlated result
+
+Preparation already persisted the initial `ASSIGN`. Do not send a second ASSIGN
+for the same attempt. Locate the exact registered message by its own fields
+(current `task_id`, `subtask_id`, `attempt`, `owner_epoch`, recipient, and input
+revision) and read it back through the product:
+
+```nu
+# Literal example paths: replace them with the actual prepared file and values.
+let prepared = (open /abs/example-domain/tasks/example-task/p10/prepared.json)
+let record = (open ($prepared.task_root + "/task.json"))
+let assignEntries = ($record.messages | where { |m| $m.type == "ASSIGN" and $m.subtask_id == $prepared.subtask_id and $m.attempt == $prepared.attempt and $m.to.agent_id == "worker-agent" and $m.to.session_id == "worker-session" })
+if ($assignEntries | length) != 1 { error make {msg: "expected exactly one prepared ASSIGN for this attempt"} }
+let registered = (pappra collab message read --task-root $prepared.task_root --message-id $assignEntries.0.message_id --json | from json)
+if $registered.message.body.input_revision != $prepared.prompt_digest { error make {msg: "prepared ASSIGN input mismatch"} }
+if $registered.message.body.assignment_digest != $prepared.assignment_digest { error make {msg: "prepared ASSIGN digest mismatch"} }
+```
+
+`message read` returns the full envelope and its recorded/applied state. Send
+additional `message send --apply` envelopes only for a genuinely new bounded
+assignment (for example a later attempt) or a message that is not already
+persisted. Then send exactly one pointer-only notification for that registered
+message:
+
+```sh
+# Literal example values: substitute the real task root, message id, binding and pane.
+pappra collab message notify --task-root /abs/example/domain/tasks/example-task \
+  --message-id msg-example-assign \
+  --binding /abs/example/binding.json --caller-pane w9:p1 --apply
+```
+
+Never loop notifications, never use `--wait`, and never treat `submitted` as
+consumption or acceptance.
+
+The receiving instance verifies the pointer digest and **its own** exact
+identity before working: its `to.agent_id`/`to.session_id` must match the
+envelope, and the task/subtask/attempt/owner epoch/input revision must match its
+prepared state. It then records a correlated `ACK` (one envelope, registered
+with `--apply`), does admitted work, and persists one `REPORT`, `BLOCK`, or
+`STATUS` followed by one product notification to the coordinator.
+
+Minimal correlated envelopes (placeholders are substitution points; keep
+`content_digest: null` — registration records the real digest):
+
+```json
+{
+  "schema": "harness-collab/message/1",
+  "message_id": "msg-<unique>-ack",
+  "type": "ACK",
+  "task_id": "<task-id>",
+  "from": {
+    "agent_id": "<worker-agent>",
+    "session_id": "<exact-worker-session>",
+    "harness": "<harness>"
+  },
+  "to": {
+    "agent_id": "<coordinator-agent>",
+    "session_id": "<exact-coordinator-session>",
+    "harness": "<harness>"
+  },
+  "reply_to": "<assign-message-id>",
+  "subtask_id": "<subtask-id>",
+  "attempt": 1,
+  "owner_epoch": 1,
+  "created_at": "<ISO-8601>",
+  "content_digest": null,
+  "body": {}
+}
+```
+
+```json
+{
+  "schema": "harness-collab/message/1",
+  "message_id": "msg-<unique>-report",
+  "type": "REPORT",
+  "task_id": "<task-id>",
+  "from": {
+    "agent_id": "<worker-agent>",
+    "session_id": "<exact-worker-session>",
+    "harness": "<harness>"
+  },
+  "to": {
+    "agent_id": "<coordinator-agent>",
+    "session_id": "<exact-coordinator-session>",
+    "harness": "<harness>"
+  },
+  "reply_to": "<assign-message-id>",
+  "subtask_id": "<subtask-id>",
+  "attempt": 1,
+  "owner_epoch": 1,
+  "created_at": "<ISO-8601>",
+  "content_digest": null,
+  "body": {
+    "status": "completed",
+    "outputs": [],
+    "native_ref": null,
+    "evidence_ref": "/absolute/evidence/report.json"
+  }
+}
+```
+
+The worker registers each envelope (`message send --apply`) and reads it back.
+Registration may report `accepted`, `duplicate`, or a classification such as
+`rejected`; check the actual status rather than assuming acceptance, and do not
+resend a rejected REPORT with a new id unless the underlying evidence changed.
+The worker then notifies the coordinator once with the same task-local binding
+and its own `--caller-pane` where needed. The coordinator verifies the
+artifacts, the exact correlation and the pinned input before deciding business
+acceptance; protocol application and acceptance remain separate facts.
+
+The owned `pappra collab run --controller pi-rpc` path remains a separate,
+explicit option for an owned Pi RPC child with its own admission and evidence
+limits. Do not present it as the default collaboration channel, and do not use
+it to imitate a visible participant.
+
+## 6. Yield, then verify
+
+After sending the notification, yield. Independent work continues in the
+receiving session; do not poll panes, status endpoints, or logs, do not install
+completion timers, and do not re-wake yourself. An idle or finished pane is not
+a result, a stopped process, or acceptance.
+
+When the coordinator's next turn arrives, verify the reported artifacts and
+inputs yourself. If a delivery or execution outcome is uncertain, inspect the
+original evidence through the existing recovery surface
+(`pappra collab recovery inspect`) before any explicit retry or handoff. A
+fresh history client cannot adopt native control of an unknown execution, and
+claimed resources stay held until the protocol permits release.
+
+## Known limits
+
+- `notify` does not create, start, or discover a participant. Bootstrap contact
+  remains a one-time, read-only operator/agent action inside the authorized
+  visible environment, separate from product notifications.
+- A pane is a visibility aid: it is not authentication, native identity, or
+  stop proof. Live ownership of an existing native session cannot be rebuilt
+  from stored pointers.
+- Herdr command shapes change between versions. Treat the examples here as
+  product-side routing patterns and confirm the actual flags with the installed
+  `herdr --help`/`--skill` at use time.
+- Without a working visible channel, persisted messaging and the owned Pi RPC
+  run may still be available, but they do not satisfy a visible-delivery
+  requirement.

package/assets/integrations/skills/pappra/references/hosts.md

@@ -9,6 +9,26 @@ entry imports `./runtime.mjs` next to it, so the package survives a moved
 checkout. Pi 1.3.0 was verified in a real session through the packaged extension
 (`pi install <dir> -l -a` + `pi -p -a`).
 
+`pappra host bundle --host pi --bootstrap-config <abs-file>` is the opt-in successor
+variant: the destination must be new, the private config binds one canonical task root
+and guard pin, and the generated entry installs a default-deny tool gate before any
+config/reader/lifecycle work. Its read-only `bootstrap-status` reports registration,
+never write permission; export does not install, trust, load or transfer.
+
+The bootstrap export relies on a trusted local parent directory with no concurrent
+namespace mutation. It exclusively claims a new destination (existing empty, populated,
+file or symlink targets are left untouched), assembles the payload in a private staging
+directory with identity checks, and on a failure before publication removes only the empty
+claim and stage it created. This is not an OS filesystem fence: portable Node has no
+anchored directory writes or no-replace directory rename, so a same-user process changing
+a path between a check and its use can redirect a write or affect publication/cleanup. The
+private binding is written last, which reduces but does not prevent that check/use race.
+
+Publication is a rename followed by a final inode check, not a transaction: a failure
+during or after publication can return an error after the output directory is visible. A
+non-zero export exit is not proof that no files exist; inspect the destination, never
+blindly delete it, and do not install or trust the output from a failed export.
+
 ## Codex
 
 Codex 0.163.0 loads command hooks only from its user configuration directory.

package/assets/integrations/skills/pappra/references/operations.md

@@ -5,10 +5,32 @@
   to the person.
 - `pappra init` plans or applies workspace configuration. `--yes` derives
   selections from discovery, `--print-choices` prints that document without
-  writing, `--reconfigure` rebuilds an existing valid `workspace.json`, and
-  `--no-runtime` leaves the durable runtime action pending.
+  writing, `--config` reads a `pappra/init-choices/1` document, and
+  `--reconfigure` is the explicit opt-in that rewrites an existing valid
+  `workspace.json` from the current selections while keeping its identity,
+  extensions, continuity, custom validation bindings and local machine
+  settings. Without `--reconfigure` an existing valid configuration is reused
+  and only missing local state is requested. With that existing workspace,
+  `--yes --reconfigure` keeps the current represented choices instead of
+  deriving new ones and `--print-choices --reconfigure` prints them.
+  A plain `--apply` verifies/reuses a runtime for the workspace target or
+  installs the current package and binds it. `--no-runtime` suppresses runtime
+  verification, installation and binding: when an action is still required the
+  result is `status:"external-actions-pending"` with exit 0 for configuration-only work, while an
+  already bound matching runtime with no file changes yields apply status
+  `no-changes` and exit 0 with `initComplete:false`.
+  A TTY wizard opens only when selections are needed; `--config` without
+  `--apply` stays preview-only, an empty plan asks nothing, and the single
+  apply confirmation belongs to the interactive no-`--apply` flow that plans
+  configuration writes. `--apply` itself never prompts.
+  `knowledge.sources` are existing documents registered later by
+  `docs scan --apply`, while `knowledge.newDocuments` is only the destination
+  for future authored documents and is not created by init.
 - `pappra runtime <install|status|verify|remove>` manages the durable runtime
   copy. `install --apply` defaults to `--from self`; writes require `--apply`.
+- `pappra repair` previews interrupted install journals; `--apply` explicitly recovers
+  proven workspace effects or a selected `--runtime-version`. Live/unknown owners and
+  changed files remain protected.
 - `pappra doctor` is passive: it does not install hooks, start hosts, or fix
   state. `runtime verify` is the active runtime check.
 - `pappra checkpoint` writes a task checkpoint; `pappra resume` reads a stored
@@ -23,9 +45,18 @@
   directory without registering it, and `install --mode plugin` fails closed.
 - `pappra mcp` starts the stdio MCP server; `pappra host mcp install --host <name> --apply`
   registers it. `pappra task pin <id> --auto-resume` controls hook resume injection.
-- `pappra collab <prepare|run|query>` runs one bounded collaboration request.
-  `run` requires `--controller fixture|pi-rpc`; `pi-rpc` launches a real Pi RPC
-  session.
+- `pappra collab prepare --goal <file> --domain-root <dir>` and MCP
+  `collab_prepare` share the strict explicit goal; MCP accepts only
+  `{domainRoot, goal}`, not the retired flat objective fields, and synthesizes no card.
+  Preparation maps `pi`/`codex`/`claude` to `pi-cli`/`codex-exec`/`claude-cli`;
+  real controllers remain `fixture|pi-rpc` with `pi-rpc` only for Pi. `collab_start`
+  returns `cli_required` and never launches, even with `confirm:true`. The user must
+  launch through the CLI with runtime evidence. MCP `runtime_install` only copies the
+  running package; tarball and registry sources require the CLI.
+- `pappra collab message <send|list|read|notify> --task-root <dir>` persists
+  protocol messages, reads them back, and sends one explicit pointer-only Herdr
+  notification. `send` and `notify` are plan-only without `--apply`; notification
+  is not consumption or acceptance. See `references/collaboration.md`.
 
 Preserve user bytes. If an operation reports a conflict or residual path,
 inspect that path and resolve ownership before retrying. Never delete an

package/dist/adapters/pi/recovery-extension.d.ts

@@ -0,0 +1,65 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { executeRecovery, type RecoveryController, type RecoveryExecutionMode, type RecoveryExecutionResult } from '../../app/collab-recovery-executor.js';
+import { type PiRecoveryConfig } from '../../hosts/integration/recovery-config.js';
+export { PI_RECOVERY_CONFIG_SCHEMA, readPiRecoveryConfig, type PiRecoveryConfig, type PiRecoveryConfigLoad, type PiRecoveryExpected, } from '../../hosts/integration/recovery-config.js';
+export declare const PI_RECOVERY_STATUS_SCHEMA: 'pappra/pi-recovery-status/1';
+export type RecoveryTrigger = 'session_start' | 'agent_settled' | 'manual';
+/** Genuine host facts observed at a supported event/manual boundary; never fabricated. */
+export interface RecoveryHostFacts {
+    readonly session_id: string;
+    readonly cwd: string | null;
+}
+export type ReconcileOutcome = {
+    readonly trigger: RecoveryTrigger;
+    readonly skipped: true;
+    readonly reason: string;
+} | {
+    readonly trigger: RecoveryTrigger;
+    readonly skipped: false;
+    readonly result: RecoveryExecutionResult;
+};
+export interface PiRecoveryStatus {
+    readonly schema: typeof PI_RECOVERY_STATUS_SCHEMA;
+    readonly registered: boolean;
+    readonly mode: RecoveryExecutionMode | null;
+    readonly task_root: string | null;
+    readonly config_digest: string | null;
+    readonly reconcile_count: number;
+    readonly issued_causes: readonly string[];
+    readonly last: ReconcileOutcome | null;
+    readonly limitations: readonly string[];
+}
+export interface RecoveryReconcilerDeps {
+    readonly controller: RecoveryController;
+    readonly now?: () => number;
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Injectable executor for tests; defaults to the real durable executor. */
+    readonly execute?: typeof executeRecovery;
+}
+export interface RecoveryReconciler {
+    reconcile(trigger: RecoveryTrigger, hostFacts: RecoveryHostFacts | null): Promise<ReconcileOutcome>;
+    status(): PiRecoveryStatus;
+}
+/**
+ * Build a single-flight reconciler. Every supported trigger may run; a reconcile never overlaps another.
+ * The ACTUAL observed host session must match the configured expected session before any work — a config
+ * loaded in a foreign session is skipped. Re-issuing the same cause is prevented durably by the executor's
+ * canonical-cause reservation, so a later new cause can still progress while recovery's own settled event
+ * cannot repeatedly wake itself.
+ */
+export declare function createRecoveryReconciler(config: PiRecoveryConfig, deps: RecoveryReconcilerDeps, configDigest?: string | null): RecoveryReconciler;
+/**
+ * Observe genuine host facts from the supported installed Pi context
+ * (`ctx.sessionManager.getSessionId()` and `ctx.cwd`). Returns null when no actual session can be read, so
+ * a missing observation stays explicit and is never synthesized.
+ */
+export declare function observeHostFacts(event: unknown, context: unknown): RecoveryHostFacts | null;
+/**
+ * Opt-in extension entry. Loads the sibling `recovery.json`, builds a live-target-verifying Herdr
+ * controller for `apply` mode (a no-op controller for `plan` mode, which never issues an effect), and
+ * installs startup/settled triggers plus a manual `pappra-recovery` command. Each trigger observes the
+ * ACTUAL host session and reconciles through the durable, cause-deduplicated executor. A load or validation
+ * failure disables reconciliation and reports it through the status command; it never throws into the
+ * loader and never substitutes a hidden fresh Pi process for the visible workflow.
+ */
+export default function recoveryExtension(pi: ExtensionAPI): void;