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

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

@@ -12,6 +12,14 @@ export interface HostTargetOptions {
     readonly hostRoot?: string;
     readonly runtimeEntry?: string;
     readonly hostVersion?: string | null;
+    /** Rewrites a manifest previously pinned to a package checkout path. */
+    readonly migrate?: boolean;
+    /**
+     * Plugin wiring is exported with `host bundle` but not installed here: host
+     * registration, trust and callability are unverified, so this mode fails
+     * closed instead of writing a bundle a host may never load.
+     */
+    readonly mode?: 'project-settings' | 'plugin';
 }
 export interface HostPlanBundle {
     readonly plan: HostIntegrationPlan;

package/dist/hosts/integration/service.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { link, mkdir, open, realpath, rename, rm } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createDiagnostic } from '../../schemas/diagnostics.js';
 import { diagnosticCodes } from '../../schemas/errors.js';
@@ -12,7 +12,7 @@ import { getPackageInfo } from '../../package-info.js';
 import { detectPassiveHosts } from '../detect.js';
 import { installPathForBundleFile, loadHostBundle } from './bundle.js';
 import { hostConfigRelativePath, renderHookConfigPatch } from './templates.js';
-import { HOST_SUPPORT, isSupportedVersion, nativeEventFor, surfaceFor, } from './support.js';
+import { HOST_PLUGIN_HOOKS, HOST_SUPPORT, isSupportedVersion, nativeEventFor, surfaceFor, } from './support.js';
 const LIFECYCLE_EVENTS = [
     'startup',
     'resume',
@@ -26,7 +26,20 @@ function now() {
 }
 function packageRuntimeEntry() {
     const packageJson = fileURLToPath(import.meta.resolve('@phyzess/pappra/package.json'));
-    return join(dirname(packageJson), 'dist', 'hosts', 'integration', 'hook-entry.js');
+    return join(dirname(packageJson), 'dist', 'hosts', 'integration', 'pappra-hook.mjs');
+}
+/**
+ * Uses the host's project placeholder when the hook copy lives inside the
+ * workspace, so a moved checkout or an evicted npx cache cannot break the hook.
+ */
+function hookTarget(host, workspaceRoot, hostRoot, hookSource) {
+    const installedPath = join(hostRoot, 'hooks', 'pappra-hook.mjs');
+    const relativePath = relative(workspaceRoot, installedPath);
+    const insideWorkspace = !relativePath.startsWith('..') && !isAbsolute(relativePath);
+    const expression = host === 'claude' && insideWorkspace
+        ? `\${CLAUDE_PROJECT_DIR}/${relativePath.split(sep).join('/')}`
+        : installedPath;
+    return { installedPath, expression, source: hookSource };
 }
 function diagnostic(code, message, source, hint) {
     return createDiagnostic({
@@ -211,7 +224,7 @@ function isExactManagedHook(value, commands) {
         typeof value.command === 'string' &&
         commands.has(value.command));
 }
-function managedConfig(host, existing, runtimeEntry, path) {
+function managedConfig(host, existing, hookExpression, path) {
     let base = {};
     if (existing !== null) {
         const parsed = parseJsonObject(existing, path);
@@ -219,7 +232,7 @@ function managedConfig(host, existing, runtimeEntry, path) {
             return parsed;
         base = parsed.value;
     }
-    const patch = renderHookConfigPatch(host, runtimeEntry);
+    const patch = renderHookConfigPatch(host, hookExpression);
     const rawHooks = base['hooks'];
     if (rawHooks !== undefined &&
         (typeof rawHooks !== 'object' ||
@@ -271,11 +284,11 @@ function managedConfig(host, existing, runtimeEntry, path) {
         bytes: Buffer.from(`${JSON.stringify(next, null, 2)}\n`),
     };
 }
-function validateManifestIdentity(manifest, host, hostRoot, configPath, runtimeEntry) {
+function validateManifestIdentity(manifest, host, hostRoot, configPath, hookExpression, migrate) {
     if (manifest.host !== host ||
         resolve(manifest.hostRoot) !== hostRoot ||
         manifest.configPath !== configPath ||
-        resolve(manifest.runtimeEntry) !== runtimeEntry) {
+        (!migrate && manifest.runtimeEntry !== hookExpression)) {
         return diagnostic(diagnosticCodes.host_install_conflict, `Host manifest identity does not match the selected target: ${hostRoot}`, join(hostRoot, BUNDLE_FILE), 'Inspect the manifest and target; Pappra does not adopt a foreign installation.');
     }
     const seen = new Set();
@@ -290,11 +303,11 @@ function validateManifestIdentity(manifest, host, hostRoot, configPath, runtimeE
     }
     return null;
 }
-function configHasExpectedHooks(host, bytes, runtimeEntry, path) {
+function configHasExpectedHooks(host, bytes, hookExpression, path) {
     const parsed = parseJsonObject(bytes, path);
     if (!parsed.ok)
         return false;
-    const patch = renderHookConfigPatch(host, runtimeEntry);
+    const patch = renderHookConfigPatch(host, hookExpression);
     const hooks = parsed.value['hooks'];
     if (typeof hooks !== 'object' || hooks === null || Array.isArray(hooks)) {
         return false;
@@ -329,7 +342,7 @@ function configHasExpectedHooks(host, bytes, runtimeEntry, path) {
     }
     return true;
 }
-function bundleManifestContent(bundle, hostRoot, runtimeEntry, configPath, files, observedAt) {
+function bundleManifestContent(bundle, hostRoot, hookExpression, configPath, files, observedAt) {
     return Buffer.from(`${JSON.stringify({
         schema: 'pappra/host-install/1',
         host: bundle.host,
@@ -337,7 +350,7 @@ function bundleManifestContent(bundle, hostRoot, runtimeEntry, configPath, files
         bundleDigest: bundle.bundleDigest,
         installedAt: observedAt,
         hostRoot,
-        runtimeEntry,
+        runtimeEntry: hookExpression,
         configPath,
         files: files.map((file) => ({
             path: file.path,
@@ -352,11 +365,13 @@ function bundleManifestContent(bundle, hostRoot, runtimeEntry, configPath, files
         trustRequired: true,
     }, null, 2)}\n`);
 }
-async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
+async function hostPlanFiles(host, workspaceRoot, hostRoot, hookSource, observedAt, migrate = false) {
+    const target = hookTarget(host, workspaceRoot, hostRoot, hookSource);
     let payload;
     try {
         payload = await loadHostBundle(host, getPackageInfo().version, {
-            runtimeEntry,
+            hookSource,
+            hookExpression: target.expression,
             observedAt,
         });
     }
@@ -401,7 +416,7 @@ async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
                 diagnostic: diagnostic(diagnosticCodes.host_install_conflict, `Host manifest is invalid and was preserved: ${manifestPath}`, manifestPath, 'Fix or remove the manifest explicitly; no managed file was overwritten.'),
             };
         }
-        const identityError = validateManifestIdentity(parsed.data, host, hostRoot, hostConfigRelativePath(host), runtimeEntry);
+        const identityError = validateManifestIdentity(parsed.data, host, hostRoot, hostConfigRelativePath(host), target.expression, migrate);
         if (identityError !== null) {
             return { ok: false, conflict: true, diagnostic: identityError };
         }
@@ -477,7 +492,7 @@ async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
             };
         }
         const before = existing.ok ? existing.value.bytes : null;
-        const merged = managedConfig(host === 'codex' ? 'codex' : 'claude', before, runtimeEntry, configPath);
+        const merged = managedConfig(host === 'codex' ? 'codex' : 'claude', before, target.expression, configPath);
         if (!merged.ok) {
             return {
                 ...merged,
@@ -510,7 +525,7 @@ async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
         })) {
         installedAt = installedManifest.installedAt;
     }
-    const manifest = bundleManifestContent(payload.bundle, hostRoot, runtimeEntry, hostConfigRelativePath(host), files, installedAt);
+    const manifest = bundleManifestContent(payload.bundle, hostRoot, target.expression, hostConfigRelativePath(host), files, installedAt);
     contents.set(BUNDLE_FILE, manifest);
     files.push({
         path: BUNDLE_FILE,
@@ -527,14 +542,14 @@ async function hostPlanFiles(host, hostRoot, runtimeEntry, observedAt) {
         configPath,
     };
 }
-function planFromFiles(host, workspaceRoot, hostRoot, runtimeEntry, bundleDigest, files) {
+function planFromFiles(host, workspaceRoot, hostRoot, hookExpression, bundleDigest, files) {
     return hostIntegrationPlanSchema.parse({
         schema: 'pappra/host-integration/1',
         planId: randomUUID(),
         host,
         workspaceRoot,
         hostRoot,
-        runtimeEntry,
+        runtimeEntry: hookExpression,
         bundleDigest,
         files,
         reloadRequired: true,
@@ -854,25 +869,47 @@ export class HostIntegrationService {
     }
     async plan(host, options = {}) {
         const hostRoot = resolve(options.hostRoot ?? join(this.#root, '.pappra', 'local', 'hosts', host));
-        const runtimeEntry = resolve(options.runtimeEntry ?? this.#runtimeEntry);
+        const hookSource = resolve(options.runtimeEntry ?? this.#runtimeEntry);
         const version = options.hostVersion ?? this.#hostVersion;
         if (!isSupportedVersion(host, version)) {
             throw new Error(`Host ${host} version ${version ?? '(unknown)'} is outside the pinned support matrix.`);
         }
-        if (!(await runtimeEntryReady(runtimeEntry))) {
-            throw new Error(`Fixed Pappra runtime entry is missing: ${runtimeEntry}`);
+        if (!(await runtimeEntryReady(hookSource))) {
+            throw new Error(`Bundled Pappra hook is missing: ${hookSource}`);
         }
-        const built = await hostPlanFiles(host, hostRoot, runtimeEntry, this.#observedAt);
+        const target = hookTarget(host, this.#root, hostRoot, hookSource);
+        const built = await hostPlanFiles(host, this.#root, hostRoot, hookSource, this.#observedAt, options.migrate === true);
         if (!built.ok)
             throw new Error(built.diagnostic.message);
-        return planFromFiles(host, this.#root, hostRoot, runtimeEntry, built.bundle.bundleDigest, built.files);
+        return planFromFiles(host, this.#root, hostRoot, target.expression, built.bundle.bundleDigest, built.files);
     }
     async install(host, options) {
+        if (options.mode === 'plugin') {
+            const support = HOST_PLUGIN_HOOKS[host];
+            const guidance = host === 'claude' && support.state === 'verified'
+                ? 'Export with `pappra host bundle --host claude --out <dir> --marketplace --json`, then run `claude plugin marketplace add <dir>` and `claude plugin install pappra@pappra-local`. Use --mode project-settings for automatic workspace wiring.'
+                : host === 'pi' && support.state === 'verified'
+                    ? 'Export with `pappra host bundle --host pi --out <dir> --json`, then run `pi install <dir> -l -a`. Use --mode project-settings for automatic workspace wiring.'
+                    : support.state === 'unsupported'
+                        ? 'This host does not load plugin hooks at its pinned version; keep --mode project-settings. See docs/host-plugin-validation.md.'
+                        : 'Plugin hooks are not verified for this host yet; an authenticated lifecycle session is required. Use --mode project-settings meanwhile.';
+            return hostIntegrationResultSchema.parse({
+                schema: 'pappra/host-integration/1',
+                ok: false,
+                status: 'unsupported',
+                plan: null,
+                appliedFiles: [],
+                residualPaths: [],
+                diagnostics: [
+                    diagnostic(diagnosticCodes.host_unavailable, `Plugin install mode is not wired for ${host}: ${support.state}. ${support.evidence}`, this.#root, guidance),
+                ],
+            });
+        }
         let plan;
         let contents;
         try {
             const hostRoot = resolve(options.hostRoot ?? join(this.#root, '.pappra', 'local', 'hosts', host));
-            const runtimeEntry = resolve(options.runtimeEntry ?? this.#runtimeEntry);
+            const hookSource = resolve(options.runtimeEntry ?? this.#runtimeEntry);
             const version = options.hostVersion ?? this.#hostVersion;
             if (!isSupportedVersion(host, version)) {
                 return hostIntegrationResultSchema.parse({
@@ -887,7 +924,7 @@ export class HostIntegrationService {
                     ],
                 });
             }
-            if (!(await runtimeEntryReady(runtimeEntry))) {
+            if (!(await runtimeEntryReady(hookSource))) {
                 return hostIntegrationResultSchema.parse({
                     schema: 'pappra/host-integration/1',
                     ok: false,
@@ -896,11 +933,12 @@ export class HostIntegrationService {
                     appliedFiles: [],
                     residualPaths: [],
                     diagnostics: [
-                        diagnostic(diagnosticCodes.host_unavailable, `Fixed Pappra runtime entry is missing: ${runtimeEntry}`, runtimeEntry, 'Install or select a complete Pappra runtime before wiring a host.'),
+                        diagnostic(diagnosticCodes.host_unavailable, `Bundled Pappra hook is missing: ${hookSource}`, hookSource, 'Install or select a complete Pappra runtime before wiring a host.'),
                     ],
                 });
             }
-            const built = await hostPlanFiles(host, hostRoot, runtimeEntry, this.#observedAt);
+            const target = hookTarget(host, this.#root, hostRoot, hookSource);
+            const built = await hostPlanFiles(host, this.#root, hostRoot, hookSource, this.#observedAt, options.migrate === true);
             if (!built.ok) {
                 return hostIntegrationResultSchema.parse({
                     schema: 'pappra/host-integration/1',
@@ -912,7 +950,7 @@ export class HostIntegrationService {
                     diagnostics: [built.diagnostic],
                 });
             }
-            plan = planFromFiles(host, this.#root, hostRoot, runtimeEntry, built.bundle.bundleDigest, built.files);
+            plan = planFromFiles(host, this.#root, hostRoot, target.expression, built.bundle.bundleDigest, built.files);
             contents = built.contents;
         }
         catch (error) {
@@ -1138,7 +1176,8 @@ export class HostIntegrationService {
             });
         }
         const expectedConfigPath = hostConfigRelativePath(host);
-        const identityError = validateManifestIdentity(manifest, host, hostRoot, expectedConfigPath, this.#runtimeEntry);
+        const target = hookTarget(host, this.#root, hostRoot, this.#runtimeEntry);
+        const identityError = validateManifestIdentity(manifest, host, hostRoot, expectedConfigPath, target.expression, false);
         if (identityError !== null) {
             return hostVerificationSchema.parse({
                 schema: 'pappra/host-verification/1',
@@ -1162,7 +1201,8 @@ export class HostIntegrationService {
         let currentBundle;
         try {
             currentBundle = await loadHostBundle(host, getPackageInfo().version, {
-                runtimeEntry: this.#runtimeEntry,
+                hookSource: this.#runtimeEntry,
+                hookExpression: target.expression,
                 observedAt: this.#observedAt,
             });
         }
@@ -1306,7 +1346,7 @@ export class HostIntegrationService {
             const config = await readFileBounded(configPath, DEFAULT_MAX_CONFIG_BYTES);
             if (!config.ok ||
                 manifestFiles.get(manifest.configPath) !== config.value.digest ||
-                !configHasExpectedHooks(host === 'codex' ? 'codex' : 'claude', config.value.bytes, this.#runtimeEntry, configPath)) {
+                !configHasExpectedHooks(host === 'codex' ? 'codex' : 'claude', config.value.bytes, target.expression, configPath)) {
                 status = 'conflict';
                 checks.push({
                     id: 'host.config',

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';
@@ -34,3 +37,23 @@ export declare const HOST_SUPPORT: {
 export declare function nativeEventFor(host: HostName, event: HostLifecycleEvent): string | null;
 export declare function isSupportedVersion(host: HostName, version: string | null): boolean;
 export declare function surfaceFor(host: HostName): (typeof HOST_SUPPORT)[HostName]['surface'];
+/**
+ * Observed plugin-hook support. `verified` means a real host session produced a
+ * `.pappra/local/host-events/<host>` record; `unsupported` means a control hook
+ * fired while the bundled plugin hook did not; `unverified` means no
+ * authenticated session was available. See docs/host-plugin-validation.md.
+ */
+export declare const HOST_PLUGIN_HOOKS: {
+    readonly pi: {
+        readonly state: 'verified';
+        readonly evidence: 'Pi 1.3.0 fires the packaged extension: `pi install <dir> -l -a` plus `pi -p -a` wrote a session_start event.';
+    };
+    readonly codex: {
+        readonly state: 'unsupported';
+        readonly evidence: 'Codex 0.163.0 does not load plugin hooks: a control hook in CODEX_HOME fired during `codex exec --dangerously-bypass-hook-trust` while the bundled plugin hook never ran, including with a .codex-plugin/plugin.json copy.';
+    };
+    readonly claude: {
+        readonly state: 'verified';
+        readonly evidence: 'Claude Code 2.1.292 passed `claude plugin validate`, then a project-scope marketplace install and `claude -p` wrote a SessionStart event from ${CLAUDE_PLUGIN_ROOT}/hooks/pappra-hook.mjs.';
+    };
+};

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',
@@ -39,3 +44,23 @@ export function isSupportedVersion(host, version) {
 export function surfaceFor(host) {
     return HOST_SUPPORT[host].surface;
 }
+/**
+ * Observed plugin-hook support. `verified` means a real host session produced a
+ * `.pappra/local/host-events/<host>` record; `unsupported` means a control hook
+ * fired while the bundled plugin hook did not; `unverified` means no
+ * authenticated session was available. See docs/host-plugin-validation.md.
+ */
+export const HOST_PLUGIN_HOOKS = {
+    pi: {
+        state: 'verified',
+        evidence: 'Pi 1.3.0 fires the packaged extension: `pi install <dir> -l -a` plus `pi -p -a` wrote a session_start event.',
+    },
+    codex: {
+        state: 'unsupported',
+        evidence: 'Codex 0.163.0 does not load plugin hooks: a control hook in CODEX_HOME fired during `codex exec --dangerously-bypass-hook-trust` while the bundled plugin hook never ran, including with a .codex-plugin/plugin.json copy.',
+    },
+    claude: {
+        state: 'verified',
+        evidence: 'Claude Code 2.1.292 passed `claude plugin validate`, then a project-scope marketplace install and `claude -p` wrote a SessionStart event from ${CLAUDE_PLUGIN_ROOT}/hooks/pappra-hook.mjs.',
+    },
+};

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

@@ -5,7 +5,7 @@ export interface RenderedHostTemplate {
     readonly bytes: Buffer;
     readonly kind: 'extension' | 'hook';
 }
-export declare function renderHookCommand(host: HostName, event: HostLifecycleEvent, runtimeEntry: string): string;
+export declare function renderHookCommand(host: HostName, event: HostLifecycleEvent, hookExpression: string): string;
 interface HookEntry {
     readonly hooks: readonly {
         readonly type: 'command';
@@ -13,10 +13,10 @@ interface HookEntry {
         readonly timeout: number;
     }[];
 }
-export declare function renderHookConfigPatch(host: 'codex' | 'claude', runtimeEntry: string): {
+export declare function renderHookConfigPatch(host: 'codex' | 'claude', hookExpression: string): {
     readonly hooks: Record<string, readonly HookEntry[]>;
 };
-export declare function renderHostTemplate(host: HostName, runtimeEntry: string): RenderedHostTemplate;
+export declare function renderHostTemplate(host: HostName, hookExpression: string): RenderedHostTemplate;
 export declare function hostConfigRelativePath(host: HostName): 'settings.json' | 'hooks.json' | null;
 export declare function hostConfigName(host: HostName): string;
 export {};

package/dist/hosts/integration/templates.js

@@ -1,18 +1,24 @@
-import { pathToFileURL } from 'node:url';
-import { basename, dirname } from 'node:path';
+import { basename } from 'node:path';
 export const PAPPRA_MANAGED_MARKER = 'pappra-managed';
 function shellQuote(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
-export function renderHookCommand(host, event, runtimeEntry) {
-    return `${shellQuote(process.execPath)} ${shellQuote(runtimeEntry)} ${shellQuote(host)} ${shellQuote(event)} # ${PAPPRA_MANAGED_MARKER}`;
+/**
+ * Host placeholders such as ${CLAUDE_PROJECT_DIR} only expand inside double
+ * quotes; absolute paths are single-quoted to survive spaces and quotes.
+ */
+function pathExpression(value) {
+    return value.includes('${') ? `"${value}"` : shellQuote(value);
+}
+export function renderHookCommand(host, event, hookExpression) {
+    return `${shellQuote(process.execPath)} ${pathExpression(hookExpression)} ${shellQuote(host)} ${shellQuote(event)} # ${PAPPRA_MANAGED_MARKER}`;
 }
-export function renderHookConfigPatch(host, runtimeEntry) {
+export function renderHookConfigPatch(host, hookExpression) {
     const entry = (event) => ({
         hooks: [
             {
                 type: 'command',
-                command: renderHookCommand(host, event, runtimeEntry),
+                command: renderHookCommand(host, event, hookExpression),
                 timeout: 1,
             },
         ],
@@ -30,15 +36,14 @@ export function renderHookConfigPatch(host, runtimeEntry) {
             },
         };
 }
-export function renderHostTemplate(host, runtimeEntry) {
+export function renderHostTemplate(host, hookExpression) {
     if (host === 'pi') {
-        const runtimeUrl = pathToFileURL(`${dirname(runtimeEntry)}/pi-extension-runtime.js`).href;
         const source = `/**
  * Generated Pappra Pi extension. It registers bounded local lifecycle handlers;
  * it does not start processes, models, network requests or background work.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createPiExtension } from ${JSON.stringify(runtimeUrl)};
+import { createPiExtension } from "./runtime.mjs";
 
 export default function (pi: ExtensionAPI): void {
   createPiExtension(pi);
@@ -50,7 +55,7 @@ export default function (pi: ExtensionAPI): void {
             kind: 'extension',
         };
     }
-    const patch = renderHookConfigPatch(host, runtimeEntry);
+    const patch = renderHookConfigPatch(host, hookExpression);
     return {
         path: `templates/${host}/hooks.json`,
         bytes: Buffer.from(`${JSON.stringify(patch, null, 2)}\n`),

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 = {