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

package/dist/hosts/pilot.d.ts

@@ -26,11 +26,8 @@ export declare function readClaudeSessionId(file: string): string | null;
 export declare function readPiSessionId(file: string): string | null;
 export declare function runNativePilot({ harness, profile, cwd, promptFile, evidenceDir, sessionId, resume, timeoutMs, maxBudgetUsd, outputName, phase, trustProject, extraDirs, clock, assignmentFile, capabilitiesFile, taskRoot, maxAgeMinutes, launchKind, discovery, }: PilotOptions): Promise<{
     reservation?: never;
-    settlement?: never;
-    reservation_id?: never;
     refused: boolean;
     admission: {
-        detail?: never;
         state?: never;
         state_revision?: never;
         ok: false;
@@ -52,8 +49,8 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
-    } | {
         detail?: never;
+    } | {
         expected?: never;
         state?: never;
         state_revision?: never;
@@ -75,6 +72,7 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
+        detail?: never;
     } | {
         expected?: never;
         actual?: never;
@@ -99,7 +97,6 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         input_revision?: never;
         owner_epoch?: never;
     } | {
-        detail?: never;
         expected?: never;
         actual?: never;
         state?: never;
@@ -121,8 +118,8 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
-    } | {
         detail?: never;
+    } | {
         state?: never;
         state_revision?: never;
         ok: false;
@@ -144,8 +141,8 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
-    } | {
         detail?: never;
+    } | {
         state?: never;
         state_revision?: never;
         ok: false;
@@ -172,6 +169,7 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
+        detail?: never;
     } | {
         state?: never;
         state_revision?: never;
@@ -196,7 +194,6 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         input_revision?: never;
         owner_epoch?: never;
     } | {
-        detail?: never;
         expected?: never;
         actual?: never;
         state?: never;
@@ -218,8 +215,8 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
-    } | {
         detail?: never;
+    } | {
         expected?: never;
         actual?: never;
         state?: never;
@@ -261,8 +258,8 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
-    } | {
         detail?: never;
+    } | {
         expected?: never;
         actual?: never;
         state_revision?: never;
@@ -284,8 +281,8 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
-    } | {
         detail?: never;
+    } | {
         state?: never;
         state_revision?: never;
         required_skills?: never;
@@ -307,6 +304,7 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
+        detail?: never;
     } | {
         expected?: never;
         actual?: never;
@@ -331,7 +329,6 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         input_revision?: never;
         owner_epoch?: never;
     } | {
-        detail?: never;
         state?: never;
         state_revision?: never;
         required_skills?: never;
@@ -353,8 +350,8 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
-    } | {
         detail?: never;
+    } | {
         expected?: never;
         actual?: never;
         state?: never;
@@ -376,6 +373,7 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         assignment_digest?: never;
         input_revision?: never;
         owner_epoch?: never;
+        detail?: never;
     };
     reason: string;
     process?: never;
@@ -386,12 +384,11 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
     stdoutFile?: never;
     stderrFile?: never;
     nativeEvidence?: never;
-} | {
-    settlement?: never;
     reservation_id?: never;
+    settlement?: never;
+} | {
     refused: boolean;
     admission: {
-        detail?: never;
         expected?: never;
         actual?: never;
         state?: never;
@@ -413,6 +410,7 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence: string;
         assignment_digest: string;
         input_revision: string | null;
+        detail?: never;
     };
     reason: string;
     reservation: {
@@ -428,12 +426,13 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
     stdoutFile?: never;
     stderrFile?: never;
     nativeEvidence?: never;
+    reservation_id?: never;
+    settlement?: never;
 } | {
     reason?: never;
     reservation?: never;
-    admission?: never;
     refused?: never;
-    reservation_id?: never;
+    admission?: never;
     execution: null;
     evidenceError: string;
     settlement: {
@@ -459,12 +458,12 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
     stdoutFile?: never;
     stderrFile?: never;
     nativeEvidence?: never;
+    reservation_id?: never;
 } | {
     reason?: never;
     reservation?: never;
-    admission?: never;
     refused?: never;
-    reservation_id?: never;
+    admission?: never;
     process?: never;
     execution: Record<string, unknown> | null;
     evidenceError: string;
@@ -482,11 +481,12 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
     stdoutFile?: never;
     stderrFile?: never;
     nativeEvidence?: never;
+    reservation_id?: never;
 } | {
     reason?: never;
     reservation?: never;
-    admission?: never;
     refused?: never;
+    admission?: never;
     process?: never;
     evidenceError?: never;
     execution: Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phyzess/pappra",
-  "version": "0.1.0-beta.18",
+  "version": "0.1.0-beta.19",
   "description": "Portable coding-agent workspaces with knowledge, continuity, code navigation and optional collaboration.",
   "publishConfig": {
     "access": "public"
@@ -79,6 +79,8 @@
   "scripts": {
     "build:scripts": "tsc -p tsconfig.scripts.json",
     "build": "tsc -p tsconfig.scripts.json && node .build/scripts/scripts/clean-build.js && tsc -p tsconfig.build.json && node .build/scripts/scripts/build-assets.js",
+    "dev:check": "node scripts/self-host.ts --check",
+    "dev:setup": "node scripts/self-host.ts --apply",
     "typecheck": "tsc -p tsconfig.build.json --noEmit && tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.scripts.json --noEmit",
     "pretest": "pnpm build && tsc -p tsconfig.test.json",
     "test": "node .build/test/scripts/run-tests.js",

package/skills/pappra/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pappra
-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.
+description: Use Pappra workspace knowledge, checkpoint/resume, selected-repository code intelligence, and task-scoped cross-harness collaboration from any supported coding agent. Use before nontrivial repository work to reach the project's own skill and CodeGraph entry, when a task needs durable handoff context, workspace documents, or bounded code navigation, and when independent parallel implementation or independent review would reduce risk even if the user never names collaboration.
 ---
 
 # Pappra
@@ -74,6 +74,34 @@ 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.
 
+## Role plans and host-agent role selection
+
+Choosing whether work needs independent implementation or an independent reviewer
+is the host agent's judgment from the user's objective and the actual change
+surface: complexity, dependency blast radius, disjoint write scopes, and risk.
+There is no backend role inferencer, no fixed participant count, and no repeated
+permission prompt once the user authorized the work.
+
+Use the installed commands in this order; roles never grant authority:
+
+- `pappra collab role-plan expand --request <abs role-plan.json> --json` expands
+  explicit participants, assignments and disjoint writer scopes into the existing
+  work-plan format. Save the returned `plan`.
+- `pappra collab plan --task-root <abs> --config <abs expanded-plan.json>` and
+  `pappra collab work-run --request <abs work-execution.json> [--apply]` keep
+  their existing admission, capability and dispatch requirements.
+- `pappra collab role-run --request <abs role-orchestration.json> [--apply]`
+  reads authoritative role/dependency state; `--apply` handles one bounded event
+  tick and reserves before dispatch. Neither infers acceptance.
+- `pappra collab role-plan aggregate --request <abs role-plan.json>` with
+  `--task-root <abs> --config <abs expanded-plan.json>` aggregates authoritative
+  results.
+
+Roles describe responsibility and scope only: they approve nothing and never
+synthesize a participant identity or capability card. Hooks record lifecycle
+observations only and never select roles or launch a model. Keep the manual path:
+a simple, reversible, local change needs no role plan.
+
 ## 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.

package/skills/pappra/references/collaboration.md

@@ -200,6 +200,19 @@ evidence through the work-plan inspector. Rejected, unknown, missing and pending
 outcomes remain visible. A delivery acknowledgement never becomes acceptance.
 Neither command launches a model, claims resources or creates an assignment.
 
+`pappra collab role-run --request <abs role-orchestration.json> [--apply]
+[--watch] --json` advances the plan's recorded role/dependency events. Plan mode
+reads authoritative state with no effects; `--apply` handles one bounded event
+tick, reserves before dispatch and never infers acceptance; `--watch` requires
+`--apply`. Repeated or ambiguous effects are reconciled, and rejected work needs an
+authorized repair attempt. It notifies registered participants only and creates no
+session, assignment or claim of its own.
+
+Which roles exist, and how many writers or reviewers run, is the host agent's
+judgment of the actual objective and change surface, not a product default.
+Nothing here infers semantic roles: hooks record bounded lifecycle observations,
+the backend resolves protocol state, and no command launches a model from prose.
+
 ## Native capability evidence
 
 `pappra collab capabilities derive --harness <pi|codex|claude> --assignment <abs assignment.json> --template <abs card.declared.json> --execution <abs execution.json> [--session <abs pi-session.jsonl> | --events <abs events.jsonl>] [--json]`

package/skills/pappra/references/environment.md

@@ -51,6 +51,13 @@ stays `process_affiliation: "not-established"`.
 Pick participants, roles, harness, and configuration from the task rather than a
 fixed agent count. Everyone can implement, review, or verify; assign by need.
 
+Which roles and how many participants are needed follows the real work split, and
+that choice belongs to the host agent reading the objective and change surface;
+neither the backend nor the hooks infer responsibilities or launch anyone.
+Authorization the user already gave for the task persists, so do not re-request the
+same delegation at every step, and never fabricate a participant identity,
+capability or claim to fill a role.
+
 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