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

package/dist/hosts/integration/bundle-export.js

@@ -1,9 +1,12 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, rmdir, writeFile, } from 'node:fs/promises';
+import { basename, isAbsolute, dirname, join, resolve } from 'node:path';
 import { getPackageRoot } from '../../package-info.js';
 import { isPathInside } from '../../schemas/paths.js';
 import { loadHostBundle } from './bundle.js';
 import { renderHookConfigPatch } from './templates.js';
+import { readBoundedFile } from '../../infra/bounded-file.js';
+import { PI_RECOVERY_MAX_CONFIG_BYTES, readPiRecoveryConfig, } from './recovery-config.js';
+const BOOTSTRAP_EXTENSION_DIR = 'extensions/pappra-bootstrap';
 function pluginHookExpression(host) {
     return host === 'claude'
         ? '${CLAUDE_PLUGIN_ROOT}/hooks/pappra-hook.mjs'
@@ -38,6 +41,178 @@ function hostManifest(host, version) {
         },
     };
 }
+function bootstrapManifest(version) {
+    return {
+        name: '@phyzess/pappra-pi-bootstrap',
+        version,
+        description: 'Pappra Pi bootstrap package: opt-in successor gate with a private local task binding.',
+        type: 'module',
+        pi: {
+            extensions: [`./${BOOTSTRAP_EXTENSION_DIR}/index.ts`],
+            skills: ['./skills'],
+        },
+        peerDependencies: { '@earendil-works/pi-coding-agent': '*' },
+    };
+}
+function bootstrapEntry() {
+    return Buffer.from(`/**
+ * Generated Pappra Pi bootstrap extension. It registers the accepted default-deny
+ * successor gate from a private relative configuration; it installs, trusts, launches
+ * and dispatches nothing by itself.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import bootstrapExtension from "./runtime.mjs";
+
+export default function (pi: ExtensionAPI): void {
+  bootstrapExtension(pi);
+}
+`, 'utf8');
+}
+/**
+ * Reserves a private sibling staging directory next to the requested destination. Nothing is
+ * written through the final pathname: the payload is assembled here and published after an
+ * exclusive final claim, so a later substitution of the destination cannot redirect a write.
+ */
+async function beginBootstrapOutput(outDir) {
+    const resolved = resolve(outDir);
+    const finalName = basename(resolved);
+    if (finalName === '' || finalName === '.' || finalName === '..')
+        throw new Error('bootstrap bundle destination must be a directory path');
+    const parent = dirname(resolved);
+    let parentStat;
+    try {
+        parentStat = await lstat(parent);
+    }
+    catch {
+        throw new Error(`bootstrap bundle parent does not exist: ${parent}`);
+    }
+    if (!parentStat.isDirectory() || parentStat.isSymbolicLink())
+        throw new Error('bootstrap bundle parent must be a real directory');
+    const realParent = await realpath(parent);
+    const finalPath = join(realParent, finalName);
+    let existing = null;
+    try {
+        existing = await lstat(finalPath);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (existing !== null)
+        throw new Error('bootstrap bundle destination must not exist; pass a new private directory');
+    const stagePath = await mkdtemp(join(realParent, '.pappra-bootstrap-'));
+    const staged = await lstat(stagePath);
+    const stageReal = await realpath(stagePath);
+    return { finalPath, stagePath, stageReal, dev: staged.dev, ino: staged.ino };
+}
+const STAGE_DRIFT = 'bootstrap staging namespace changed during export';
+/**
+ * Fails closed on observed staging namespace drift (symlink, type change or device/inode
+ * change). This models a check/use boundary, not a general same-user filesystem fence: portable
+ * Node exposes no anchored directory writes.
+ */
+async function stageDrift(stage) {
+    try {
+        const current = await lstat(stage.stagePath);
+        if (current.isSymbolicLink() ||
+            !current.isDirectory() ||
+            current.dev !== stage.dev ||
+            current.ino !== stage.ino)
+            return STAGE_DRIFT;
+        const real = await realpath(stage.stagePath);
+        if (real !== stage.stageReal)
+            return STAGE_DRIFT;
+        return null;
+    }
+    catch {
+        return STAGE_DRIFT;
+    }
+}
+async function assertStage(stage) {
+    const drift = await stageDrift(stage);
+    if (drift !== null)
+        throw new Error(drift);
+}
+/** Removes only the staging directory this call created; substituted paths are retained. */
+async function discardStage(stage) {
+    try {
+        const current = await lstat(stage.stagePath);
+        if (current.isSymbolicLink() ||
+            current.dev !== stage.dev ||
+            current.ino !== stage.ino)
+            return;
+        await rm(stage.stagePath, { recursive: true, force: false });
+    }
+    catch {
+        // Missing or unreadable after a substitution: keep whatever is there.
+    }
+}
+/**
+ * Claims the final path with an exclusive `mkdir`, which is the only portable no-replace
+ * directory primitive. Anything already at the path (empty directory, file or symlink) makes
+ * this fail and is preserved.
+ */
+async function claimFinal(stage) {
+    await mkdir(stage.finalPath, { recursive: false, mode: 0o700 });
+    const claimed = await lstat(stage.finalPath);
+    return { dev: claimed.dev, ino: claimed.ino };
+}
+async function verifyClaim(stage, claim) {
+    const current = await lstat(stage.finalPath);
+    if (current.isSymbolicLink() ||
+        !current.isDirectory() ||
+        current.dev !== claim.dev ||
+        current.ino !== claim.ino)
+        throw new Error('bootstrap bundle destination changed during publication');
+}
+/** Removes the claim only when it is still the empty directory this call created. */
+async function releaseClaim(stage, claim) {
+    try {
+        const current = await lstat(stage.finalPath);
+        if (current.isSymbolicLink() ||
+            !current.isDirectory() ||
+            current.dev !== claim.dev ||
+            current.ino !== claim.ino)
+            return;
+        // A directory claim must be removed with the directory operation: `rm` with
+        // `recursive: false` rejects a directory (EISDIR) even when it is empty.
+        await rmdir(stage.finalPath);
+    }
+    catch {
+        // A substituted or non-empty destination is preserved.
+    }
+}
+/**
+ * Publishes the completed staged directory over the empty claim created by this call. The
+ * claim identity and the stage identity are re-checked first; the staged inode is verified
+ * after publication. A same-user process racing exactly between these checks is outside what
+ * portable Node can fence (no renameat2/RENAME_NOREPLACE or openat), and is documented as a
+ * check/use limit rather than claimed as prevented.
+ */
+async function publishStage(stage, claim) {
+    await verifyClaim(stage, claim);
+    await assertStage(stage);
+    await rename(stage.stagePath, stage.finalPath);
+    const final = await lstat(stage.finalPath);
+    if (final.isSymbolicLink() ||
+        !final.isDirectory() ||
+        final.dev !== stage.dev ||
+        final.ino !== stage.ino)
+        throw new Error('bootstrap publication did not produce the staged directory');
+}
+function piExtensionEntry(runtimeFile) {
+    return Buffer.from(`/** Generated opt-in Pi extension shim; it never installs or trusts itself. */\nimport type { ExtensionAPI } from "@earendil-works/pi-coding-agent";\nimport extension from "./${runtimeFile}";\n\nexport default function (pi: ExtensionAPI): void {\n  extension(pi);\n}\n`, 'utf8');
+}
+function piExtensionManifest(version, extensions) {
+    return {
+        name: '@phyzess/pappra-pi-collaboration',
+        version,
+        description: 'Opt-in Pappra Pi collaboration extensions.',
+        type: 'module',
+        pi: { extensions: [...extensions], skills: ['./skills'] },
+        peerDependencies: { '@earendil-works/pi-coding-agent': '*' },
+    };
+}
 /**
  * Writes a host-native plugin/package directory. This is an artifact export: it
  * does not register the plugin with a host, and it never claims the host will
@@ -48,13 +223,201 @@ export async function exportHostPluginBundle(options) {
     if (options.marketplace === true && options.host === 'pi') {
         throw new Error('Pi installs a directory directly; a marketplace wrapper is not supported.');
     }
+    if (options.bootstrap !== undefined && options.host !== 'pi')
+        throw new Error('bootstrap bundles are supported for the Pi host only');
+    if (options.bootstrap !== undefined && options.marketplace === true)
+        throw new Error('bootstrap bundles cannot be wrapped in a marketplace');
+    if ((options.recovery !== undefined || options.transition !== undefined) &&
+        options.host !== 'pi')
+        throw new Error('recovery and transition bundles are supported for the Pi host only');
+    if (options.bootstrap !== undefined &&
+        (options.recovery !== undefined || options.transition !== undefined))
+        throw new Error('bootstrap bundles cannot be combined with recovery or transition extensions');
+    if ((options.recovery !== undefined || options.transition !== undefined) &&
+        options.marketplace === true)
+        throw new Error('recovery and transition bundles cannot be wrapped in a marketplace');
     const pluginPrefix = options.marketplace === true ? 'pappra/' : '';
     const pluginRoot = options.marketplace === true ? join(outRoot, 'pappra') : outRoot;
+    const hookSource = join(getPackageRoot(), 'dist/hosts/integration/pappra-hook.mjs');
     const payload = await loadHostBundle(options.host, options.packageVersion, {
-        hookSource: join(getPackageRoot(), 'dist/hosts/integration/pappra-hook.mjs'),
+        hookSource,
         hookExpression: pluginHookExpression(options.host),
     });
     const written = [];
+    if (options.bootstrap !== undefined) {
+        const bootstrap = options.bootstrap;
+        let artifact;
+        try {
+            artifact = await readFile(bootstrap.artifactPath);
+        }
+        catch {
+            throw new Error(`bootstrap extension artifact is missing: ${bootstrap.artifactPath}; build the package first`);
+        }
+        if (options.marketplace === true)
+            throw new Error('bootstrap bundles cannot be wrapped in a marketplace');
+        const staged = await beginBootstrapOutput(options.outDir);
+        let claim = null;
+        try {
+            const writeEntry = async (path, bytes, mode) => {
+                const target = join(staged.stagePath, ...path.split('/'));
+                if (!isPathInside(staged.stagePath, target))
+                    throw new Error(`Unsafe plugin bundle path: ${path}`);
+                await assertStage(staged);
+                await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+                await assertStage(staged);
+                await writeFile(target, bytes, mode === undefined ? undefined : { mode });
+                await assertStage(staged);
+                written.push(path);
+            };
+            for (const [path, bytes] of payload.contents) {
+                if (!path.startsWith('skills/'))
+                    continue;
+                await writeEntry(path, bytes);
+            }
+            await writeEntry(`${BOOTSTRAP_EXTENSION_DIR}/index.ts`, bootstrapEntry());
+            await writeEntry(`${BOOTSTRAP_EXTENSION_DIR}/runtime.mjs`, artifact);
+            await writeEntry('package.json', Buffer.from(`${JSON.stringify(bootstrapManifest(options.packageVersion), null, 2)}\n`));
+            // The private binding is written last so a staging substitution is detected before it.
+            await writeEntry(`${BOOTSTRAP_EXTENSION_DIR}/bootstrap.json`, bootstrap.configBytes, 0o600);
+            claim = await claimFinal(staged);
+            await publishStage(staged, claim);
+        }
+        catch (error) {
+            await discardStage(staged);
+            if (claim !== null)
+                await releaseClaim(staged, claim);
+            throw error;
+        }
+        return {
+            host: options.host,
+            outDir: staged.finalPath,
+            files: written.sort((left, right) => left.localeCompare(right)),
+            pluginManifest: 'package.json',
+            hookConfig: null,
+            registration: [
+                'Install the directory as a Pi package only after reviewing the private binding; Pappra does not install or trust it.',
+                'Loading is not enforced gating; check the read-only bootstrap status before any model work.',
+            ],
+            verification: 'unsupported',
+            bootstrap: {
+                schema: bootstrap.config.schema,
+                configDigest: bootstrap.configDigest,
+                mode: 'deny-until-completed-transfer',
+                registeredByExport: false,
+            },
+        };
+    }
+    if (options.recovery !== undefined || options.transition !== undefined) {
+        let recoveryBytes = null;
+        let recoverySchema = null;
+        let recoveryDigest = null;
+        if (options.recovery !== undefined) {
+            if (!isAbsolute(options.recovery.configFile))
+                throw new Error('recovery config path must be absolute');
+            const validated = readPiRecoveryConfig(options.recovery.configFile);
+            if (!validated.ok)
+                throw new Error(`recovery config is invalid (${validated.code})`);
+            const pinned = readBoundedFile(options.recovery.configFile, PI_RECOVERY_MAX_CONFIG_BYTES);
+            if (!pinned.ok || pinned.digest !== validated.digest)
+                throw new Error('recovery config changed or became unreadable during validation');
+            recoveryBytes = pinned.bytes;
+            recoverySchema = validated.config.schema;
+            recoveryDigest = validated.digest;
+        }
+        let recoveryArtifact = null;
+        let transitionArtifact = null;
+        try {
+            if (options.recovery !== undefined)
+                recoveryArtifact = await readFile(options.recovery.artifactPath);
+            if (options.transition !== undefined)
+                transitionArtifact = await readFile(options.transition.artifactPath);
+        }
+        catch {
+            throw new Error('an opt-in Pi extension artifact is missing; build the package before exporting');
+        }
+        const staged = await beginBootstrapOutput(options.outDir);
+        let claim = null;
+        const extensionPaths = [];
+        try {
+            const writeEntry = async (path, bytes, mode) => {
+                const target = join(staged.stagePath, ...path.split('/'));
+                if (!isPathInside(staged.stagePath, target))
+                    throw new Error(`Unsafe plugin bundle path: ${path}`);
+                await assertStage(staged);
+                await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+                await assertStage(staged);
+                await writeFile(target, bytes, mode === undefined ? undefined : { mode });
+                await assertStage(staged);
+                written.push(path);
+            };
+            for (const [path, bytes] of payload.contents) {
+                if (path.startsWith('skills/'))
+                    await writeEntry(path, bytes);
+            }
+            if (recoveryArtifact !== null) {
+                const directory = 'extensions/pappra-recovery';
+                await writeEntry(`${directory}/index.ts`, piExtensionEntry('runtime.mjs'));
+                await writeEntry(`${directory}/runtime.mjs`, recoveryArtifact);
+                extensionPaths.push(`./${directory}/index.ts`);
+            }
+            if (transitionArtifact !== null) {
+                const directory = 'extensions/pappra-session-transition';
+                await writeEntry(`${directory}/index.ts`, piExtensionEntry('runtime.mjs'));
+                await writeEntry(`${directory}/runtime.mjs`, transitionArtifact);
+                extensionPaths.push(`./${directory}/index.ts`);
+            }
+            await writeEntry('package.json', Buffer.from(`${JSON.stringify(piExtensionManifest(options.packageVersion, extensionPaths), null, 2)}\n`));
+            if (recoveryBytes !== null)
+                await writeEntry('extensions/pappra-recovery/recovery.json', recoveryBytes, 0o600);
+            claim = await claimFinal(staged);
+            await publishStage(staged, claim);
+        }
+        catch (error) {
+            await discardStage(staged);
+            if (claim !== null)
+                await releaseClaim(staged, claim);
+            throw error;
+        }
+        const registration = [
+            'Review and install this opt-in Pi package explicitly; export does not register, trust, enable or launch it.',
+            ...(recoveryArtifact === null
+                ? []
+                : [
+                    'Recovery requires the explicitly selected private task config and only runs on supported observed startup/settled/manual triggers; no reconnect event or generic outage recovery is claimed.',
+                ]),
+            ...(transitionArtifact === null
+                ? []
+                : [
+                    'The transition command remains blocked without native quiescence proof; task retirement is not native session archive or automatic takeover.',
+                ]),
+        ];
+        return {
+            host: 'pi',
+            outDir: staged.finalPath,
+            files: written.sort((left, right) => left.localeCompare(right)),
+            pluginManifest: 'package.json',
+            hookConfig: null,
+            registration,
+            verification: 'unsupported',
+            ...(recoverySchema === null || recoveryDigest === null
+                ? {}
+                : {
+                    recovery: {
+                        schema: recoverySchema,
+                        configDigest: recoveryDigest,
+                        registeredByExport: false,
+                    },
+                }),
+            ...(transitionArtifact === null
+                ? {}
+                : {
+                    transition: {
+                        registeredByExport: false,
+                        nativeQuiescence: 'unavailable',
+                    },
+                }),
+        };
+    }
     const writeEntry = async (path, bytes) => {
         const target = join(outRoot, ...path.split('/'));
         if (!isPathInside(outRoot, target)) {

package/dist/hosts/integration/bundle.js

@@ -27,6 +27,9 @@ export function installPathForBundleFile(host, sourcePath) {
     if (host === 'pi' && sourcePath === 'templates/pi/entry.ts') {
         return 'extensions/pappra/index.ts';
     }
+    if (host === 'pi' && sourcePath === 'templates/pi/runtime.mjs') {
+        return 'extensions/pappra/runtime.mjs';
+    }
     return sourcePath;
 }
 /**

package/dist/hosts/integration/hook.js

@@ -6,11 +6,12 @@ import { diagnosticCodes } from '../../schemas/errors.js';
 import { HOST_HOOK_INPUT_SCHEMA, commandHookEventSchema, hostHookInputSchema, hostHookResultSchema, } from '../../schemas/host.js';
 import { observePath, readFileBounded, resolveRealpath, sha256Digest, } from '../../infra/fs.js';
 import { isPathInside } from '../../schemas/paths.js';
+import { ensurePrivateState } from '../../infra/private-state.js';
 import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
 import { inspectMachineConfig, loadWorkspaceConfig, } from '../../workspace/config.js';
 import { CheckpointService } from '../../continuity/service.js';
 import { ensureStatePathBoundary } from '../../install/ownership.js';
-import { readAutoResume, readTaskPin } from '../../app/task-pin.js';
+import { readAutoResume, readTaskPin } from '../../continuity/task-pin.js';
 import { nativeEventFor } from './support.js';
 const DEFAULT_MAX_INPUT_BYTES = 1024 * 1024;
 const DEFAULT_DEADLINE_MS = 1000;
@@ -40,6 +41,9 @@ function result(input) {
 export function renderHostHookOutput(host, result) {
     if (result.context === null || result.event === null)
         return null;
+    // PostCompact is an observation hook, not SessionStart context injection.
+    if (host === 'claude' && result.event === 'compact')
+        return null;
     const context = result.context.length > 8000
         ? `${result.context.slice(0, 7997)}...`
         : result.context;
@@ -84,9 +88,9 @@ async function privateSegmentsSafe(root, directory) {
     }
     return true;
 }
-async function boundedAdvisory(root, event, taskId, workspaceName) {
+async function boundedAdvisory(root, event, taskId, workspaceName, workspaceId) {
     const lines = [
-        `Pappra workspace "${workspaceName}" is registered for lifecycle event ${event}.`,
+        `Pappra workspace ${JSON.stringify(workspaceName)} is registered for lifecycle event ${event}.`,
     ];
     if (taskId === null) {
         lines.push('No explicit task was selected; run `pappra checkpoint --task <id>` or `pappra resume <id>` for manual continuity.');
@@ -97,14 +101,18 @@ async function boundedAdvisory(root, event, taskId, workspaceName) {
             taskId,
             currentSession: null,
         });
-        if (!resumed.ok || resumed.packet === null) {
+        if (!resumed.ok ||
+            resumed.packet === null ||
+            resumed.packet.workspaceId !== workspaceId ||
+            resumed.packet.taskId !== taskId ||
+            resumed.packet.identityChecks.some((check) => check.status !== 'ok')) {
             lines.push(`Checkpoint ${taskId} is unavailable or incomplete; manual pappra checkpoint/resume is required.`);
         }
         else {
             lines.push(`Checkpoint ${taskId} is available for manual review.`);
-            lines.push(`Objective: ${resumed.packet.boundedContext.objective}`);
+            lines.push(`Advisory objective: ${JSON.stringify(resumed.packet.boundedContext.objective)}`);
             if (resumed.packet.boundedContext.nextActions.length > 0) {
-                lines.push(`Next actions: ${resumed.packet.boundedContext.nextActions.join('; ')}`);
+                lines.push(`Advisory next actions: ${JSON.stringify(resumed.packet.boundedContext.nextActions)}`);
             }
             if (!resumed.packet.executionAllowed) {
                 lines.push('Context does not authorize execution; inspect blockers before acting.');
@@ -218,9 +226,12 @@ export function mapNativeHookEvent(host, raw, _fallbackEvent, _fallbackCwd) {
     if (native === 'SessionStart') {
         const source = parsed.data.source;
         event =
-            source === 'resume'
+            source === 'resume' || source === 'compact'
                 ? 'resume'
-                : source === undefined || source === 'startup' || source === 'new'
+                : source === undefined ||
+                    source === 'startup' ||
+                    source === 'new' ||
+                    source === 'clear'
                     ? 'startup'
                     : null;
     }
@@ -461,6 +472,22 @@ export async function runHostHook(input, options = {}) {
             ],
         });
     }
+    const privateState = await ensurePrivateState(root);
+    if (!privateState.ok) {
+        return result({
+            ok: false,
+            status: 'failed',
+            host: value.host,
+            event: value.event,
+            eventKey,
+            duplicate: false,
+            context: null,
+            diagnostics: [
+                diagnostic(privateState.code, privateState.message, root, privateState.nextAction ??
+                    'Protect private workspace state before recording the host event.'),
+            ],
+        });
+    }
     await mkdir(directory, { recursive: true, mode: 0o700 });
     const directoryAfter = await observePath(directory);
     const realDirectory = await resolveRealpath(directory);
@@ -492,7 +519,7 @@ export async function runHostHook(input, options = {}) {
     };
     const pinnedTask = await readTaskPin(root);
     const autoResume = pinnedTask !== null && (await readAutoResume(root));
-    const context = await boundedAdvisory(root, value.event, value.taskId ?? (autoResume ? pinnedTask.taskId : null), workspaceRead.value.name);
+    const context = await boundedAdvisory(root, value.event, value.taskId ?? (autoResume ? pinnedTask.taskId : null), workspaceRead.value.name, workspaceRead.value.workspaceId);
     if (clock() - started > deadline) {
         return result({
             ok: false,