@phyzess/pappra 0.1.0-beta.1 → 0.1.0-beta.11

package/README.md

@@ -19,34 +19,53 @@ curl -fsSL https://raw.githubusercontent.com/phyzess/pappra/main/examples/minima
 # Preview first. JSON/config mode is non-interactive and does not prompt.
 npx @phyzess/pappra@beta init --config ./minimal-choices.json --json
 
-# Apply the same choices. With no runtime installed, apply intentionally
-# reports external-actions-pending and exits nonzero after writing config.
+# 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.
 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.
 
-`init --json` without `--config` fails closed because JSON mode does not open the interactive wizard; run `npx @phyzess/pappra@beta init` without `--json` in a TTY if you want to enter selections interactively. `--config` and `--json` never prompt.
+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.
 
 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.
 
-An apply result can be `ok:true` with `status:"external-actions-pending"` and a
-nonzero process exit. That is a successful, partial configuration write, not a
-claim that a runtime or external tool was installed. Inspect `pendingExternalActions`
-and run `doctor` before adding optional integrations.
+`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.
+
+The runtime copy can be managed directly:
+
+```sh
+npx @phyzess/pappra@beta runtime install --apply [--from self|tarball|registry]
+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.
 
 Optional examples have prerequisites rather than generated files: code-graph and
 host commands require the selected external CLI/support, and collaboration
-requires an explicit controller. They are not needed for the core workflow above.
+requires an explicit controller. `--controller pi-rpc` is the host-directs/Pi-executes
+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.
 
 ## What it manages
 
 - **Workspace configuration:** `.pappra/workspace.json` and checkout-local `.pappra/local/machine.json`.
 - **Knowledge:** workspace and private document catalogs with explicit preview/apply operations.
 - **Continuity:** private task checkpoints and bounded advisory resume packets. Resume never grants execution by itself.
-- **Code intelligence:** status, explicit preparation and bounded query for selected repositories. Text/structure fallback is available when the optional graph engine is absent.
-- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration.
+- **Code intelligence:** status, explicit preparation and bounded query for selected repositories. Text/structure fallback is available when the optional graph engine is absent. Registrations are stored under the workspace `.pappra/local/code`, never inside a repository checkout, so a multi-repository workspace does not turn its checkouts into nested workspaces.
+- **Host integrations:** optional Pi, Codex and Claude Code adapters that merge Pappra-owned entries without taking over user configuration. Hooks are copied as a dependency-free bundle; Claude Code uses `${CLAUDE_PROJECT_DIR}` and Pi imports its runtime relatively, while Codex 0.163.0 loads hooks only from `$CODEX_HOME/hooks.json` (`host install --host codex --scope user`). `host bundle --marketplace` exports a marketplace that Claude Code and Codex accept without registering it. Plugin hooks are verified for Pi 1.3.0 and Claude Code 2.1.292 (startup) and unsupported for Codex, so `host install --mode plugin` fails closed with the per-host registration commands. See [host plugin validation](docs/host-plugin-validation.md).
 - **Bounded collaboration:** an optional, explicitly controlled one-request workflow. It is not a scheduler or daemon.
 
 ## Optional integrations and support
@@ -66,11 +85,11 @@ Host names and external protocol identifiers describe supported integration surf
 pnpm check
 ```
 
-The check runs the source policy, type checks, formatting, deterministic tests and a local package smoke test. The package smoke test uses an offline local tarball and an isolated fixture home/state; it does not install a model or contact a provider.
+The check runs the source policy, type checks, formatting, deterministic tests and a local package smoke test. The package smoke test prefers an offline local tarball (falling back to registry resolution when the runner has no offline metadata) and an isolated fixture home/state; it does not install a model or contact a model provider.
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.1`) 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.1`, because pre-release versions are never republished.
+Pappra is development software (`0.1.0-beta.11`) 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.11`, because pre-release versions are never republished.
 
 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

