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

package/dist/cli/commands/mcp.d.ts

@@ -4,5 +4,6 @@ export interface McpCommandOptions {
     readonly cwd: string;
     readonly root: string | null;
     readonly json: boolean;
+    readonly allowWorkspaceWrites?: boolean;
 }
 export declare function runMcpCommand(options: McpCommandOptions, output: CliOutput): Promise<number>;

package/dist/cli/commands/mcp.js

@@ -1,13 +1,19 @@
 import { runMcpServer } from '../../mcp/server.js';
-export const mcpUsage = 'pappra mcp [--root <dir>] [--json]\n\n' +
-    'Starts the Pappra MCP server on stdio for the selected workspace. The server exposes\n' +
-    'read-only tools (workspace_status, resume, docs_list, docs_check, code_status,\n' +
-    'code_query, runtime_status). stdout carries MCP JSON-RPC; use --help outside a host.';
+export const mcpUsage = 'pappra mcp [--root <dir>] [--allow-workspace-writes] [--json]\n\n' +
+    'Starts the Pappra MCP server on stdio for the selected workspace. stdout carries\n' +
+    'MCP JSON-RPC; use --help outside a host.\n\n' +
+    'Read-only tools: workspace_status, resume, docs_list, docs_check, code_status,\n' +
+    'code_query, runtime_status.\n' +
+    'The default server cannot mutate state, install code or launch agent/index work. A trusted host may\n' +
+    'enable checkpoint/docs_scan and workspace-private collab_prepare at server startup\n' +
+    'with --allow-workspace-writes; apply only selects preview versus execution.\n' +
+    'runtime_install and code_prepare execution always require the authorized CLI.\n' +
+    'collab_start returns cli_required and never launches, even with confirm: true.';
 export async function runMcpCommand(options, output) {
     const root = options.root ?? options.cwd;
     if (options.json) {
         output.stderr('pappra mcp: --json is not used; the server speaks MCP JSON-RPC on stdout.\n');
     }
-    await runMcpServer(root);
+    await runMcpServer(root, options.allowWorkspaceWrites === true);
     return 0;
 }

package/dist/cli/commands/repair.d.ts

@@ -0,0 +1,12 @@
+import type { CliOutput } from '../output.js';
+export declare const repairUsage: string;
+export declare function runRepairCommand(options: {
+    readonly root: string;
+    readonly runtimeVersion?: string;
+    readonly installId?: string;
+    readonly apply: boolean;
+    readonly json: boolean;
+    readonly quarantineUnownedLocks?: boolean;
+    readonly resetLocal?: boolean;
+    readonly allWritersStopped?: boolean;
+}, output: CliOutput): Promise<number>;

package/dist/cli/commands/repair.js

@@ -0,0 +1,41 @@
+import { repairInstall } from '../../install/repair.js';
+export const repairUsage = 'pappra repair [--root <workspace>] [--runtime-version <v>] [--install-id <uuid>] [--apply] [--quarantine-unowned-locks] [--reset-local --all-writers-stopped] [--json]\n' +
+    'Preview incomplete install journals, or explicitly recover them with --apply.\n' +
+    'Also inspect/recover provably dead knowledge and checkpoint writer locks.\n' +
+    'Runtime recovery targets the machine data directory for the selected version.\n' +
+    'Live/unknown lock owners and modified or unproven files are preserved.\n' +
+    '--quarantine-unowned-locks is an explicit operator assertion that ALL affected writers are stopped;\n' +
+    'with --apply it moves unknown lock evidence into private quarantine without claiming owner death.\n' +
+    'Never use this flag against a live or paused writer. Live verified owners are always refused.\n' +
+    '--reset-local explicitly archives all old private local state without migration; --apply also requires\n' +
+    '--all-writers-stopped. Existing bytes remain under ignored .pappra/local-archive; fresh init is separate.\n';
+export async function runRepairCommand(options, output) {
+    const result = await repairInstall(options);
+    if (options.json)
+        output.stdout(`${JSON.stringify({ command: 'repair', ...result })}\n`);
+    else {
+        output.stdout(`State repair ${result.mode}: ${result.entries.length} incomplete install journal(s).\n`);
+        for (const entry of result.entries)
+            output.stdout(`  ${entry.installId} ${entry.operation}: ${entry.status}\n`);
+        for (const file of result.locks)
+            output.stdout(`Writer lock: ${file}\n`);
+        for (const state of result.lockStates)
+            output.stdout(`Lock owner ${state.state}: ${state.file}\n`);
+        for (const file of result.preserved)
+            output.stdout(`Preserved unproven file: ${file}\n`);
+        for (const file of result.quarantined)
+            output.stdout(`Quarantined unowned lock evidence: ${file}\n`);
+        if (result.reset !== null)
+            output.stdout(`Local reset ${result.reset.status}; archive: ${result.reset.archive ?? '(none)'}\n`);
+        for (const file of result.repaired)
+            output.stdout(`Recovered: ${file}\n`);
+        for (const error of result.errors)
+            output.stderr(`pappra repair: ${error}\n`);
+        if (result.ok &&
+            result.mode === 'plan' &&
+            (result.entries.length > 0 || result.locks.length > 0)) {
+            output.stdout('Rerun with --apply to recover the listed install state.\n');
+        }
+    }
+    return result.ok ? 0 : 1;
+}

