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

package/dist/continuity/context.d.ts

@@ -2,12 +2,14 @@ import type { Diagnostic } from '../schemas/diagnostics.js';
 import type { Checkpoint } from '../schemas/continuity.js';
 import type { MachineConfig } from '../schemas/machine.js';
 import type { WorkspaceConfig } from '../schemas/workspace.js';
-import type { DiscoveredRepository } from '../workspace/types.js';
+import type { DiscoveredRepository, UnresolvedRepository } from '../workspace/types.js';
 export interface ContinuityWorkspace {
     readonly root: string;
     readonly config: WorkspaceConfig;
     readonly machine: MachineConfig | null;
     readonly repositories: readonly DiscoveredRepository[];
+    readonly unresolvedRepositories: readonly UnresolvedRepository[];
+    readonly discoveryTruncated: boolean;
     readonly diagnostics: readonly Diagnostic[];
 }
 export interface ContinuityWorkspaceResult {
@@ -20,5 +22,12 @@ export interface RepositorySnapshot {
     readonly patchBytes: Buffer | null;
 }
 export declare function loadContinuityWorkspace(root: string): Promise<ContinuityWorkspaceResult>;
-export declare function snapshotRepository(workspace: ContinuityWorkspace, repository: DiscoveredRepository, index: number): Promise<RepositorySnapshot>;
+/**
+ * Assigns stable identities that never shadow a configured logical ID. The
+ * normal fallback remains unchanged when collision-free; an automatic
+ * repository whose preferred fallback is reserved receives the first free
+ * `workspace-N` identity instead. Capture and resume must use the same list.
+ */
+export declare function repositoryIdentities(repositories: readonly DiscoveredRepository[], reservedIds?: readonly string[]): readonly string[];
+export declare function snapshotRepository(workspace: ContinuityWorkspace, repository: DiscoveredRepository, index: number, assignedId?: string): Promise<RepositorySnapshot>;
 export declare function continuityDiagnostic(message: string, source: string, hint: string): Diagnostic;

package/dist/continuity/context.js

@@ -38,6 +38,8 @@ export async function loadContinuityWorkspace(root) {
             config: config.value,
             machine: machine.value,
             repositories: repositories.repositories,
+            unresolvedRepositories: repositories.unresolved,
+            discoveryTruncated: repositories.truncated,
             diagnostics,
         },
         diagnostics,
@@ -46,15 +48,74 @@ export async function loadContinuityWorkspace(root) {
 function repoId(repository, index) {
     return (repository.id ?? (index === 0 ? 'workspace' : `workspace-${index + 1}`));
 }
+/**
+ * Assigns stable identities that never shadow a configured logical ID. The
+ * normal fallback remains unchanged when collision-free; an automatic
+ * repository whose preferred fallback is reserved receives the first free
+ * `workspace-N` identity instead. Capture and resume must use the same list.
+ */
+export function repositoryIdentities(repositories, reservedIds = []) {
+    const used = new Set([
+        ...reservedIds,
+        ...repositories.flatMap((repository) => repository.id === null ? [] : [repository.id]),
+    ]);
+    return repositories.map((repository, index) => {
+        if (repository.id !== null)
+            return repository.id;
+        const preferred = index === 0 ? 'workspace' : `workspace-${index + 1}`;
+        let candidate = preferred;
+        let suffix = 1;
+        while (used.has(candidate)) {
+            candidate = `workspace-${suffix}`;
+            suffix += 1;
+        }
+        used.add(candidate);
+        return candidate;
+    });
+}
 function repoScope(repository) {
     return repository.external ? 'external' : 'workspace';
 }
-export async function snapshotRepository(workspace, repository, index) {
+/**
+ * Parses `git status --porcelain=v1 -z` untracked paths without display
+ * unquoting. Rename/copy records carry a second NUL-delimited original path;
+ * that continuation is skipped so it can never be treated as a status row.
+ */
+function untrackedPathsFromNulStatus(statusText) {
+    if (statusText === '')
+        return [];
+    if (!statusText.endsWith('\0'))
+        return null;
+    const fields = statusText.split('\0');
+    fields.pop();
+    const paths = [];
+    for (let index = 0; index < fields.length; index += 1) {
+        const entry = fields[index];
+        if (entry === undefined || entry.length < 3 || entry[2] !== ' ') {
+            return null;
+        }
+        const code = entry.slice(0, 2);
+        const path = entry.slice(3);
+        if (path.length === 0)
+            return null;
+        if (code === '??')
+            paths.push(path);
+        if (code[0] === 'R' || code[0] === 'C') {
+            const continuation = fields[index + 1];
+            if (continuation === undefined || continuation.length === 0)
+                return null;
+            index += 1;
+        }
+    }
+    return paths;
+}
+export async function snapshotRepository(workspace, repository, index, assignedId) {
     const status = await runGit({
         cwd: repository.root,
         args: [
             'status',
             '--porcelain=v1',
+            '-z',
             '--untracked-files=all',
             '--',
             '.',
@@ -68,6 +129,8 @@ export async function snapshotRepository(workspace, repository, index) {
         cwd: repository.root,
         args: [
             'diff',
+            '--no-ext-diff',
+            '--no-textconv',
             '--binary',
             'HEAD',
             '--',
@@ -82,12 +145,15 @@ export async function snapshotRepository(workspace, repository, index) {
     const diffText = diff.ok ? diff.value.stdout : '';
     const dirty = status.ok ? statusText.trim().length > 0 : repository.git.dirty;
     let captureStatus = status.ok && diff.ok ? 'complete' : 'unknown';
+    const untracked = status.ok ? untrackedPathsFromNulStatus(statusText) : null;
+    if (status.ok && untracked === null)
+        captureStatus = 'partial';
     let patchBytes = null;
     if (dirty === true && status.ok && diff.ok) {
         const statusBytes = Buffer.from(statusText, 'utf8');
         const diffBytes = Buffer.from(diffText, 'utf8');
         const parts = [
-            Buffer.from(`PAPPRA-UNTRACKED/2\nP ${statusBytes.length} ${diffBytes.length}\n`, 'utf8'),
+            Buffer.from(`PAPPRA-UNTRACKED/3\nP ${statusBytes.length} ${diffBytes.length}\n`, 'utf8'),
             statusBytes,
             diffBytes,
         ];
@@ -95,11 +161,7 @@ export async function snapshotRepository(workspace, repository, index) {
         if (total > CONTINUITY_PAYLOAD_MAX_BYTES) {
             captureStatus = 'partial';
         }
-        const untracked = statusText
-            .split('\n')
-            .filter((line) => line.startsWith('?? '))
-            .map((line) => line.slice(3));
-        for (const path of untracked) {
+        for (const path of untracked ?? []) {
             if (total > CONTINUITY_PAYLOAD_MAX_BYTES)
                 break;
             const absolute = join(repository.root, path);
@@ -120,7 +182,7 @@ export async function snapshotRepository(workspace, repository, index) {
                     captureStatus = 'partial';
                     continue;
                 }
-                body = read.value.bytes;
+                body = Buffer.from(read.value.digest, 'utf8');
                 entryKind = 'F';
             }
             else if (observation.kind === 'symlink') {
@@ -129,17 +191,42 @@ export async function snapshotRepository(workspace, repository, index) {
                     captureStatus = 'partial';
                     continue;
                 }
-                body = Buffer.from(target, 'utf8');
+                body = Buffer.from(sha256Digest(target), 'utf8');
                 entryKind = 'L';
             }
+            else if (observation.kind === 'directory') {
+                // Git reports an embedded, non-submodule checkout as one untracked
+                // directory. Capture its own Git identity, never recurse into its bytes.
+                const head = await runGit({
+                    cwd: absolute,
+                    args: ['rev-parse', '--show-toplevel', 'HEAD'],
+                    timeoutMs: 5000,
+                    maxOutputBytes: 8192,
+                });
+                const nestedStatus = await runGit({
+                    cwd: absolute,
+                    args: ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+                    timeoutMs: 5000,
+                    maxOutputBytes: 2 * 1024 * 1024,
+                });
+                if (!head.ok ||
+                    !nestedStatus.ok ||
+                    head.value.stdout.split('\n')[0]?.replace(/\/$/, '') !==
+                        absolute.replace(/\/$/, '')) {
+                    captureStatus = 'partial';
+                    continue;
+                }
+                body = Buffer.from(sha256Digest(`${head.value.stdout}\n${nestedStatus.value.stdout}`), 'utf8');
+                entryKind = 'R';
+            }
             else {
                 captureStatus = 'partial';
                 continue;
             }
             const pathBytes = Buffer.from(path, 'utf8');
-            // F/L is part of the identity: a regular file body and a symlink target
-            // with identical bytes are still different source objects. The target
-            // text is read with readlink and never resolved or opened.
+            // Untracked bytes (including symlink targets) never enter the payload.
+            // Frame only their path, type and digest; F/L keeps distinct object kinds
+            // separate even when a file's bytes equal a symlink's target text.
             const header = Buffer.from(`${entryKind} ${pathBytes.length} ${body.length}\n`, 'utf8');
             if (total + header.length + pathBytes.length + body.length >
                 CONTINUITY_PAYLOAD_MAX_BYTES) {
@@ -155,7 +242,7 @@ export async function snapshotRepository(workspace, repository, index) {
     const checkoutId = workspace.machine?.checkoutId ?? sha256Digest(repository.root);
     return {
         record: {
-            repoId: repoId(repository, index),
+            repoId: assignedId ?? repoId(repository, index),
             checkoutId,
             root: repository.root,
             head: repository.git.head,

package/dist/continuity/handoff-bundle.d.ts

@@ -0,0 +1,296 @@
+import { z } from 'zod';
+import { type Outcome } from '../schemas/outcome.js';
+import { type ContinuityWriteOptions } from './paths.js';
+/**
+ * Linked private handoff bundles.
+ *
+ * A bundle is a separately versioned manifest that *links* one existing durable
+ * checkpoint to a collaboration task/attempt and the source native session, and
+ * carries the bounded additional handoff snapshot (claims, pending work, next
+ * action, recovery). It never duplicates checkpoint content, transfers
+ * authority, launches a replacement, archives a session or grants execution.
+ * Reading or verifying a bundle is purely advisory: it never returns execution
+ * permission or native control. The later rollover orchestrator (E3-B) must
+ * independently revalidate current authority, quiescence, ACK and transfer.
+ *
+ * Bundles are published immutably and exclusively under the existing
+ * workspace-private continuity task namespace
+ * (`.pappra/local/tasks/<continuityTaskId>/handoff-bundles/<bundleId>.json`),
+ * reusing the guarded continuity filesystem helpers. There is no latest
+ * pointer, alternate task record or mutable authority store.
+ */
+export declare const HANDOFF_BUNDLE_SCHEMA = "pappra/handoff-bundle/1";
+/** Subdirectory holding immutable handoff bundles inside a private task dir. */
+export declare const HANDOFF_BUNDLES_DIRNAME = "handoff-bundles";
+/**
+ * Upper bound for a serialized bundle. The manifest only links a checkpoint and
+ * carries a bounded snapshot, so it stays well under the shared continuity
+ * payload cap; an oversized file is rejected without inspecting its content.
+ */
+export declare const HANDOFF_BUNDLE_MAX_BYTES: number;
+/** The bound reference to one existing, schema-valid checkpoint. */
+export declare const handoffCheckpointReferenceSchema: z.ZodObject<{
+    checkpointId: z.ZodUUID;
+    taskId: z.ZodString;
+    workspaceId: z.ZodUUID;
+    ref: z.ZodString;
+    digest: z.ZodString;
+    authorSession: z.ZodNullable<z.ZodString>;
+    contextCompleteness: z.ZodEnum<{
+        complete: "complete";
+        partial: "partial";
+    }>;
+}, z.core.$strict>;
+export type HandoffCheckpointReference = z.infer<typeof handoffCheckpointReferenceSchema>;
+/** The collaboration task/attempt/input/owner-epoch this handoff belongs to. */
+export declare const handoffCollaborationBindingSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    attempt: z.ZodNumber;
+    ownerEpoch: z.ZodNumber;
+    subtaskId: z.ZodNullable<z.ZodString>;
+    inputRevision: z.ZodNullable<z.ZodString>;
+    association: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type HandoffCollaborationBinding = z.infer<typeof handoffCollaborationBindingSchema>;
+/** The source native session. Model/provider are advisory observations only. */
+export declare const handoffSourceNativeSessionSchema: z.ZodObject<{
+    harness: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        pi: "pi";
+        unknown: "unknown";
+    }>;
+    sessionId: z.ZodString;
+    agentId: z.ZodNullable<z.ZodString>;
+    paneId: z.ZodNullable<z.ZodString>;
+    surface: z.ZodNullable<z.ZodString>;
+    configurationId: z.ZodNullable<z.ZodString>;
+    modelObservation: z.ZodObject<{
+        model: z.ZodNullable<z.ZodString>;
+        provider: z.ZodNullable<z.ZodString>;
+        reasoning: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type HandoffSourceNativeSession = z.infer<typeof handoffSourceNativeSessionSchema>;
+/** The bounded additional snapshot carried alongside the linked checkpoint. */
+export declare const handoffSnapshotSchema: z.ZodObject<{
+    claims: z.ZodArray<z.ZodObject<{
+        claimId: z.ZodString;
+        resource: z.ZodString;
+        resourceEpoch: z.ZodNumber;
+        holder: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    claimsCompleteness: z.ZodEnum<{
+        complete: "complete";
+        partial: "partial";
+        unknown: "unknown";
+    }>;
+    pendingTools: z.ZodObject<{
+        items: z.ZodArray<z.ZodString>;
+        completeness: z.ZodEnum<{
+            complete: "complete";
+            partial: "partial";
+            unknown: "unknown";
+        }>;
+    }, z.core.$strict>;
+    pendingMessages: z.ZodObject<{
+        items: z.ZodArray<z.ZodString>;
+        completeness: z.ZodEnum<{
+            complete: "complete";
+            partial: "partial";
+            unknown: "unknown";
+        }>;
+    }, z.core.$strict>;
+    pendingApprovals: z.ZodObject<{
+        items: z.ZodArray<z.ZodString>;
+        completeness: z.ZodEnum<{
+            complete: "complete";
+            partial: "partial";
+            unknown: "unknown";
+        }>;
+    }, z.core.$strict>;
+    nextAction: z.ZodString;
+    recovery: z.ZodArray<z.ZodString>;
+    executionAuthority: z.ZodLiteral<"none">;
+    advisory: z.ZodLiteral<true>;
+}, z.core.$strict>;
+export type HandoffSnapshot = z.infer<typeof handoffSnapshotSchema>;
+/** The complete linked handoff bundle manifest. */
+export declare const handoffBundleSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"pappra/handoff-bundle/1">;
+    bundleId: z.ZodUUID;
+    createdAt: z.ZodISODateTime;
+    continuityTaskId: z.ZodString;
+    checkpoint: z.ZodObject<{
+        checkpointId: z.ZodUUID;
+        taskId: z.ZodString;
+        workspaceId: z.ZodUUID;
+        ref: z.ZodString;
+        digest: z.ZodString;
+        authorSession: z.ZodNullable<z.ZodString>;
+        contextCompleteness: z.ZodEnum<{
+            complete: "complete";
+            partial: "partial";
+        }>;
+    }, z.core.$strict>;
+    collaboration: z.ZodObject<{
+        taskId: z.ZodString;
+        attempt: z.ZodNumber;
+        ownerEpoch: z.ZodNumber;
+        subtaskId: z.ZodNullable<z.ZodString>;
+        inputRevision: z.ZodNullable<z.ZodString>;
+        association: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    sourceNativeSession: z.ZodObject<{
+        harness: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            pi: "pi";
+            unknown: "unknown";
+        }>;
+        sessionId: z.ZodString;
+        agentId: z.ZodNullable<z.ZodString>;
+        paneId: z.ZodNullable<z.ZodString>;
+        surface: z.ZodNullable<z.ZodString>;
+        configurationId: z.ZodNullable<z.ZodString>;
+        modelObservation: z.ZodObject<{
+            model: z.ZodNullable<z.ZodString>;
+            provider: z.ZodNullable<z.ZodString>;
+            reasoning: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    handoff: z.ZodObject<{
+        claims: z.ZodArray<z.ZodObject<{
+            claimId: z.ZodString;
+            resource: z.ZodString;
+            resourceEpoch: z.ZodNumber;
+            holder: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>;
+        claimsCompleteness: z.ZodEnum<{
+            complete: "complete";
+            partial: "partial";
+            unknown: "unknown";
+        }>;
+        pendingTools: z.ZodObject<{
+            items: z.ZodArray<z.ZodString>;
+            completeness: z.ZodEnum<{
+                complete: "complete";
+                partial: "partial";
+                unknown: "unknown";
+            }>;
+        }, z.core.$strict>;
+        pendingMessages: z.ZodObject<{
+            items: z.ZodArray<z.ZodString>;
+            completeness: z.ZodEnum<{
+                complete: "complete";
+                partial: "partial";
+                unknown: "unknown";
+            }>;
+        }, z.core.$strict>;
+        pendingApprovals: z.ZodObject<{
+            items: z.ZodArray<z.ZodString>;
+            completeness: z.ZodEnum<{
+                complete: "complete";
+                partial: "partial";
+                unknown: "unknown";
+            }>;
+        }, z.core.$strict>;
+        nextAction: z.ZodString;
+        recovery: z.ZodArray<z.ZodString>;
+        executionAuthority: z.ZodLiteral<"none">;
+        advisory: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+    limitations: z.ZodArray<z.ZodString>;
+    notes: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type HandoffBundle = z.infer<typeof handoffBundleSchema>;
+export interface SaveHandoffBundleInput {
+    readonly root: string;
+    readonly continuityTaskId: string;
+    readonly checkpoint: HandoffCheckpointReference;
+    readonly collaboration: HandoffCollaborationBinding;
+    readonly sourceNativeSession: HandoffSourceNativeSession;
+    readonly handoff: HandoffSnapshot;
+    readonly limitations?: readonly string[];
+    readonly notes?: string | null;
+    /** Optional explicit id (uuid); a fresh one is generated otherwise. */
+    readonly bundleId?: string;
+    /** Clock seam; defaults to the wall clock. */
+    readonly now?: () => Date;
+    /** Fault-injection seam forwarded to the exclusive publish. */
+    readonly writeOptions?: ContinuityWriteOptions;
+}
+export interface SaveHandoffBundleResult {
+    readonly bundleId: string;
+    readonly path: string;
+    readonly relativeRef: string;
+    readonly digest: string;
+    readonly bundle: HandoffBundle;
+}
+export interface ReadHandoffBundleResult {
+    readonly bundle: HandoffBundle;
+    readonly digest: string;
+    readonly path: string;
+}
+export interface HandoffArtifactCheck {
+    readonly path: string;
+    readonly status: 'unchanged' | 'changed' | 'missing' | 'unsafe' | 'unreadable';
+}
+export interface HandoffCompletenessSummary {
+    readonly claims: 'complete' | 'partial' | 'unknown';
+    readonly pendingTools: 'complete' | 'partial' | 'unknown';
+    readonly pendingMessages: 'complete' | 'partial' | 'unknown';
+    readonly pendingApprovals: 'complete' | 'partial' | 'unknown';
+}
+export interface VerifyHandoffBundleResult {
+    readonly bundleId: string;
+    readonly continuityTaskId: string;
+    readonly checkpointPresent: true;
+    readonly checkpointDigestMatches: true;
+    readonly checkpointSchemaValid: true;
+    readonly associationValid: true;
+    readonly workspaceIdentityMatches: true;
+    readonly checkpointContextCompleteness: 'complete' | 'partial';
+    readonly artifactChecks: readonly HandoffArtifactCheck[];
+    /**
+     * Truthful overall context assessment: 'complete' only when the checkpoint is
+     * itself complete and every referenced artifact is unchanged; 'unknown' when
+     * an artifact is unsafe or unreadable; otherwise 'incomplete'. A partial
+     * checkpoint or a missing/changed artifact is never reported as complete.
+     */
+    readonly contextIntegrity: 'complete' | 'incomplete' | 'unknown';
+    /** Verification never grants execution or native control. */
+    readonly executionAllowed: false;
+    readonly completeness: HandoffCompletenessSummary;
+}
+export declare function serializeHandoffBundle(bundle: HandoffBundle): Buffer;
+export declare function handoffBundleRelativeRef(bundleId: string): string;
+/** Build and validate a bundle manifest without touching the filesystem. */
+export declare function buildHandoffBundle(input: SaveHandoffBundleInput): Outcome<HandoffBundle>;
+/** Parse untrusted bytes into a validated bundle without leaking content. */
+export declare function parseHandoffBundle(raw: unknown): Outcome<HandoffBundle>;
+/**
+ * Validate the referenced checkpoint, then publish the bundle immutably and
+ * exclusively. A missing, changed or mismatched checkpoint fails before any
+ * write; an existing bundle id is never replaced.
+ */
+export declare function saveHandoffBundle(input: SaveHandoffBundleInput): Promise<Outcome<SaveHandoffBundleResult>>;
+/** Read and validate one stored bundle; private content is never leaked. */
+export declare function readHandoffBundle(options: {
+    readonly root: string;
+    readonly continuityTaskId: string;
+    readonly bundleId: string;
+}): Promise<Outcome<ReadHandoffBundleResult>>;
+/**
+ * Re-validate a bundle against its referenced checkpoint. Any missing, changed,
+ * mismatched or invalid checkpoint fails verification, so a defective bundle is
+ * never reported as complete. Success never implies execution authority.
+ */
+export declare function verifyHandoffBundle(options: {
+    readonly root: string;
+    readonly continuityTaskId: string;
+    readonly bundleId: string;
+} | {
+    readonly root: string;
+    readonly bundle: HandoffBundle;
+}): Promise<Outcome<VerifyHandoffBundleResult>>;