@phyzess/pappra 0.1.0-beta.14 → 0.1.0-beta.19

package/dist/hosts/pilot.d.ts

@@ -28,6 +28,8 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
     reservation?: never;
     refused: boolean;
     admission: {
+        state?: never;
+        state_revision?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
@@ -36,10 +38,6 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
-        detail?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -50,19 +48,19 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        expected?: never;
+        state?: never;
+        state_revision?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
-        detail: string;
+        actual: string;
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
-        expected?: never;
-        actual?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -73,19 +71,42 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        expected?: never;
+        actual?: never;
+        state?: never;
+        state_revision?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
+        detail: string;
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
-        detail?: never;
+        attempt_state?: never;
+        resources?: never;
+        mode?: never;
+        launch_kind?: never;
+        resume_selector?: never;
+        pre_bound_identity?: never;
+        expected_identity?: never;
+        capability_evidence?: never;
+        assignment_digest?: never;
+        input_revision?: never;
+        owner_epoch?: never;
+    } | {
         expected?: never;
         actual?: never;
+        state?: never;
         state_revision?: never;
-        owner_epoch?: never;
+        ok: false;
+        reason: string;
+        checks: Record<string, unknown>[];
+        required_skills?: never;
+        required_tools?: never;
+        preflight?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -96,7 +117,11 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        state?: never;
+        state_revision?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
@@ -105,10 +130,6 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
-        detail?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -119,12 +140,16 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        state?: never;
+        state_revision?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
-        expected: import("../collab/types.js").Identity;
-        actual: import("../collab/types.js").Identity & {
+        expected: import("../schemas/collaboration-state.js").Identity;
+        actual: import("../schemas/collaboration-state.js").Identity & {
             harness: string;
             cwd: string;
             surface: string;
@@ -133,10 +158,6 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
-        detail?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -147,7 +168,11 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        state?: never;
+        state_revision?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
@@ -157,9 +182,6 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -170,19 +192,18 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
     } | {
+        expected?: never;
+        actual?: never;
+        state?: never;
+        state_revision?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
         required_skills: number;
         required_tools: number;
         preflight?: never;
-        state?: never;
-        detail?: never;
-        expected?: never;
-        actual?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -193,7 +214,13 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        expected?: never;
+        actual?: never;
+        state?: never;
+        state_revision?: never;
         required_skills?: never;
         required_tools?: never;
         ok: false;
@@ -220,12 +247,6 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
             warnings: import("../collab/preflight.js").Check[];
             limits: string[];
         };
-        state?: never;
-        detail?: never;
-        expected?: never;
-        actual?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -236,7 +257,12 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        expected?: never;
+        actual?: never;
+        state_revision?: never;
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
@@ -244,11 +270,6 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         reason: string;
         checks: Record<string, unknown>[];
         state: string;
-        detail?: never;
-        expected?: never;
-        actual?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -259,19 +280,19 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        state?: never;
+        state_revision?: never;
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
         expected: (string | null)[];
         actual: string;
-        detail?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         resources?: never;
         mode?: never;
@@ -282,20 +303,21 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        expected?: never;
+        actual?: never;
+        state?: never;
+        state_revision?: never;
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
         resources: Record<string, unknown>[];
         detail: string;
-        expected?: never;
-        actual?: never;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         mode?: never;
         launch_kind?: never;
@@ -305,20 +327,19 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
     } | {
+        state?: never;
+        state_revision?: never;
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
-        detail?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
         resources: Record<string, unknown>[];
         expected: number | undefined;
         actual: number;
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         mode?: never;
         launch_kind?: never;
@@ -328,20 +349,20 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     } | {
+        expected?: never;
+        actual?: never;
+        state?: never;
+        state_revision?: never;
         required_skills?: never;
         required_tools?: never;
         preflight?: never;
-        state?: never;
-        detail?: never;
-        expected?: never;
-        actual?: never;
         ok: false;
         reason: string;
         checks: Record<string, unknown>[];
         resources: Record<string, unknown>[];
-        state_revision?: never;
-        owner_epoch?: never;
         attempt_state?: never;
         mode?: never;
         launch_kind?: never;
@@ -351,6 +372,8 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence?: never;
         assignment_digest?: never;
         input_revision?: never;
+        owner_epoch?: never;
+        detail?: never;
     };
     reason: string;
     process?: never;
@@ -366,14 +389,13 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
 } | {
     refused: boolean;
     admission: {
-        required_skills?: never;
-        required_tools?: never;
-        preflight?: never;
-        state?: never;
-        detail?: never;
         expected?: never;
         actual?: never;
+        state?: never;
         reason?: never;
+        required_skills?: never;
+        required_tools?: never;
+        preflight?: never;
         ok: true;
         checks: Record<string, unknown>[];
         state_revision: number;
@@ -388,6 +410,7 @@ export declare function runNativePilot({ harness, profile, cwd, promptFile, evid
         capability_evidence: string;
         assignment_digest: string;
         input_revision: string | null;
+        detail?: never;
     };
     reason: string;
     reservation: {

package/dist/hosts/pilot.js

@@ -6,7 +6,7 @@ import { spawn } from 'node:child_process';
 import { admitLaunch, reserveLaunch, settleLaunch, classifyIdentity, TOOL_PROFILES, } from '../collab/admission.js';
 import { createNonce, nowIso } from '../collab/store.js';
 import { sha256File as digestFile } from '../collab/envelope.js';
-import { object, parseJson } from '../collab/validation.js';
+import { object, parseJson } from '../infra/validation.js';
 import { isAssignment } from '../collab/contracts.js';
 const PHASES = new Set([
     'discovery',
@@ -28,6 +28,7 @@ function buildArgv({ harness, profile, cwd, prompt, sessionId, resume, maxBudget
             ...(trustProject ? ['--approve'] : []),
             resume ? '--session' : '--session-id',
             (resume ?? sessionId),
+            '--',
             prompt,
         ];
         return { command: 'pi', argv, session_selector: resume ?? sessionId };
@@ -46,6 +47,7 @@ function buildArgv({ harness, profile, cwd, prompt, sessionId, resume, maxBudget
                 '--skip-git-repo-check',
                 '-c',
                 `sandbox_mode="${sandbox}"`,
+                '--',
                 prompt,
             ]
             : [
@@ -56,6 +58,7 @@ function buildArgv({ harness, profile, cwd, prompt, sessionId, resume, maxBudget
                 '-s',
                 sandbox,
                 '--skip-git-repo-check',
+                '--',
                 prompt,
             ];
         return { command: 'codex', argv: base, session_selector: resume ?? null };
@@ -88,6 +91,7 @@ function buildArgv({ harness, profile, cwd, prompt, sessionId, resume, maxBudget
             String(maxBudgetUsd),
             resume ? '--resume' : '--session-id',
             (resume ?? sessionId),
+            '--',
             prompt,
         ];
         return { command: 'claude', argv, session_selector: resume ?? sessionId };

package/dist/hosts/version.d.ts

@@ -0,0 +1,3 @@
+import type { HostName } from '../schemas/host.js';
+/** Bounded executable observation only; never sends a prompt or starts a model. */
+export declare function observeHostVersion(host: HostName, pathEnv: string): string | null;

package/dist/hosts/version.js

@@ -0,0 +1,18 @@
+import { spawnSync } from 'node:child_process';
+import { executableOnPath } from './detect.js';
+/** Bounded executable observation only; never sends a prompt or starts a model. */
+export function observeHostVersion(host, pathEnv) {
+    const executable = executableOnPath(host, pathEnv);
+    if (!executable)
+        return null;
+    const result = spawnSync(executable, ['--version'], {
+        encoding: 'utf8',
+        shell: false,
+        timeout: 5000,
+        maxBuffer: 16 * 1024,
+        env: { ...process.env, PATH: pathEnv },
+    });
+    if (result.error || result.status !== 0)
+        return null;
+    return (/(?:^|\s)([0-9]+\.[0-9]+\.[0-9]+)(?:\s|$)/.exec(`${result.stdout}\n${result.stderr}`)?.[1] ?? null);
+}

package/dist/index.d.ts

@@ -2,4 +2,3 @@ export { getPackageInfo, getPackageRoot } from './package-info.js';
 export type { PackageInfo } from './package-info.js';
 export { HostAdapter, HostIntegrationService, type HostIntegrationOptions, type HostTargetOptions, } from './hosts/integration/service.js';
 export { mapNativeHookEvent, runHostHook, type HostHookOptions, type NativeHookMapping, } from './hosts/integration/hook.js';
-export * from './app/collaboration.js';

package/dist/index.js

@@ -1,4 +1,3 @@
 export { getPackageInfo, getPackageRoot } from './package-info.js';
 export { HostAdapter, HostIntegrationService, } from './hosts/integration/service.js';
 export { mapNativeHookEvent, runHostHook, } from './hosts/integration/hook.js';
-export * from './app/collaboration.js';

package/dist/infra/bounded-file.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bounded, read-only access to one explicit regular file.
+ *
+ * The pathname is observed first so obviously unsafe entries are refused without
+ * opening them. The open itself is nonblocking/no-follow on POSIX, so a regular
+ * file replaced by a FIFO or symlink between inspection and open cannot block or
+ * redirect the read; the descriptor is re-validated afterwards for type and size.
+ */
+export type BoundedFileFailureCode = 'path_not_absolute' | 'symlink' | 'not_regular' | 'too_large' | 'unreadable';
+export type BoundedFileResult = {
+    readonly ok: true;
+    readonly bytes: Buffer;
+    readonly text: string;
+    readonly digest: string;
+} | {
+    readonly ok: false;
+    readonly code: BoundedFileFailureCode;
+};
+export declare function readBoundedFile(file: string, maxBytes: number): BoundedFileResult;

package/dist/infra/bounded-file.js

@@ -0,0 +1,66 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const digestOf = (bytes) => `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+const nonblockingFlag = () => process.platform === 'win32' ? 0 : (fs.constants.O_NONBLOCK ?? 0);
+export function readBoundedFile(file, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) {
+        throw new Error('Bounded read limit must be a positive integer.');
+    }
+    if (!path.isAbsolute(file)) {
+        return { ok: false, code: 'path_not_absolute' };
+    }
+    let observed;
+    try {
+        observed = fs.lstatSync(file);
+    }
+    catch {
+        return { ok: false, code: 'unreadable' };
+    }
+    if (observed.isSymbolicLink())
+        return { ok: false, code: 'symlink' };
+    if (!observed.isFile())
+        return { ok: false, code: 'not_regular' };
+    if (observed.size > maxBytes)
+        return { ok: false, code: 'too_large' };
+    const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | nonblockingFlag();
+    let handle;
+    try {
+        handle = fs.openSync(file, flags);
+    }
+    catch (error) {
+        const code = typeof error === 'object' && error !== null && 'code' in error
+            ? String(error.code)
+            : null;
+        return { ok: false, code: code === 'ELOOP' ? 'symlink' : 'unreadable' };
+    }
+    try {
+        const stat = fs.fstatSync(handle);
+        if (!stat.isFile())
+            return { ok: false, code: 'not_regular' };
+        if (stat.size > maxBytes)
+            return { ok: false, code: 'too_large' };
+        // Read at most the observed size (already bounded); never read until EOF.
+        const bytes = Buffer.alloc(stat.size);
+        let total = 0;
+        while (total < bytes.length) {
+            const read = fs.readSync(handle, bytes, total, bytes.length - total, total);
+            if (read === 0)
+                break;
+            total += read;
+        }
+        const content = bytes.subarray(0, total);
+        return {
+            ok: true,
+            bytes: content,
+            text: content.toString('utf8'),
+            digest: digestOf(content),
+        };
+    }
+    catch {
+        return { ok: false, code: 'unreadable' };
+    }
+    finally {
+        fs.closeSync(handle);
+    }
+}

package/dist/infra/fs.js

@@ -51,9 +51,17 @@ export async function readFileBounded(path, maxBytes = DEFAULT_CONFIG_MAX_BYTES)
         if (!stats.isFile()) {
             return failed(diagnosticCodes.fileNotRegular, `Not a regular file: ${path}`, { nextAction: 'Replace it with a regular file.' });
         }
-        const buffer = Buffer.allocUnsafe(maxBytes + 1);
+        // Size the allocation to the opened file, rather than the caller's ceiling.
+        // Keep one extra byte to detect overflow, including files that grow after
+        // fstat; a small runtime dependency must not allocate the 64 MiB ceiling.
+        let buffer = Buffer.allocUnsafe(Math.min(stats.size, maxBytes) + 1);
         let total = 0;
-        while (total < buffer.length) {
+        while (total <= maxBytes) {
+            if (total === buffer.length) {
+                const grown = Buffer.allocUnsafe(Math.min(maxBytes + 1, Math.max(4096, buffer.length * 2)));
+                buffer.copy(grown, 0, 0, total);
+                buffer = grown;
+            }
             const { bytesRead } = await handle.read(buffer, total, buffer.length - total, null);
             if (bytesRead === 0)
                 break;

package/dist/infra/git.d.ts

@@ -45,6 +45,12 @@ export interface InspectGitRepositoryOptions {
     readonly timeoutMs?: number;
     readonly maxOutputBytes?: number;
     readonly signal?: AbortSignal;
+    /**
+     * Set to `false` when the caller derives working-tree state from its own
+     * diffs. The observation then reports `dirty: null` instead of spawning an
+     * additional `git status` scan.
+     */
+    readonly workingTreeState?: boolean;
 }
 /**
  * Observes a repository without modifying the index, refs, or working tree.
@@ -58,3 +64,26 @@ export declare function inspectGitRepository(candidateRoot: string, options?: In
  * "nothing is ignored".
  */
 export declare function filterGitIgnored(repositoryRoot: string, candidates: readonly string[], options?: InspectGitRepositoryOptions): Promise<Outcome<readonly string[]>>;
+export interface GitObservationScope {
+    readonly repository: (root: string, options?: InspectGitRepositoryOptions) => Promise<Outcome<GitRepositoryObservation>>;
+}
+export interface GitObservationScopeOptions {
+    /**
+     * Default for `InspectGitRepositoryOptions.workingTreeState`; `true` keeps the
+     * `inspectGitRepository` behaviour. Callers that derive working-tree state from
+     * their own diffs opt out to save one `git status` scan per checkout.
+     */
+    readonly workingTreeState?: boolean;
+}
+/**
+ * Memoizes Git repository probes for exactly one operation.
+ *
+ * Repository identity (root, git dir, HEAD, branch) is immutable for the
+ * duration of a single command, so repeated inspections of the same checkout
+ * reuse the first observation instead of spawning equivalent Git processes.
+ * Working-tree state is *not* immutable: the scope therefore only lives inside
+ * one operation and must never be reused across operations or persisted. Callers
+ * that re-observe a tree after mutation (code prepare) keep using the scope for
+ * identity probes while the working-tree diff is always re-read.
+ */
+export declare function createGitObservationScope(options?: GitObservationScopeOptions): GitObservationScope;

package/dist/infra/git.js

@@ -20,6 +20,7 @@ function sanitizedGitEnvironment() {
         'GIT_CEILING_DIRECTORIES',
         'GIT_CONFIG_COUNT',
         'GIT_CONFIG_PARAMETERS',
+        'GIT_EXTERNAL_DIFF',
     ]) {
         delete environment[key];
     }
@@ -281,17 +282,22 @@ export async function inspectGitRepository(candidateRoot, options = {}) {
         limitations.push('branch unavailable');
     }
     let dirty = null;
-    const statusResult = await run([
-        'status',
-        '--porcelain=v1',
-        '-z',
-        '--untracked-files=normal',
-    ]);
-    if (statusResult.ok) {
-        dirty = statusResult.value.stdout.length > 0;
+    if (options.workingTreeState === false) {
+        limitations.push('working tree state not requested');
     }
     else {
-        limitations.push(`working tree state unavailable: ${statusResult.message}`);
+        const statusResult = await run([
+            'status',
+            '--porcelain=v1',
+            '-z',
+            '--untracked-files=normal',
+        ]);
+        if (statusResult.ok) {
+            dirty = statusResult.value.stdout.length > 0;
+        }
+        else {
+            limitations.push(`working tree state unavailable: ${statusResult.message}`);
+        }
     }
     const kind = isBare
         ? 'bare'
@@ -356,3 +362,33 @@ export async function filterGitIgnored(repositoryRoot, candidates, options = {})
     }
     return succeeded(ignored);
 }
+/**
+ * Memoizes Git repository probes for exactly one operation.
+ *
+ * Repository identity (root, git dir, HEAD, branch) is immutable for the
+ * duration of a single command, so repeated inspections of the same checkout
+ * reuse the first observation instead of spawning equivalent Git processes.
+ * Working-tree state is *not* immutable: the scope therefore only lives inside
+ * one operation and must never be reused across operations or persisted. Callers
+ * that re-observe a tree after mutation (code prepare) keep using the scope for
+ * identity probes while the working-tree diff is always re-read.
+ */
+export function createGitObservationScope(options = {}) {
+    const defaultWorkingTreeState = options.workingTreeState ?? true;
+    const observations = new Map();
+    return {
+        repository(root, inspectOptions = {}) {
+            const workingTreeState = inspectOptions.workingTreeState ?? defaultWorkingTreeState;
+            const key = JSON.stringify([resolve(root), workingTreeState]);
+            const cached = observations.get(key);
+            if (cached !== undefined)
+                return cached;
+            const pending = inspectGitRepository(root, {
+                ...inspectOptions,
+                workingTreeState,
+            });
+            observations.set(key, pending);
+            return pending;
+        },
+    };
+}

package/dist/infra/json-property.d.ts

@@ -0,0 +1,2 @@
+/** Replace one top-level JSON property while retaining unrelated bytes and style. */
+export declare function updateJsonProperty(existing: Buffer | null, key: string, value: unknown): Buffer;