package/dist/cli/commands/runtime.d.ts

@@ -2,7 +2,7 @@ import type { CliOutput } from '../output.js';
 export declare const runtimeUsage: string;
 export interface RuntimeCommandOptions {
     readonly cwd: string;
-    readonly action: 'install' | 'status' | 'verify' | 'remove' | null;
+    readonly action: 'install' | 'status' | 'verify' | 'remove' | 'gc' | null;
     readonly json: boolean;
     readonly from: 'self' | 'tarball' | 'registry' | null;
     readonly tarball: string | null;

package/dist/cli/commands/runtime.js

@@ -1,18 +1,23 @@
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { inspectRuntimeReferences, runtimeBindingMatches, } from '../../install/references.js';
 import { getPackageInfo, getPackageRoot } from '../../package-info.js';
 import { inspectRuntimeState, inspectRuntimeStatePassive, installRuntime, removeRuntime, resolveUserDataDir, runtimePaths, } from '../../install/runtime.js';
 import { updateMachineRuntime } from '../../install/apply.js';
 import { inspectMachineConfig } from '../../workspace/config.js';
 import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
-export const runtimeUsage = 'pappra runtime <install|status|verify|remove> [options] [--json]\n' +
+export const runtimeUsage = 'pappra runtime <install|status|verify|remove|gc> [options] [--json]\n' +
     '  install [--from self|tarball|registry] [--tarball <file>] [--runtime-version <v>]\n' +
     '          [--apply] [--bind]\n' +
     '  status\n' +
     '  verify [--runtime-version <v>]\n' +
-    '  remove [--runtime-version <v>] --apply [--force]\n\n' +
+    '  remove [--runtime-version <v>] [--apply] [--force]\n' +
+    '  gc [--runtime-version <v>] [--apply] [--force]\n\n' +
     'Install keeps a durable copy of the package outside the checkout. --from self packs the\n' +
     'package that is currently executing, which is what makes an npx/dlx bootstrap survive\n' +
-    'cache eviction. Writes require --apply; --bind records the copy in machine.json.\n';
+    'cache eviction. Writes require --apply; --bind records the copy in machine.json.\n' +
+    'Only explicitly registered workspace roots are inspected; no home scan is performed.\n' +
+    '--force accepts unknown/unregistered coverage, but never bypasses a verified workspace binding.\n';
 async function inspectBinding(cwd) {
     const resolution = await resolveWorkspaceRoot({ startPath: cwd });
     if (resolution.root === null)
@@ -197,53 +202,147 @@ async function runVerify(options, output, binding) {
 async function runRemove(options, output, binding) {
     const version = options.version ?? binding?.runtime?.version ?? null;
     if (version === null) {
-        output.stderr('pappra runtime remove: --version is required.\n');
+        const message = 'runtime remove requires --runtime-version.';
+        if (options.json)
+            output.stdout(`${JSON.stringify({ ok: false, code: 'invalid_arguments', message })}\n`);
+        else
+            output.stderr(`pappra: ${message}\n`);
         return 2;
     }
+    const dataDir = resolveUserDataDir();
+    const boundHere = await runtimeBindingMatches(dataDir, version, binding?.runtime);
+    const references = await inspectRuntimeReferences(dataDir, version);
     if (!options.apply) {
-        output.stderr('pappra runtime remove: rerun with --apply to remove it.\n');
-        return 2;
-    }
-    const boundHere = binding?.runtime?.version === version;
-    if (boundHere && !options.force) {
-        const message = 'machine.json still binds this runtime; pass --force to remove it anyway.';
-        if (options.json) {
-            output.stdout(`${JSON.stringify({
-                ok: false,
-                command: 'runtime',
-                action: 'remove',
-                version,
-                message,
-            })}\n`);
-        }
-        else {
-            output.stderr(`pappra runtime remove: ${message}\n`);
-        }
-        return 1;
-    }
-    const removed = await removeRuntime({
-        version,
-        dataDir: resolveUserDataDir(),
-        // The current workspace was already checked above; callers that need to
-        // protect other checkouts pass --force only after checking them.
-        activeReferences: [],
-    });
-    if (options.json) {
-        output.stdout(`${JSON.stringify({
-            ok: removed.ok,
+        const plan = {
+            ok: true,
             command: 'runtime',
             action: 'remove',
+            mode: 'plan',
             version,
-            removed,
-            machineBindingRetained: boundHere,
-        })}\n`);
+            runtimeRoot: runtimePaths(version, dataDir).runtimeRoot,
+            references,
+            boundHere,
+            eligibleUnderForcePolicy: !boundHere && references.active.length === 0 && options.force,
+            nextAction: 'Use --apply after review. --force accepts unknown coverage only; active bindings are always retained.',
+        };
+        output.stdout(options.json
+            ? `${JSON.stringify(plan)}\n`
+            : `Runtime removal plan ${version}: ${boundHere || references.active.length > 0 ? 'referenced; retained' : 'global coverage unknown; explicit --force required'}.\n`);
+        return 0;
     }
+    const removed = await removeRuntime({
+        version,
+        dataDir,
+        ...(boundHere && binding !== null
+            ? { activeReferences: [binding.root] }
+            : {}),
+        forceUnknownReferences: options.force,
+    });
+    if (options.json)
+        output.stdout(`${JSON.stringify({ ok: removed.ok, command: 'runtime', action: 'remove', version, removed, references, machineBindingRetained: boundHere })}\n`);
     else {
         output.stdout(`Runtime ${version}: ${removed.status}\n`);
         printDiagnostics(output, removed.diagnostics);
     }
     return removed.ok ? 0 : 1;
 }
+async function runGc(options, output, binding) {
+    if (options.version !== null &&
+        !/^[0-9A-Za-z][0-9A-Za-z0-9._+-]*$/.test(options.version)) {
+        const message = 'runtime gc requires an exact --runtime-version without path separators.';
+        output.stdout(options.json
+            ? `${JSON.stringify({ ok: false, code: 'invalid_arguments', message })}\n`
+            : `${message}\n`);
+        return 2;
+    }
+    if (options.from !== null || options.tarball !== null || options.bind) {
+        const message = 'runtime gc accepts only --runtime-version, --apply, --force and --json.';
+        if (options.json)
+            output.stdout(`${JSON.stringify({ ok: false, code: 'invalid_arguments', message })}\n`);
+        else
+            output.stderr(`${message}\n`);
+        return 2;
+    }
+    const dataDir = resolveUserDataDir();
+    let versions;
+    try {
+        const entries = await readdir(join(dataDir, 'runtimes'), {
+            withFileTypes: true,
+        });
+        versions = entries
+            .filter((entry) => entry.isDirectory() &&
+            /^[0-9A-Za-z][0-9A-Za-z0-9._+-]*$/.test(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            const report = {
+                ok: false,
+                command: 'runtime',
+                action: 'gc',
+                mode: options.apply ? 'apply' : 'plan',
+                message: 'Runtime directory is unreadable; nothing was removed.',
+            };
+            output.stdout(options.json ? `${JSON.stringify(report)}\n` : `${report.message}\n`);
+            return 1;
+        }
+        versions = [];
+    }
+    if (options.version !== null)
+        versions = versions.filter((version) => version === options.version);
+    if (versions.length > 256) {
+        const message = 'Runtime GC version limit exceeded; select one --runtime-version.';
+        output.stdout(options.json
+            ? `${JSON.stringify({ ok: false, command: 'runtime', action: 'gc', message })}\n`
+            : `${message}\n`);
+        return 1;
+    }
+    const entries = [];
+    let ok = true;
+    for (const version of versions) {
+        const references = await inspectRuntimeReferences(dataDir, version);
+        const boundHere = await runtimeBindingMatches(dataDir, version, binding?.runtime);
+        if (boundHere || references.active.length > 0) {
+            entries.push({
+                version,
+                status: 'retained',
+                reason: 'verified-workspace-reference',
+                references,
+            });
+            continue;
+        }
+        if (!options.apply) {
+            entries.push({
+                version,
+                status: options.force ? 'candidate' : 'unknown',
+                references,
+            });
+            continue;
+        }
+        const removed = await removeRuntime({
+            version,
+            dataDir,
+            forceUnknownReferences: options.force,
+        });
+        entries.push({ version, ...removed, references });
+        ok &&= removed.ok;
+    }
+    const report = {
+        ok,
+        command: 'runtime',
+        action: 'gc',
+        mode: options.apply ? 'apply' : 'plan',
+        dataDir,
+        coverage: 'registered-workspaces-only',
+        unregisteredCoverage: 'unknown',
+        entries,
+    };
+    output.stdout(options.json
+        ? `${JSON.stringify(report)}\n`
+        : `Runtime GC ${report.mode}: ${entries.map((entry) => `${String(entry['version'])}=${String(entry['status'])}`).join(', ') || 'no versions'}\n`);
+    return ok ? 0 : 1;
+}
 export async function runRuntimeCommand(options, output) {
     if (options.action === null) {
         output.stderr(`${runtimeUsage}`);
@@ -259,5 +358,7 @@ export async function runRuntimeCommand(options, output) {
             return runVerify(options, output, binding);
         case 'remove':
             return runRemove(options, output, binding);
+        case 'gc':
+            return runGc(options, output, binding);
     }
 }

package/dist/cli/commands/session.d.ts

@@ -0,0 +1,7 @@
+import type { CliOutput } from '../output.js';
+export declare const sessionUsage: string;
+export declare function runSessionCommand(options: {
+    readonly action: string;
+    readonly config: string | null;
+    readonly json: boolean;
+}, output: CliOutput): Promise<number>;

package/dist/cli/commands/session.js

@@ -0,0 +1,82 @@
+import { readManagedPiRequest, planManagedPiSession, } from '../../app/managed-pi.js';
+import { startManagedPiSession, requestManagedPiControl, } from '../../hosts/pi/managed-session.js';
+import { watchManagedPiReadiness } from '../../app/managed-pi-readiness.js';
+import { runManagedPiSdkRuntime } from '../../app/managed-pi-sdk-runtime.js';
+export const sessionUsage = 'pappra session <plan|start|status|fence|stop> --config <abs managed-pi.json> [--json]\n\n' +
+    'plan validates a launch request without effects. start requires a visible terminal,\n' +
+    'launches native Pi TUI with OpenRouter and preserves daily configuration.\n' +
+    'Ingress is journaled; exact-child exit is separate from transfer-safe quiescence.\n' +
+    'status/fence/stop address only the private endpoint created by that launch.\n' +
+    'No existing interactive session is adopted. start does not accept --json.';
+export async function runSessionCommand(options, output) {
+    try {
+        if (options.config === null)
+            throw new Error('--config is required.');
+        const request = readManagedPiRequest(options.config);
+        if (options.action === 'status' ||
+            options.action === 'fence' ||
+            options.action === 'stop') {
+            const result = await requestManagedPiControl(`${request.journalPath}.control.json`, options.action === 'status' ? 'snapshot' : options.action);
+            output.stdout(`${JSON.stringify(result, null, options.json ? undefined : 2)}\n`);
+            if (options.action === 'stop') {
+                const exit = result.exit;
+                return result.ok === true &&
+                    typeof exit === 'object' &&
+                    exit !== null &&
+                    'status' in exit &&
+                    (exit.status === 'exited' || exit.status === 'runtime_disposed')
+                    ? 0
+                    : 1;
+            }
+            return result.ok === true ? 0 : 1;
+        }
+        if (options.action === 'plan') {
+            output.stdout(`${JSON.stringify(planManagedPiSession(request), null, options.json ? undefined : 2)}\n`);
+            return 0;
+        }
+        if (options.action !== 'start')
+            throw new Error('session accepts plan, start, status, fence or stop.');
+        if (options.json)
+            throw new Error('Native TUI start does not accept --json.');
+        if (request.runtime === 'sdk') {
+            if (!process.stdin.isTTY || !process.stdout.isTTY)
+                throw new Error('SDK mode requires a visible native terminal.');
+            return await runManagedPiSdkRuntime(request);
+        }
+        const { schema: _schema, readiness, ...launch } = request;
+        const session = await startManagedPiSession(launch);
+        let publisher = null;
+        try {
+            if (readiness)
+                publisher = watchManagedPiReadiness(readiness, {
+                    sessionId: session.identity.sessionId,
+                    cwd: launch.cwd,
+                    metadataFile: `${launch.journalPath}.pi-events.jsonl`,
+                });
+        }
+        catch {
+            // Readiness failure does not terminate an otherwise owned, visible session.
+            output.stderr('Readiness watcher could not start; task preflight remains required.\n');
+        }
+        const exit = await session.waitForExit().finally(() => publisher?.close());
+        if (exit.status === 'exited')
+            session.close();
+        if (exit.status !== 'exited') {
+            output.stderr('Managed Pi child exit is unknown; inspect retained controller evidence.\n');
+            return 1;
+        }
+        return exit.exitCode === 0 ? 0 : 1;
+    }
+    catch (error) {
+        const result = {
+            ok: false,
+            code: 'managed_pi_session_refused',
+            message: error instanceof Error ? error.message : 'Managed Pi session failed.',
+        };
+        if (options.json)
+            output.stdout(`${JSON.stringify(result)}\n`);
+        else
+            output.stderr(`${result.message}\n`);
+        return 2;
+    }
+}

package/dist/cli/commands/task.js

@@ -1,8 +1,10 @@
 import { resolveWorkspaceRoot } from '../../workspace/resolve.js';
 import { pinTask, readAutoResume, readTaskPin, setAutoResume, unpinTask, } from '../../app/task-pin.js';
+import { loadWorkspaceConfig } from '../../workspace/config.js';
 export const taskUsage = 'pappra task <pin|unpin|show> [taskId] [--auto-resume] [--json]\n\n' +
     'pin records the current task in .pappra/local/current-task. Hooks inject a resume\n' +
-    'packet only when the workspace continuity.autoResume switch is on (--auto-resume).';
+    "packet only when this checkout's private auto-resume preference is on (--auto-resume).\n" +
+    'The preference lives in .pappra/local/task-preferences.json and never rewrites workspace.json.';
 function failure(output, options, message) {
     if (options.json) {
         output.stdout(`${JSON.stringify({ ok: false, code: 'task_invalid', message })}\n`);
@@ -15,8 +17,17 @@ function failure(output, options, message) {
 export async function runTaskCommand(options, output) {
     const resolution = await resolveWorkspaceRoot({ startPath: options.cwd });
     const root = resolution.root;
-    if (root === null) {
-        return failure(output, options, 'task requires a registered Pappra workspace above the current directory.');
+    const mutating = options.action === 'pin' || options.action === 'unpin';
+    if (root === null || (mutating && resolution.state !== 'registered')) {
+        return failure(output, options, `task requires a registered Pappra workspace above the current directory (found: ${resolution.state}).`);
+    }
+    if (mutating) {
+        // An incomplete or unsafe registration can still report a root; mutations
+        // also require configuration this version can read.
+        const config = await loadWorkspaceConfig(root);
+        if (!config.ok) {
+            return failure(output, options, `workspace configuration is not usable: ${config.message}`);
+        }
     }
     if (options.action === 'pin') {
         if (options.taskId === null) {
@@ -29,7 +40,7 @@ export async function runTaskCommand(options, output) {
         if (options.autoResume) {
             const switched = await setAutoResume(root, true);
             if ('message' in switched) {
-                return failure(output, options, switched.message);
+                return failure(output, options, `task ${pinned.taskId} is pinned, but autoResume was not enabled: ${switched.message}`);
             }
         }
         const report = {
@@ -44,7 +55,10 @@ export async function runTaskCommand(options, output) {
         return 0;
     }
     if (options.action === 'unpin') {
-        await unpinTask(root);
+        const unpinned = await unpinTask(root);
+        if ('message' in unpinned) {
+            return failure(output, options, unpinned.message);
+        }
         const report = { ok: true, action: 'unpin' };
         output.stdout(options.json
             ? `${JSON.stringify(report)}\n`