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

package/dist/code/identity.d.ts

@@ -1,3 +1,4 @@
+import { type GitObservationScope } from '../infra/git.js';
 import { type Outcome } from '../schemas/outcome.js';
 import { type CodeIdentity } from '../schemas/code.js';
 export interface ComputeCodeIdentityInput {
@@ -8,6 +9,12 @@ export interface ComputeCodeIdentityInput {
     readonly configStatus?: 'default' | 'observed' | 'unknown';
     readonly excludedRoots?: readonly string[];
     readonly signal?: AbortSignal;
+    /**
+     * One operation's Git probe scope. When supplied, the repository probe is
+     * shared with workspace discovery instead of being spawned a second time for
+     * the same checkout. Working-tree diffs are never taken from the scope.
+     */
+    readonly observations?: GitObservationScope;
 }
 export declare function computeCodeIdentity(input: ComputeCodeIdentityInput): Promise<Outcome<CodeIdentity>>;
 export declare function codeIdentityDigest(identity: CodeIdentity): string;

package/dist/code/identity.js

@@ -1,7 +1,6 @@
 import { readlink } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
-import { inspectGitRepository } from '../infra/git.js';
-import { runGit } from '../infra/git.js';
+import { inspectGitRepository, runGit, } from '../infra/git.js';
 import { observePath, readFileBounded, sha256Digest } from '../infra/fs.js';
 import { diagnosticCodes } from '../schemas/errors.js';
 import { failed, succeeded } from '../schemas/outcome.js';
@@ -34,6 +33,8 @@ async function observeWorkingTree(root, excludedRoots, signal) {
     }
     const cached = await readDiff([
         'diff',
+        '--no-ext-diff',
+        '--no-textconv',
         '--binary',
         '--cached',
         '--',
@@ -42,6 +43,8 @@ async function observeWorkingTree(root, excludedRoots, signal) {
     ]);
     const unstaged = await readDiff([
         'diff',
+        '--no-ext-diff',
+        '--no-textconv',
         '--binary',
         '--',
         '.',
@@ -172,7 +175,8 @@ async function observeWorkingTree(root, excludedRoots, signal) {
     };
 }
 export async function computeCodeIdentity(input) {
-    const observed = await inspectGitRepository(input.root, {
+    const inspect = input.observations?.repository ?? inspectGitRepository;
+    const observed = await inspect(input.root, {
         timeoutMs: GIT_TIMEOUT_MS,
         ...(input.signal === undefined ? {} : { signal: input.signal }),
     });

package/dist/code/registration.js

@@ -1,4 +1,5 @@
 import { mkdir, open, rename, rm } from 'node:fs/promises';
+import { ensurePrivateState } from '../infra/private-state.js';
 import { randomUUID } from 'node:crypto';
 import { join, relative, sep } from 'node:path';
 import { observePath, readFileBounded, resolveRealpath, sha256Digest, } from '../infra/fs.js';
@@ -62,6 +63,9 @@ export async function acquireCodePrepareLock(root, excludedRoots = []) {
     const boundary = await ensureCodeMutationBoundary(root, path, excludedRoots);
     if (!boundary.ok)
         return boundary;
+    const prepared = await ensurePrivateState(root);
+    if (!prepared.ok)
+        return prepared;
     try {
         await mkdir(directory, { recursive: true, mode: 0o700 });
         const content = Buffer.from(`${JSON.stringify({ pid: process.pid, token: randomUUID(), acquiredAt: new Date().toISOString() })}\n`);
@@ -249,6 +253,9 @@ export async function writeCodeRegistration(root, registration, excludedRoots =
     const boundary = await ensureCodeMutationBoundary(root, path, excludedRoots);
     if (!boundary.ok)
         return boundary;
+    const prepared = await ensurePrivateState(root);
+    if (!prepared.ok)
+        return prepared;
     const temporary = `${path}.tmp-${randomUUID()}`;
     const content = Buffer.from(`${JSON.stringify(registration, null, 2)}\n`);
     let owned = null;

package/dist/code/service.d.ts

@@ -1,3 +1,4 @@
+import { type GitObservationScope } from '../infra/git.js';
 import type { Diagnostic } from '../schemas/diagnostics.js';
 import { type CodeIdentity, type CodeIndexHealth, type CodeIndexRegistration, type CodePreparePlan, type CodePrepareResult, type CodeQueryKind, type CodeQueryLimits, type CodeQueryResult } from '../schemas/code.js';
 import { codeIdentityDigest } from './identity.js';
@@ -13,6 +14,14 @@ export interface CodeStatusInput {
     readonly root: string;
     readonly repositoryId: string;
     readonly signal?: AbortSignal;
+    /**
+     * One operation's Git probe scope. Callers that run several service methods
+     * for a single command may pass one scope so workspace discovery and every
+     * identity probe share immutable repository observations. Omitted callers get
+     * a scope that lives only for this call: no result is ever cached across
+     * operations.
+     */
+    readonly observations?: GitObservationScope;
 }
 export interface CodePrepareInput extends CodeStatusInput {
     readonly apply: boolean;

package/dist/code/service.js

@@ -1,3 +1,4 @@
+import { createGitObservationScope, } from '../infra/git.js';
 import { sha256Digest } from '../infra/fs.js';
 import { createDiagnostic } from '../schemas/diagnostics.js';
 import { diagnosticCodes } from '../schemas/errors.js';
@@ -43,7 +44,7 @@ function fallbackHealth(state, reason, engineVersion = 'unknown') {
         observedAt: new Date().toISOString(),
     });
 }
-async function loadWorkspace(root) {
+async function loadWorkspace(root, observations) {
     const config = await inspectWorkspaceConfig(root);
     const diagnostics = [...config.diagnostics];
     if (config.value === null) {
@@ -57,6 +58,7 @@ async function loadWorkspace(root) {
         machine: machine.value,
         configPath: config.path,
         options: discoveryOptions,
+        observations,
     });
     diagnostics.push(...repositories.diagnostics);
     return {
@@ -99,7 +101,9 @@ function overlayRegistration(raw, registration, registrationFailure, identity) {
     return raw;
 }
 async function observeCode(input) {
-    const view = await loadWorkspace(input.root);
+    const observations = input.observations ??
+        createGitObservationScope({ workingTreeState: false });
+    const view = await loadWorkspace(input.root, observations);
     const diagnostics = [...view.diagnostics];
     const repository = selectRepository(view, input.repositoryId);
     if (repository === null) {
@@ -156,6 +160,7 @@ async function observeCode(input) {
         configStatus,
         excludedRoots,
         ...(input.signal === undefined ? {} : { signal: input.signal }),
+        observations,
     });
     if (!identity.ok) {
         diagnostics.push(outcomeDiagnostic(identity, repository.root));
@@ -297,7 +302,14 @@ export class CodeIntelligenceService {
         return { observed, plan };
     }
     async prepare(input) {
-        const { observed, plan } = await this.planPrepare(input);
+        // Reuse probes within planning; refresh after external preparation because
+        // another writer or the engine may change HEAD while this call is awaiting.
+        const observations = input.observations ??
+            createGitObservationScope({ workingTreeState: false });
+        const { observed, plan } = await this.planPrepare({
+            ...input,
+            observations,
+        });
         if (!input.apply) {
             return {
                 schema: 'pappra/code-prepare-result/1',
@@ -448,6 +460,7 @@ export class CodeIntelligenceService {
                 configStatus: afterConfig.value.status,
                 excludedRoots: observed.excludedRoots,
                 ...(input.signal === undefined ? {} : { signal: input.signal }),
+                observations: createGitObservationScope({ workingTreeState: false }),
             });
             if (!afterIdentity.ok) {
                 return {

package/dist/code/text.js

@@ -8,6 +8,8 @@ import { failed, succeeded } from '../schemas/outcome.js';
 import { boundCodeItems } from './budget.js';
 const MAX_FILE_BYTES = 256 * 1024;
 const MAX_FILE_COUNT = 5000;
+// Scanning and emitted JSON have independent budgets.
+const MAX_SCAN_BYTES = 64 * 1024 * 1024;
 const EXCLUDES = [
     ':(exclude).codegraph',
     ':(exclude).pappra/local',
@@ -100,11 +102,18 @@ export async function runTextQuery(request, mode, signal) {
     const items = [];
     const evidence = [];
     const reasons = [];
-    let bytes = 0;
+    let scannedBytes = 0;
     let truncated = list.value.stdout.split('\0').filter(Boolean).length > paths.length;
+    if (truncated)
+        reasons.push('file_limit');
     for (const path of paths) {
-        if (items.length >= request.limits.maxResults ||
-            bytes >= request.limits.maxBytes) {
+        if (signal?.aborted) {
+            reasons.push('cancelled');
+            truncated = true;
+            break;
+        }
+        if (items.length >= request.limits.maxResults) {
+            reasons.push('result_limit');
             truncated = true;
             break;
         }
@@ -135,9 +144,9 @@ export async function runTextQuery(request, mode, signal) {
             reasons.push('binary_skipped');
             continue;
         }
-        bytes += read.value.size;
-        if (bytes > request.limits.maxBytes) {
-            bytes = request.limits.maxBytes;
+        scannedBytes += read.value.size;
+        if (scannedBytes > MAX_SCAN_BYTES) {
+            reasons.push('scan_budget');
             truncated = true;
             break;
         }
@@ -159,14 +168,17 @@ export async function runTextQuery(request, mode, signal) {
                 });
                 offset = lower.indexOf(needle, offset + Math.max(1, needle.length));
             }
-            if (offset !== -1)
+            if (offset !== -1) {
                 truncated = true;
+                reasons.push('result_limit');
+            }
         }
         else {
             const matches = structureMatches(text, request.query);
             for (const match of matches) {
                 if (items.length >= request.limits.maxResults) {
                     truncated = true;
+                    reasons.push('result_limit');
                     break;
                 }
                 items.push({ ...match, path });

package/dist/collab/admission.d.ts

@@ -38,6 +38,8 @@ export declare const TOOL_PROFILES: {
         reviewer: string;
     };
 };
+/** Returns a runner only for an own supported harness key with a string value. */
+export declare function runnerForHarness(harness: unknown): string | null;
 /**
  * Pre-dispatch admission. A launcher that started a native process without checking the
  * assignment, the capability snapshot, the collaboration record and the actual resource
@@ -50,6 +52,10 @@ export declare const TOOL_PROFILES: {
  *              anything it has not observed
  */
 export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot, cwd, sessionId, harness, profile, launchKind, discovery, resumeSelector, now, maxAgeMinutes, }: AdmissionOptions): {
+    owner_epoch?: never;
+    detail?: never;
+    state?: never;
+    state_revision?: never;
     ok: false;
     reason: string;
     checks: Record<string, unknown>[];
@@ -58,10 +64,6 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     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;
@@ -73,18 +75,18 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    expected?: never;
+    owner_epoch?: never;
+    detail?: 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;
@@ -96,18 +98,41 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    expected?: never;
+    actual?: never;
+    owner_epoch?: 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;
+} | {
     expected?: never;
     actual?: never;
-    state_revision?: never;
     owner_epoch?: never;
+    detail?: never;
+    state?: never;
+    state_revision?: never;
+    ok: false;
+    reason: string;
+    checks: Record<string, unknown>[];
+    required_skills?: never;
+    required_tools?: never;
+    preflight?: never;
     attempt_state?: never;
     resources?: never;
     mode?: never;
@@ -119,6 +144,10 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    owner_epoch?: never;
+    detail?: never;
+    state?: never;
+    state_revision?: never;
     ok: false;
     reason: string;
     checks: Record<string, unknown>[];
@@ -127,10 +156,6 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     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;
@@ -142,6 +167,10 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    owner_epoch?: never;
+    detail?: never;
+    state?: never;
+    state_revision?: never;
     ok: false;
     reason: string;
     checks: Record<string, unknown>[];
@@ -155,10 +184,6 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     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;
@@ -170,6 +195,9 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    owner_epoch?: never;
+    state?: never;
+    state_revision?: never;
     ok: false;
     reason: string;
     checks: Record<string, unknown>[];
@@ -179,9 +207,6 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     required_skills?: never;
     required_tools?: never;
     preflight?: never;
-    state?: never;
-    state_revision?: never;
-    owner_epoch?: never;
     attempt_state?: never;
     resources?: never;
     mode?: never;
@@ -193,18 +218,18 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    expected?: never;
+    actual?: never;
+    owner_epoch?: never;
+    detail?: 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;
@@ -216,19 +241,25 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    expected?: never;
+    actual?: never;
+    owner_epoch?: never;
+    detail?: never;
+    state?: never;
+    state_revision?: never;
     required_skills?: never;
     required_tools?: never;
     ok: false;
     reason: string;
     checks: Record<string, unknown>[];
     preflight: {
+        attempt?: never;
         status: string;
         errors: string[];
         blockers: never[];
         warnings: never[];
         task_id?: never;
         assignment_id?: never;
-        attempt?: never;
         checked_at?: never;
         limits?: never;
     } | {
@@ -242,12 +273,6 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
         warnings: import("./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;
@@ -259,6 +284,11 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    expected?: never;
+    actual?: never;
+    owner_epoch?: never;
+    detail?: never;
+    state_revision?: never;
     required_skills?: never;
     required_tools?: never;
     preflight?: never;
@@ -266,11 +296,6 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     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;
@@ -282,18 +307,18 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     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;
@@ -305,19 +330,19 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    expected?: never;
+    actual?: never;
+    owner_epoch?: 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;
@@ -328,19 +353,19 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     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;
-    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;
@@ -351,19 +376,19 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    expected?: never;
+    actual?: never;
+    owner_epoch?: never;
+    detail?: 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;
@@ -374,14 +399,14 @@ export declare function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot
     assignment_digest?: never;
     input_revision?: never;
 } | {
+    reason?: never;
+    expected?: never;
+    actual?: never;
+    detail?: never;
+    state?: never;
     required_skills?: never;
     required_tools?: never;
     preflight?: never;
-    state?: never;
-    detail?: never;
-    expected?: never;
-    actual?: never;
-    reason?: never;
     ok: true;
     checks: Record<string, unknown>[];
     state_revision: number;

package/dist/collab/admission.js

@@ -35,11 +35,19 @@ export const TOOL_PROFILES = {
     },
 };
 /** The runner an assignment must name for a given harness; the launcher will not substitute one. */
-const RUNNER_FOR_HARNESS = {
+const RUNNER_FOR_HARNESS = Object.freeze({
     pi: 'pi-cli',
     codex: 'codex-exec',
     claude: 'claude-cli',
-};
+});
+/** Returns a runner only for an own supported harness key with a string value. */
+export function runnerForHarness(harness) {
+    if (typeof harness !== 'string' ||
+        !Object.hasOwn(RUNNER_FOR_HARNESS, harness))
+        return null;
+    const runner = RUNNER_FOR_HARNESS[harness];
+    return typeof runner === 'string' && runner.length > 0 ? runner : null;
+}
 /** Whether the assignment can name the native session before the process starts. Pi and Claude
  *  accept an explicit session id; `codex exec` chooses the thread id itself. */
 const PRE_BOUND_IDENTITY = {
@@ -83,10 +91,17 @@ export function admitLaunch({ assignmentFile, capabilitiesFile, taskRoot, cwd, s
             actual: harness,
         };
     }
-    const expectedRunner = RUNNER_FOR_HARNESS[harness ?? assignment.assignee.harness];
-    if (assignment.runner?.name &&
-        expectedRunner &&
-        assignment.runner.name !== expectedRunner) {
+    const requestedHarness = harness ?? assignment.assignee.harness;
+    const expectedRunner = runnerForHarness(requestedHarness);
+    if (expectedRunner === null) {
+        return {
+            ok: false,
+            reason: 'unsupported_harness',
+            checks,
+            actual: requestedHarness,
+        };
+    }
+    if (assignment.runner.name !== expectedRunner) {
         return {
             ok: false,
             reason: 'runner_contract_mismatch',

package/dist/collab/canonical.d.ts

@@ -3,7 +3,7 @@ export declare const RESOURCE_KINDS: readonly string[];
 /**
  * Resolve the longest existing ancestor with realpath and append the not-yet-existing
  * suffix. Symlink aliases therefore collapse to one key. The suffix keeps the caller's
- * spelling, so a differently-cased non-existent target is not normalised.
+ * spelling for I/O; comparison keys account for the containing filesystem's case behavior.
  */
 export declare function canonicalizeTarget(input: string): {
     path: string;