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

package/README.md

@@ -63,7 +63,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. `host install --mode plugin` fails closed until plugin registration and callability are verified in a real session.
+- **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).
 - **Bounded collaboration:** an optional, explicitly controlled one-request workflow. It is not a scheduler or daemon.
 
 ## Optional integrations and support
@@ -87,7 +87,7 @@ The check runs the source policy, type checks, formatting, deterministic tests a
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.5`) 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.5`, because pre-release versions are never republished.
+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.
 
 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/hosts/integration/bundle-export.js

@@ -67,17 +67,20 @@ export async function exportHostPluginBundle(options) {
     for (const [path, bytes] of payload.contents) {
         // Plugin manifests point at hooks/hooks.json directly; the rendered
         // templates are only an intermediate artifact.
-        if (options.host !== 'pi' && path.startsWith('templates/'))
+        if (path.startsWith('templates/'))
             continue;
         await writeEntry(`${pluginPrefix}${path}`, bytes);
     }
     const expression = pluginHookExpression(options.host);
     if (options.host === 'pi') {
         const entry = payload.contents.get('templates/pi/entry.ts');
-        if (entry === undefined) {
+        const runtime = payload.contents.get('templates/pi/runtime.mjs');
+        if (entry === undefined || runtime === undefined) {
             throw new Error('Pi plugin bundle is missing its extension entry.');
         }
+        // The generated entry imports ./runtime.mjs, so both files share one directory.
         await writeEntry(`${pluginPrefix}extensions/pappra/index.ts`, entry);
+        await writeEntry(`${pluginPrefix}extensions/pappra/runtime.mjs`, runtime);
     }
     else {
         const patch = renderHookConfigPatch(options.host, expression);

package/dist/hosts/integration/service.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',
@@ -885,6 +885,14 @@ export class HostIntegrationService {
     }
     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,
@@ -893,7 +901,7 @@ export class HostIntegrationService {
                 appliedFiles: [],
                 residualPaths: [],
                 diagnostics: [
-                    diagnostic(diagnosticCodes.host_unavailable, 'Plugin install mode is not wired: host registration, trust and callability are unverified.', this.#root, 'Use `pappra host bundle --host <name> --out <dir>` to export the plugin directory and register it yourself; project-settings install remains the verified mode.'),
+                    diagnostic(diagnosticCodes.host_unavailable, `Plugin install mode is not wired for ${host}: ${support.state}. ${support.evidence}`, this.#root, guidance),
                 ],
             });
         }

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

@@ -34,3 +34,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

@@ -39,3 +39,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/package.json

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