@@ -16,13 +16,16 @@ index, or new writer.
 2. Read `references/hosts.md` when the host surface is Pi, Codex, or Claude.
 3. Use `pappra checkpoint` / `pappra resume` for handoffs. A stored checkpoint
    is context, not permission to execute or to trust a previous session.
-4. Use `pappra docs` and `pappra code` only for the workspace selected by the
-   current root. Never infer a workspace from an unrelated session.
+4. Use `pappra docs`, `pappra code`, `pappra runtime` and `pappra host` only for
+   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. Never turn
-   prose into identity, approval, or capability claims.
+   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.
 
 ## One-request collaboration
 

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

@@ -2,29 +2,39 @@
 
 ## Pi
 
-The integration installs a project extension plus a copied `pappra` skill.
-Pi extensions run with host permissions. Load only a trusted copy from this
-workspace/target; the generated entrypoint imports the fixed Pappra runtime by
-absolute file URL and registers lifecycle handlers only.
+The project integration installs an extension plus a copied `pappra` skill; the
+generated entrypoint imports the fixed Pappra runtime by absolute file URL.
+`pappra host bundle --host pi` exports a self-contained package instead: the
+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`).
 
 ## Codex
 
-The integration installs a command-hook entry and merges only Pappra-owned
-entries into `hooks.json`. Existing hooks and unrelated keys are preserved.
+Codex 0.163.0 loads command hooks only from its user configuration directory.
+Wire it with `pappra host install --host codex --scope user`, which merges only
+Pappra-owned entries into `$CODEX_HOME/hooks.json` (existing hooks and unrelated
+keys are preserved) and copies the bundled hook there. Project
+`.codex/hooks.json` and plugin-bundle hooks are not loaded at this version.
 Codex hook definitions are trusted individually; installation is not trust.
 Observed 0.163.0 hook keys do not include a compact event, so compact and
 automatic checkpoint requests remain unsupported.
 
 ## Claude Code
 
-The integration installs a command-hook entry and merges only Pappra-owned
-entries into `settings.json`. `SessionStart` and `PostCompact` are distinct;
-matchers, trust, timeout, and output behavior remain host/version-specific.
-Installing a command is not proof it ran.
+The project integration installs a command-hook entry and merges only
+Pappra-owned entries into `settings.json`; the command uses
+`${CLAUDE_PROJECT_DIR}`. `pappra host bundle --host claude --marketplace` exports
+a plugin whose hook uses `${CLAUDE_PLUGIN_ROOT}`; the marketplace validates with
+`claude plugin validate` and startup was verified in a real session. `SessionStart`
+and `PostCompact` are distinct; matchers, trust, timeout, and output behavior
+remain host/version-specific. Installing a command is not proof it ran.
 
 ## Common safety
 
 All surfaces use the event's canonical cwd/root, bounded stdin, a one-second
 local deadline, no transcript reads, no arbitrary configured commands, and no
 network/model/index/session side effects. Paths with spaces or Unicode are
-passed as argv/file URLs, never interpolated into a shell.
+passed as argv/file URLs, never interpolated into a shell. Plugin registration is
+host-specific; never claim a hook is loaded because files were written or a
+validator passed.

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

@@ -14,6 +14,10 @@ Pappra distinguishes four local lifecycle intents:
 The matrix is version-specific. A host version outside the observed support
 range is `unsupported`/`unknown`, not a fallback to name similarity.
 
+Codex 0.163.0 loads these hook keys only from its user configuration directory
+(`$CODEX_HOME/hooks.json`); project `.codex/hooks.json` and plugin bundles are
+not loaded by that version. Claude Code and Pi wire hooks in project scope.
+
 ## What a hook does
 
 A hook validates the host payload, resolves the current workspace from the

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

@@ -1,13 +1,26 @@
 # Operations reference
 
-- `pappra init` plans or applies workspace configuration.
+- `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.
+- `pappra runtime <install|status|verify|remove>` manages the durable runtime
+  copy. `install --apply` defaults to `--from self`; writes require `--apply`.
 - `pappra doctor` is passive: it does not install hooks, start hosts, or fix
