@phyzess/pappra 0.1.0-beta.7 → 0.1.0-beta.9

package/README.md

@@ -55,7 +55,9 @@ 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
 
@@ -63,7 +65,7 @@ requires an explicit controller. They are not needed for the core workflow above
 - **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. Hooks are copied as a dependency-free bundle into the host root; `host bundle --marketplace` exports a local 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 0.163.0; `host bundle` exports the bundle and `host install --mode plugin` fails closed with the per-host commands. See [host plugin validation](docs/host-plugin-validation.md).
+- **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 into the host root; `host bundle --marketplace` exports a local 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); Codex 0.163.0 loads hooks only from user scope, so use `host install --host codex --scope user` (merges `$CODEX_HOME/hooks.json`). `host bundle` exports a plugin bundle for the other hosts and `host install --mode plugin` fails closed with the per-host 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
@@ -87,7 +89,7 @@ The check runs the source policy, type checks, formatting, deterministic tests a
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.7`) 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.7`, because pre-release versions are never republished.
+Pappra is development software (`0.1.0-beta.9`) 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.9`, 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/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/cli/commands/host.d.ts

@@ -12,5 +12,6 @@ export interface HostCommandOptions {
     readonly out: string | null;
     readonly mode: 'project-settings' | 'plugin' | null;
     readonly marketplace: boolean;
+    readonly scope: 'project' | 'user' | null;
 }
 export declare function runHostCommand(options: HostCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/host.js

@@ -1,5 +1,5 @@
 import { homedir } from 'node:os';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { HostIntegrationService } from '../../hosts/integration/service.js';
 import { exportHostPluginBundle } from '../../hosts/integration/bundle-export.js';
 import { HOST_SUPPORT, isSupportedVersion, } from '../../hosts/integration/support.js';
@@ -10,6 +10,13 @@ export const hostUsage = 'pappra host <detect|describe|plan|install|verify|bundl
     '\n' +
     'bundle exports a host-native plugin/package directory and never registers it or\n' +
     'claims host callability.';
+/** Codex only loads lifecycle hooks from its user configuration directory. */
+function codexHome() {
+    const configured = process.env['CODEX_HOME'];
+    return configured === undefined || configured === ''
+        ? join(homedir(), '.codex')
+        : resolve(configured);
+}
 function printDiagnostics(output, diagnostics) {
     for (const entry of diagnostics) {
         if (typeof entry === 'object' &&
@@ -46,9 +53,27 @@ export async function runHostCommand(options, output) {
         hostVersion: options.hostVersion,
         observedAt: new Date().toISOString(),
     });
-    const hostRoot = options.hostRoot === null
-        ? undefined
-        : resolve(options.cwd, options.hostRoot);
+    if (options.scope === 'user') {
+        if (HOST_SUPPORT[options.host].hookScope !== 'user') {
+            output.stderr(`pappra host: ${options.host} loads hooks from ${HOST_SUPPORT[options.host].hookScope} scope; --scope user is only valid for a user-scoped host (codex).\n`);
+            return 2;
+        }
+        if (options.hostRoot !== null) {
+            output.stderr('pappra host: --scope user resolves CODEX_HOME and cannot be combined with --host-root.\n');
+            return 2;
+        }
+        if (options.action !== 'plan' &&
+            options.action !== 'install' &&
+            options.action !== 'verify') {
+            output.stderr('pappra host: --scope user is only valid for plan, install, or verify.\n');
+            return 2;
+        }
+    }
+    const hostRoot = options.scope === 'user'
+        ? codexHome()
+        : options.hostRoot === null
+            ? undefined
+            : resolve(options.cwd, options.hostRoot);
     const target = {
         ...(hostRoot === undefined ? {} : { hostRoot }),
         ...(options.hostVersion === null

package/dist/cli/run.js

@@ -26,6 +26,7 @@ function parseOptions(args) {
             out: { type: 'string' },
             mode: { type: 'string' },
             marketplace: { type: 'boolean' },
+            scope: { type: 'string' },
             bind: { type: 'boolean' },
             force: { type: 'boolean' },
             'no-interactive': { type: 'boolean' },
@@ -251,6 +252,16 @@ export async function runCli(args, output) {
         failure(output, json, 'invalid_arguments', '--out is only valid for host.');
         return 2;
     }
+    if (values.scope !== undefined &&
+        values.scope !== 'project' &&
+        values.scope !== 'user') {
+        failure(output, json, 'invalid_arguments', '--scope accepts project or user.');
+        return 2;
+    }
+    if (command !== 'host' && values.scope !== undefined) {
+        failure(output, json, 'invalid_arguments', '--scope is only valid for host.');
+        return 2;
+    }
     if (command !== 'host' && values.marketplace === true) {
         failure(output, json, 'invalid_arguments', '--marketplace is only valid for host bundle.');
         return 2;
@@ -665,6 +676,10 @@ export async function runCli(args, output) {
             (values.apply === true && action !== 'install') ||
             (values.mode !== undefined && action !== 'install') ||
             (values.marketplace === true && action !== 'bundle') ||
+            (values.scope !== undefined &&
+                action !== 'plan' &&
+                action !== 'install' &&
+                action !== 'verify') ||
             (values['host-root'] !== undefined && action === null) ||
             (values['host-version'] !== undefined && action === null);
         if (values.help) {
@@ -693,6 +708,9 @@ export async function runCli(args, output) {
                 ? values.mode
                 : null,
             marketplace: values.marketplace === true,
+            scope: values.scope === 'project' || values.scope === 'user'
+                ? values.scope
+                : null,
         }, output);
     }
     if (command !== null) {

package/dist/hosts/integration/pappra-extension-runtime.mjs

@@ -23933,6 +23933,7 @@ var HOST_SUPPORT = {
   pi: {
     surface: "pi-extension",
     version: "1.3.0",
+    hookScope: "project",
     events: {
       startup: "session_start",
       resume: "session_start",
@@ -23943,6 +23944,9 @@ var HOST_SUPPORT = {
   codex: {
     surface: "codex-hooks",
     version: "0.163.0",
+    // Codex 0.163.0 loads lifecycle hooks only from its user configuration
+    // directory (CODEX_HOME); project `.codex/hooks.json` is not loaded.
+    hookScope: "user",
     events: {
       startup: "SessionStart",
       resume: "SessionStart",
@@ -23953,6 +23957,7 @@ var HOST_SUPPORT = {
   claude: {
     surface: "claude-hooks",
     version: "2.1.292",
+    hookScope: "project",
     events: {
       startup: "SessionStart",
       resume: "SessionStart",

package/dist/hosts/integration/pappra-hook.mjs

@@ -23938,6 +23938,7 @@ var HOST_SUPPORT = {
   pi: {
     surface: "pi-extension",
     version: "1.3.0",
+    hookScope: "project",
     events: {
       startup: "session_start",
       resume: "session_start",
@@ -23948,6 +23949,9 @@ var HOST_SUPPORT = {
   codex: {
     surface: "codex-hooks",
     version: "0.163.0",
+    // Codex 0.163.0 loads lifecycle hooks only from its user configuration
+    // directory (CODEX_HOME); project `.codex/hooks.json` is not loaded.
+    hookScope: "user",
     events: {
       startup: "SessionStart",
       resume: "SessionStart",
@@ -23958,6 +23962,7 @@ var HOST_SUPPORT = {
   claude: {
     surface: "claude-hooks",
     version: "2.1.292",
+    hookScope: "project",
     events: {
       startup: "SessionStart",
       resume: "SessionStart",

package/dist/hosts/integration/support.d.ts

@@ -3,6 +3,7 @@ export declare const HOST_SUPPORT: {
     readonly pi: {
         readonly surface: 'pi-extension';
         readonly version: '1.3.0';
+        readonly hookScope: 'project';
         readonly events: {
             readonly startup: 'session_start';
             readonly resume: 'session_start';
@@ -13,6 +14,7 @@ export declare const HOST_SUPPORT: {
     readonly codex: {
         readonly surface: 'codex-hooks';
         readonly version: '0.163.0';
+        readonly hookScope: 'user';
         readonly events: {
             readonly startup: 'SessionStart';
             readonly resume: 'SessionStart';
@@ -23,6 +25,7 @@ export declare const HOST_SUPPORT: {
     readonly claude: {
         readonly surface: 'claude-hooks';
         readonly version: '2.1.292';
+        readonly hookScope: 'project';
         readonly events: {
             readonly startup: 'SessionStart';
             readonly resume: 'SessionStart';

package/dist/hosts/integration/support.js

@@ -2,6 +2,7 @@ export const HOST_SUPPORT = {
     pi: {
         surface: 'pi-extension',
         version: '1.3.0',
+        hookScope: 'project',
         events: {
             startup: 'session_start',
             resume: 'session_start',
@@ -12,6 +13,9 @@ export const HOST_SUPPORT = {
     codex: {
         surface: 'codex-hooks',
         version: '0.163.0',
+        // Codex 0.163.0 loads lifecycle hooks only from its user configuration
+        // directory (CODEX_HOME); project `.codex/hooks.json` is not loaded.
+        hookScope: 'user',
         events: {
             startup: 'SessionStart',
             resume: 'SessionStart',
@@ -22,6 +26,7 @@ export const HOST_SUPPORT = {
     claude: {
         surface: 'claude-hooks',
         version: '2.1.292',
+        hookScope: 'project',
         events: {
             startup: 'SessionStart',
             resume: 'SessionStart',

package/dist/hosts/pi/rpc.d.ts

@@ -461,6 +461,8 @@ export declare function startOwnedPiRpc(options: PiOptions): Promise<{
         pid: number | null;
         expectedSessionId: string | null;
         sessionFile: () => string | null;
+        /** Byte offset sampled immediately before the prompt was sent. */
+        promptBaseline: () => number;
         /** Read-only native query. Repeatable; always recorded through the protocol. */
         query(): Promise<{
             at: string;

package/dist/hosts/pi/rpc.js

@@ -680,6 +680,7 @@ export async function startOwnedPiRpc(options) {
     let reportedSessionFile = null;
     let boundSessionFile = null;
     let promptSent = false;
+    let promptBaseline = 0;
     let lastPromptOrdinal = 0;
     let operationError = null;
     let finishPromise = null;
@@ -822,6 +823,8 @@ export async function startOwnedPiRpc(options) {
         pid: child.pid ?? null,
         expectedSessionId: admission.expected_identity,
         sessionFile: () => boundSessionFile,
+        /** Byte offset sampled immediately before the prompt was sent. */
+        promptBaseline: () => promptBaseline,
         /** Read-only native query. Repeatable; always recorded through the protocol. */
         async query() {
             try {
@@ -894,7 +897,24 @@ export async function startOwnedPiRpc(options) {
                     throw new PiRpcRefusal('prompt_already_sent', 'invalid', 'one frozen prompt per launch');
                 assertNamespaceGuard(opts);
                 assertCurrentAuthority({ requireResources: true });
-                await assertIdentity({ requireBinding: true });
+                // Pi creates the session file lazily, on the first persisted message. The
+                // pre-prompt check therefore verifies the reported session id without requiring
+                // the header; the post-prompt check requires the bound header before the run is
+                // accepted.
+                await assertIdentity({ requireBinding: false });
+                // The controller publishes only records written after this baseline, so it must
+                // be sampled before the prompt creates the first message.
+                const baselineFile = reportedSessionFile;
+                promptBaseline = (() => {
+                    if (baselineFile === null)
+                        return 0;
+                    try {
+                        return fs.statSync(baselineFile).size;
+                    }
+                    catch {
+                        return 0;
+                    }
+                })();
                 const ordinalBefore = rpc.recordCount();
                 const response = await request('prompt', { message: opts.promptText });
                 const disposition = response.data?.disposition;
@@ -902,6 +922,24 @@ export async function startOwnedPiRpc(options) {
                     !['started', 'queued', 'handled'].includes(disposition)) {
                     throw new PiRpcRefusal('prompt_not_accepted', 'needs_input', `disposition ${disposition}`);
                 }
+                // The header row is flushed just after the prompt is accepted, so bind with a
+                // short bounded retry instead of racing the writer.
+                const bindDeadline = Date.now() + 2_000;
+                for (;;) {
+                    try {
+                        await assertIdentity({ requireBinding: true });
+                        break;
+                    }
+                    catch (error) {
+                        const retryable = error instanceof PiRpcRefusal &&
+                            (error.code === 'native_session_file_unavailable' ||
+                                error.code === 'native_session_header_invalid') &&
+                            Date.now() < bindDeadline;
+                        if (!retryable)
+                            throw error;
+                        await new Promise((resolve) => setTimeout(resolve, 50));
+                    }
+                }
                 promptSent = true;
                 lastPromptOrdinal = ordinalBefore;
                 proof.prompt = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phyzess/pappra",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.9",
   "description": "Portable workspace knowledge and continuity for coding agents.",
   "publishConfig": {
     "access": "public"