-  state.
-- `pappra checkpoint` writes a task checkpoint; `pappra resume` reads a
-  stored snapshot and reports whether execution is allowed.
-- `pappra docs` manages knowledge documents.
-- `pappra code` operates on an explicitly selected repository and keeps
-  index mutations behind an explicit `--apply`.
+  state. `runtime verify` is the active runtime check.
+- `pappra checkpoint` writes a task checkpoint; `pappra resume` reads a stored
+  snapshot and reports whether execution is allowed.
+- `pappra docs <list|check|archive|scan>` manages the knowledge catalog.
+  `scan --apply` registers documents found under the configured sources.
+- `pappra code` operates on an explicitly selected repository and keeps index
+  mutations behind an explicit `--apply`.
+- `pappra host <detect|describe|plan|install|verify|bundle>` wires an optional
+  host. Codex 0.163.0 loads hooks only from `$CODEX_HOME/hooks.json`, so use
+  `install --host codex --scope user`; `bundle --marketplace` exports a plugin
+  directory without registering it, and `install --mode plugin` fails closed.
+- `pappra collab <prepare|run|query>` runs one bounded collaboration request.
+  `run` requires `--controller fixture|pi-rpc`; `pi-rpc` launches a real Pi RPC
+  session.
 
 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/app/collaboration.js

@@ -461,17 +461,6 @@ function currentNativeResult(file, baseline) {
         return null;
     }
 }
-function regularFileSize(file) {
-    if (file === null || !path.isAbsolute(file))
-        return null;
-    try {
-        const observed = fs.lstatSync(file);
-        return observed.isFile() ? observed.size : null;
-    }
-    catch {
-        return null;
-    }
-}
 function writeNewFile(file, bytes) {
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
     fs.writeFileSync(file, bytes, { flag: 'wx', mode: 0o600 });
@@ -1359,10 +1348,14 @@ export class PiRpcController {
                 possible_start: stage === 'identity',
             };
         }
-        const nativeSessionFile = started.session.sessionFile();
-        const nativeSessionBaseline = regularFileSize(nativeSessionFile);
+        let nativeSessionFile = null;
+        let nativeSessionBaseline = 0;
         try {
             await started.session.prompt();
+            // The handle sampled the baseline before it sent the prompt; read it afterwards so
+            // both values describe the launch that just completed.
+            nativeSessionFile = started.session.sessionFile();
+            nativeSessionBaseline = started.session.promptBaseline();
         }
         catch (error) {
             await started.session.finish().catch(() => undefined);

package/dist/app/doctor.js

@@ -259,7 +259,7 @@ function runtimeCheck(targetVersion, machineRuntime, passive, machinePath, obser
                 source: machinePath ?? dataDir,
                 observedAt,
                 nextActions: [
-                    'Run an explicit pappra init --apply --install-runtime with a chosen local tarball or exact version when authorized.',
+                    'Run pappra runtime install --apply (from self, tarball, or an exact version) or pappra init --apply when authorized.',
                 ],
             });
         }
@@ -335,7 +335,7 @@ function runtimeCheck(targetVersion, machineRuntime, passive, machinePath, obser
                 ]
                 : [],
             nextActions: [
-                'Run an explicit pappra init --apply --install-runtime with a chosen local tarball or exact version when authorized.',
+                'Run pappra runtime install --apply (from self, tarball, or an exact version) or pappra init --apply when authorized.',
             ],
         });
     }
@@ -886,14 +886,33 @@ export async function runDoctor(options = {}) {
         ],
     }));
     const selectedHosts = machine?.selectedHosts ?? [];
-    const hostRootBase = root ?? homeDir;
+    // Passive observation only: a host install can target the private default root, a
+    // project directory, or Codex's user configuration directory.
+    const hostInstallRoots = (host) => {
+        const roots = [
+            join(root ?? homeDir, '.pappra', 'local', 'hosts', host),
+            join(root ?? homeDir, `.${host}`),
+        ];
+        if (host === 'codex') {
+            roots.push(process.env['CODEX_HOME'] ?? join(homeDir, '.codex'));
+        }
+        return roots;
+    };
     const installedHostBundle = (await Promise.all(selectedHosts.map(async (host) => {
-        const path = join(hostRootBase, '.pappra', 'local', 'hosts', host, 'pappra-host.json');
-        return (await observePath(path)).kind === 'file' ? path : null;
+        for (const base of hostInstallRoots(host)) {
+            const path = join(base, 'pappra-host.json');
+            if ((await observePath(path)).kind === 'file')
+                return path;
+        }
+        return null;
     }))).find((path) => path !== null) ?? null;
     const installedHostSkill = (await Promise.all(selectedHosts.map(async (host) => {
-        const path = join(hostRootBase, '.pappra', 'local', 'hosts', host, 'skills', 'pappra', 'SKILL.md');
-        return (await observePath(path)).kind === 'file' ? path : null;
+        for (const base of hostInstallRoots(host)) {
+            const path = join(base, 'skills', 'pappra', 'SKILL.md');
+            if ((await observePath(path)).kind === 'file')
+                return path;
+        }
+        return null;
     }))).find((path) => path !== null) ?? null;
     checks.push(...hostChecks(selectedHosts, homeDir, pathEnv, observedAt));
     checks.push(makeCheck({

package/dist/app/init.d.ts

@@ -14,6 +14,8 @@ export interface InitFailure {
     readonly message: string;
     readonly diagnostics: readonly Diagnostic[];
     readonly nextAction: string | null;
+    /** Machine-readable payload for callers that cannot prompt. */
+    readonly details?: Readonly<Record<string, unknown>>;
 }
 export interface InitRootResolution {
     readonly requestedRoot: string;
@@ -114,6 +116,8 @@ export interface PlanInitOptions {
     readonly root: string;
     readonly choices?: InitChoices | null;
     readonly runtimeVersion?: string;
+    /** Rebuilds workspace.json from selections even when a valid config exists. */
+    readonly reconfigure?: boolean;
     readonly planId?: string;
     readonly discoveredAt?: string;
     /** Reuse an immediately preceding inspectInitContext result. */
@@ -130,6 +134,30 @@ export declare function inspectInitContext(rootPath: string): Promise<InitContex
 export declare function listRepositoryCandidates(discovery: WorkspaceDiscovery): readonly RepositoryCandidate[];
 /** Lists knowledge source choices derived only from current discovery. */
 export declare function listKnowledgeCandidates(discovery: WorkspaceDiscovery): readonly KnowledgeCandidate[];
+export interface InitChoiceRule {
+    readonly field: string;
+    readonly value: string;
+    readonly reason: string;
+}
+export interface InitChoiceCandidates {
+    readonly repositories: readonly string[];
+    readonly knowledge: readonly string[];
+    readonly validation: readonly string[];
+    readonly hosts: readonly string[];
+}
+export interface DerivedInitChoices {
+    readonly choices: InitChoices;
+    readonly rules: readonly InitChoiceRule[];
+    readonly candidates: InitChoiceCandidates;
+}
+/**
+ * Derives deterministic init selections from discovery alone. Every value is
+ * reported with the rule that produced it so a caller can audit the choice
+ * before applying it; nothing here writes, installs or prompts.
+ */
+export declare function deriveInitChoices(discovery: WorkspaceDiscovery, options?: {
+    readonly pathEnv?: string;
+}): Promise<DerivedInitChoices>;
 /**
  * Produces a strict plan and exact in-memory writes. No target file is created
  * or modified by this function.