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

package/dist/knowledge/scan.js

@@ -1,5 +1,9 @@
-import { discoverWorkspace } from '../workspace/discover.js';
-import { KnowledgeService } from './index.js';
+import { discoverDocuments } from '../workspace/documents.js';
+import { createDiagnostic } from '../schemas/diagnostics.js';
+import { diagnosticCodes } from '../schemas/errors.js';
+import { loadKnowledgeContext } from './context.js';
+import { loadKnowledgeCatalogs } from './catalog.js';
+import { registerDocumentBatch } from './register-batch.js';
 export function classifyScannedDocumentKind(path) {
     const lower = path.toLowerCase();
     if (lower.endsWith('agents.md') || lower.endsWith('claude.md'))
@@ -14,25 +18,69 @@ export function classifyScannedDocumentKind(path) {
         return 'plan';
     return 'architecture';
 }
+function scanResult(root, mode, candidates, registered, skipped, diagnostics, nextActions, ok = !diagnostics.some((entry) => entry.severity === 'error')) {
+    return {
+        ok,
+        schema: 'pappra/docs-scan/1',
+        mode,
+        workspaceRoot: root,
+        candidates,
+        registered,
+        skipped,
+        nextActions,
+        diagnostics,
+    };
+}
 /**
  * Registers documents discovered under the configured knowledge sources.
  * Without apply this is read-only and reports the candidates.
  */
 export async function scanDiscoveredDocuments(root, options) {
-    const discovery = await discoverWorkspace(root);
-    const config = discovery.config;
-    if (config === null) {
-        return {
-            ok: false,
-            message: 'docs scan requires a valid .pappra/workspace.json; run pappra init first.',
-        };
+    const loaded = await loadKnowledgeContext(root);
+    const config = loaded.context?.config ?? null;
+    const diagnostics = [...loaded.diagnostics];
+    const discovery = loaded.context === null
+        ? { documents: [], diagnostics: [], truncated: false }
+        : await discoverDocuments({
+            root: loaded.context.root,
+            config,
+            configPath: loaded.context.configPath,
+            repositories: loaded.context.repositories,
+            options: {
+                scanDepth: 64,
+                maxDocuments: 10_000,
+                maxDirectories: 10_000,
+                maxEntriesPerDirectory: 10_000,
+                gitTimeoutMs: 5000,
+            },
+        });
+    diagnostics.push(...discovery.diagnostics);
+    if (discovery.truncated) {
+        diagnostics.push(createDiagnostic({
+            code: diagnosticCodes.discoveryLimitReached,
+            severity: 'warning',
+            message: 'Knowledge source discovery was truncated; scan coverage is incomplete.',
+            source: root,
+            pointer: null,
+            hint: 'Reduce the configured sources or their size, then rerun the scan for complete coverage.',
+        }));
+    }
+    if (config === null || loaded.context === null) {
+        return scanResult(root, options.apply ? 'apply' : 'plan', [], [], 0, diagnostics, [
+            'Run pappra init or repair .pappra/workspace.json before scanning knowledge sources.',
+        ], false);
     }
-    const service = new KnowledgeService(root);
-    const listed = await service.list({ includePrivate: true });
-    const registered = new Set(listed.records.flatMap((record) => record.location.kind === 'workspace' ? [record.location.path] : []));
+    const listed = await loadKnowledgeCatalogs(loaded.context);
+    diagnostics.push(...listed.diagnostics);
+    if (!listed.ok) {
+        return scanResult(root, options.apply ? 'apply' : 'plan', [], [], 0, diagnostics, [
+            'Repair the knowledge catalog diagnostics before scanning; no registration was attempted.',
+        ], false);
+    }
+    const registered = new Set([...listed.records.values()].flatMap((record) => record.location.kind === 'workspace' ? [record.location.path] : []));
     const sources = config.knowledge.sources;
     const visibility = config.knowledge.taskVisibility === 'shared' ? 'shareable' : 'private';
-    const candidates = [];
+    const discoveredCandidates = [];
     for (const document of discovery.documents ?? []) {
         const path = document.workspaceRelativePath;
         if (path === null)
@@ -42,50 +90,58 @@ export async function scanDiscoveredDocuments(root, options) {
         }
         if (registered.has(path))
             continue;
-        candidates.push({
+        discoveredCandidates.push({
             path,
             kind: classifyScannedDocumentKind(path),
             visibility,
         });
     }
-    const diagnostics = [...listed.diagnostics];
+    const candidates = discoveredCandidates.slice(0, 300);
+    if (discoveredCandidates.length > candidates.length)
+        diagnostics.push(createDiagnostic({
+            code: diagnosticCodes.discoveryLimitReached,
+            severity: 'warning',
+            message: 'This batch contains 300 new documents; rerun scan after applying to continue with the remaining documents.',
+            source: root,
+        }));
+    const incomplete = discovery.truncated ||
+        discoveredCandidates.length > candidates.length ||
+        diagnostics.some((entry) => entry.severity === 'error');
+    const privateCommand = visibility === 'private' ? 'pappra docs list --include-private' : null;
     if (!options.apply) {
-        return {
-            ok: true,
-            schema: 'pappra/docs-scan/1',
-            mode: 'plan',
-            workspaceRoot: root,
-            candidates,
-            registered: [],
-            skipped: candidates.length,
-            nextActions: [
-                'Rerun with apply: true to register these documents in the knowledge catalog.',
-            ],
-            diagnostics,
-        };
+        const nextActions = [];
+        if (candidates.length > 0) {
+            nextActions.push('Rerun with --apply to register these documents in the knowledge catalog.');
+        }
+        if (incomplete || discovery.truncated) {
+            nextActions.push('Correct the reported knowledge-source diagnostics, then rerun the scan for complete coverage.');
+        }
+        if (privateCommand !== null) {
+            nextActions.push(`After applying, review private documents with: ${privateCommand}.`);
+        }
+        return scanResult(root, 'plan', candidates, [], candidates.length, diagnostics, nextActions, !incomplete);
     }
     const registeredNow = [];
-    for (const candidate of candidates) {
-        const result = await service.register({
-            location: { kind: 'workspace', path: candidate.path },
-            kind: candidate.kind,
-            maturity: 'draft',
-            owner: 'human',
-            visibility: candidate.visibility,
-        });
+    const results = await registerDocumentBatch(loaded.context, candidates.map((candidate) => ({
+        location: { kind: 'workspace', path: candidate.path },
+        kind: candidate.kind,
+        maturity: 'draft',
+        owner: 'human',
+        visibility: candidate.visibility,
+    })));
+    for (const result of results) {
         diagnostics.push(...result.diagnostics);
         if (result.ok)
             registeredNow.push(result.record);
     }
-    return {
-        ok: diagnostics.every((entry) => entry.severity !== 'error'),
-        schema: 'pappra/docs-scan/1',
-        mode: 'apply',
-        workspaceRoot: root,
-        candidates,
-        registered: registeredNow,
-        skipped: candidates.length - registeredNow.length,
-        nextActions: [],
-        diagnostics,
-    };
+    const nextActions = [];
+    if (incomplete ||
+        discovery.truncated ||
+        registeredNow.length < candidates.length) {
+        nextActions.push('Coverage was incomplete or some registrations failed; correct the diagnostics and rerun the scan.');
+    }
+    if (privateCommand !== null) {
+        nextActions.push(`Review registered private documents with: ${privateCommand}.`);
+    }
+    return scanResult(root, 'apply', candidates, registeredNow, candidates.length - registeredNow.length, diagnostics, nextActions, !incomplete && !diagnostics.some((entry) => entry.severity === 'error'));
 }

package/dist/knowledge/service.d.ts

@@ -1,3 +1,4 @@
+import type { DocumentLocation } from '../schemas/document.js';
 import { type FreshnessReport } from './refs.js';
 import type { ApplyWriteInput, ApplyWriteResult, ArchiveDocumentResult, DeleteExplicitInput, DeleteExplicitResult, DocumentCheckResult, ListDocumentsOptions, ListDocumentsResult, PreviewDeleteInput, PreviewDeleteResult, ProposeWriteInput, ProposeWriteResult, ReadDocumentResult, RegisterDocumentInput, RegisterDocumentResult, ShareDocumentResult, SupersedeDocumentInput, SupersedeDocumentResult, KnowledgeServiceOptions } from './types.js';
 export declare class KnowledgeService {
@@ -5,6 +6,8 @@ export declare class KnowledgeService {
     readonly root: string;
     constructor(root: string, options?: KnowledgeServiceOptions);
     register(input: RegisterDocumentInput): Promise<RegisterDocumentResult>;
+    relocate(documentId: string, location: DocumentLocation): Promise<RegisterDocumentResult>;
+    forget(documentId: string, scope?: 'shared' | 'private'): Promise<RegisterDocumentResult>;
     read(documentId: string): Promise<ReadDocumentResult>;
     list(options?: ListDocumentsOptions): Promise<ListDocumentsResult>;
     check(options?: {

package/dist/knowledge/service.js

@@ -5,6 +5,7 @@ import { loadKnowledgeCatalogs } from './catalog.js';
 import { inspectFreshness, findRecord } from './refs.js';
 import { resolveKnowledgeLocation, readKnowledgeFile } from './paths.js';
 import { applyWrite, proposeWrite, registerDocument } from './write.js';
+import { relocateOrForgetDocument } from './relocate.js';
 import { archiveDocument, deleteExplicit, previewDelete, shareDocument, supersedeDocument, } from './lifecycle.js';
 const MAX_DOCUMENT_BYTES = 8 * 1024 * 1024;
 function outcomeDiagnostic(failure, source) {
@@ -77,8 +78,17 @@ function filteredDiagnostics(context, catalogs, includePrivate) {
     if (includePrivate)
         return diagnostics;
     const privatePrefix = `${context.root}/.pappra/local/knowledge`;
-    return diagnostics.filter((entry) => entry.source !== privatePrefix &&
+    const visible = diagnostics.filter((entry) => entry.source !== privatePrefix &&
         !entry.source.startsWith(`${privatePrefix}/`));
+    if (!catalogs.ok && !visible.some((entry) => entry.severity === 'error'))
+        visible.push(createDiagnostic({
+            code: diagnosticCodes.document_catalog_conflict,
+            severity: 'error',
+            message: 'A private knowledge catalog conflict blocks this operation.',
+            source: context.configPath,
+            hint: 'Run pappra docs list --include-private to inspect the conflict; use docs forget to remove an obsolete registration without deleting its file.',
+        }));
+    return visible;
 }
 export class KnowledgeService {
     root;
@@ -99,6 +109,28 @@ export class KnowledgeService {
         }
         return registerDocument(loaded.context, input);
     }
+    async relocate(documentId, location) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok)
+            return {
+                ok: false,
+                status: 'failed',
+                record: null,
+                diagnostics: loaded.diagnostics,
+            };
+        return relocateOrForgetDocument(loaded.context, documentId, location);
+    }
+    async forget(documentId, scope) {
+        const loaded = await getContext(this.root);
+        if (!loaded.ok)
+            return {
+                ok: false,
+                status: 'failed',
+                record: null,
+                diagnostics: loaded.diagnostics,
+            };
+        return relocateOrForgetDocument(loaded.context, documentId, null, scope);
+    }
     async read(documentId) {
         const loaded = await getContext(this.root);
         if (!loaded.ok) {

package/dist/knowledge/write.d.ts

@@ -1,7 +1,10 @@
-import { type DocumentWriteProposal } from '../schemas/document.js';
+import { type DocumentRecord, type DocumentWriteProposal } from '../schemas/document.js';
+import { type Outcome } from '../schemas/outcome.js';
 import type { KnowledgeContext } from './context.js';
+import { type ResolvedKnowledgeLocation } from './paths.js';
 import type { ApplyWriteInput, ApplyWriteResult, KnowledgeServiceOptions, ProposeWriteInput, ProposeWriteResult, RegisterDocumentInput, RegisterDocumentResult } from './types.js';
 export declare function defaultVisibility(context: KnowledgeContext): 'private' | 'shareable';
+export declare function validateAndBuildRecord(context: KnowledgeContext, input: RegisterDocumentInput, location: ResolvedKnowledgeLocation): Promise<Outcome<DocumentRecord>>;
 export declare function registerDocument(context: KnowledgeContext, input: RegisterDocumentInput): Promise<RegisterDocumentResult>;
 export declare function proposeWrite(context: KnowledgeContext, input: ProposeWriteInput): Promise<ProposeWriteResult>;
 export declare function applyWrite(input: ApplyWriteInput, root: string, options?: KnowledgeServiceOptions): Promise<ApplyWriteResult>;

package/dist/knowledge/write.js

@@ -99,7 +99,7 @@ function recordDiagnostics(record, source) {
             diagnostic(diagnosticCodes.document_record_invalid, `Document record is invalid: ${parsed.error.issues[0]?.message ?? 'unknown issue'}`, source, 'Fix the record metadata; no catalog bytes were written.'),
         ];
 }
-async function validateAndBuildRecord(context, input, location) {
+export async function validateAndBuildRecord(context, input, location) {
     const documentId = input.documentId ?? randomUUID();
     const visibility = input.visibility ?? defaultVisibility(context);
     const sources = input.sources ?? [];

package/dist/mcp/server.d.ts

@@ -2,10 +2,12 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 export declare const MCP_SERVER_NAME = "pappra";
 export interface PappraMcpServerOptions {
     readonly root: string;
+    /** Trusted server-launch policy, never accepted from tool arguments. */
+    readonly allowWorkspaceWrites?: boolean;
 }
 /**
  * Builds the stdio MCP server for one workspace. Tools are read-only here; write
- * operations are added separately and must stay behind apply/confirm gates.
+ * operations require a trusted launch policy; tool flags only select preview/apply.
  */
 export declare function createPappraMcpServer(options: PappraMcpServerOptions): McpServer;
-export declare function runMcpServer(root: string): Promise<void>;
+export declare function runMcpServer(root: string, allowWorkspaceWrites?: boolean): Promise<void>;

package/dist/mcp/server.js

@@ -1,6 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import path from 'node:path';
 import { discoverWorkspace } from '../workspace/discover.js';
 import { inspectMachineConfig, inspectWorkspaceConfig, } from '../workspace/config.js';
 import { inspectRuntimeStatePassive } from '../install/runtime.js';
@@ -10,11 +11,18 @@ import { CodeIntelligenceService } from '../code/index.js';
 import { HOST_SUPPORT } from '../hosts/integration/support.js';
 import { getPackageInfo } from '../package-info.js';
 import { scanDiscoveredDocuments } from '../knowledge/scan.js';
-import { installRuntime } from '../install/runtime.js';
-import { bindAndRecordRuntime, ensureDefaultRuntime } from '../app/init.js';
-import { prepareFromObjective } from '../app/collab-from.js';
-import { FixtureController, PiRpcController, finishStarted, startPrepared, submitResultReport, } from '../app/collaboration.js';
+import { prepareCollaboration } from '../app/collaboration.js';
+import { collaborationGoalSchema } from '../schemas/collaboration.js';
+import { canonicalizeTarget } from '../collab/canonical.js';
+import { isPathInside } from '../schemas/paths.js';
 export const MCP_SERVER_NAME = 'pappra';
+function cliRequired(command) {
+    return {
+        ok: false,
+        status: 'cli_required',
+        message: `${command} requires an authorized CLI invocation. A tool-supplied apply flag is not user approval.`,
+    };
+}
 function toolResult(value, isError = false) {
     return {
         content: [
@@ -39,10 +47,11 @@ async function errorResult(action) {
 }
 /**
  * Builds the stdio MCP server for one workspace. Tools are read-only here; write
- * operations are added separately and must stay behind apply/confirm gates.
+ * operations require a trusted launch policy; tool flags only select preview/apply.
  */
 export function createPappraMcpServer(options) {
     const root = options.root;
+    const allowWorkspaceWrites = options.allowWorkspaceWrites === true;
     const server = new McpServer({
         name: MCP_SERVER_NAME,
         version: getPackageInfo().version,
@@ -222,13 +231,15 @@ export function createPappraMcpServer(options) {
             provider: result.result?.provider ?? null,
             coverage: result.result?.coverage ?? null,
             items: result.result?.items ?? [],
+            truncated: result.result?.truncated ?? false,
+            reasons: result.result?.reasons ?? [],
             health: result.health,
             diagnostics: result.diagnostics,
         };
     }));
     server.registerTool('checkpoint', {
         title: 'Write a task checkpoint',
-        description: 'Writes an advisory checkpoint for handoff. Requires apply: true; a checkpoint is context, not permission to execute.',
+        description: 'Writes an advisory checkpoint only when trusted server startup enables workspace writes. apply selects persistence and never grants authorization.',
         inputSchema: {
             task: z.string().min(1).max(256),
             objective: z.string().min(1).max(4000),
@@ -245,13 +256,15 @@ export function createPappraMcpServer(options) {
             nativeSession: z.string().min(1).max(256).optional(),
             apply: z.boolean(),
         },
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: !allowWorkspaceWrites },
     }, async (args) => errorResult(async () => {
+        if (!allowWorkspaceWrites)
+            return cliRequired('pappra checkpoint');
         if (args.apply !== true) {
             return {
                 ok: false,
-                status: 'confirmation_required',
-                message: 'checkpoint writes state; call again with apply: true after the user agrees.',
+                status: 'preview',
+                message: 'Preview only. The trusted host has enabled workspace writes; apply selects persistence, not authorization.',
             };
         }
         const nativeRefs = args.nativeSession === undefined
@@ -308,10 +321,12 @@ export function createPappraMcpServer(options) {
     }));
     server.registerTool('docs_scan', {
         title: 'Scan knowledge sources',
-        description: 'Registers documents discovered under the configured knowledge sources. Without apply it only reports candidates.',
+        description: 'Previews discovered knowledge documents. Applying requires trusted server startup workspace-write policy; tool flags do not grant it.',
         inputSchema: { apply: z.boolean().optional() },
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: !allowWorkspaceWrites },
     }, async (args) => errorResult(async () => {
+        if (args.apply === true && !allowWorkspaceWrites)
+            return cliRequired('pappra docs scan --apply');
         const result = await scanDiscoveredDocuments(root, {
             apply: args.apply === true,
         });
@@ -319,19 +334,21 @@ export function createPappraMcpServer(options) {
     }));
     server.registerTool('code_prepare', {
         title: 'Prepare a repository code index',
-        description: 'Registers the selected repository index and optionally runs the external engine. Without apply it only reports the plan.',
+        description: 'Previews repository index preparation. Engine execution requires an authorized CLI command.',
         inputSchema: {
             repo: z.string().min(1).max(128),
             apply: z.boolean().optional(),
             rebuild: z.boolean().optional(),
         },
-        annotations: { readOnlyHint: false },
+        annotations: { readOnlyHint: true },
     }, async (args) => errorResult(async () => {
+        if (args.apply === true)
+            return cliRequired('pappra code prepare --apply');
         const service = new CodeIntelligenceService(root);
         const result = await service.prepare({
             root,
             repositoryId: args.repo,
-            apply: args.apply === true,
+            apply: false,
             rebuild: args.rebuild === true,
         });
         return {
@@ -345,147 +362,81 @@ export function createPappraMcpServer(options) {
     }));
     server.registerTool('runtime_install', {
         title: 'Install the durable runtime',
-        description: 'Installs and binds a durable runtime copy. Requires apply: true; the default source is the running package.',
-        inputSchema: {
-            from: z.enum(['self', 'tarball', 'version']).optional(),
-            version: z.string().min(1).max(128).optional(),
-            tarball: z.string().min(1).max(4096).optional(),
+        description: 'Reports CLI guidance for runtime installation; MCP never installs or executes package code. Only from:self is accepted.',
+        inputSchema: z.strictObject({
+            from: z.literal('self').optional(),
             apply: z.boolean(),
-        },
-        annotations: { readOnlyHint: false },
+        }),
+        annotations: { readOnlyHint: true },
     }, async (args) => errorResult(async () => {
         const from = args.from ?? 'self';
-        const version = args.version ?? getPackageInfo().version;
-        if (args.apply !== true) {
-            return {
-                ok: false,
-                status: 'confirmation_required',
-                message: 'runtime_install writes a durable copy and machine.json; call again with apply: true.',
-                version,
-                from,
-            };
-        }
-        if (from === 'self') {
-            const result = await ensureDefaultRuntime(root, version);
-            return {
-                ok: result.ok && result.completion,
-                completion: result.completion,
-                runtime: result.runtime,
-                diagnostics: result.diagnostics,
-            };
-        }
-        const tarball = args.tarball;
-        if (from === 'tarball' && tarball === undefined) {
-            return {
-                ok: false,
-                message: 'from: tarball requires the tarball path.',
-            };
-        }
-        const installed = await installRuntime({
-            version,
-            source: from === 'tarball' && tarball !== undefined
-                ? { kind: 'tarball', path: tarball }
-                : { kind: 'version' },
-            packageName: getPackageInfo().name,
-        });
-        const bound = await bindAndRecordRuntime(root, installed);
+        const version = getPackageInfo().version;
         return {
-            ok: bound.ok && bound.completion,
-            completion: bound.completion,
-            runtime: installed,
-            diagnostics: bound.diagnostics,
+            ...cliRequired('pappra runtime install --from self --apply'),
+            version,
+            from,
         };
     }));
     server.registerTool('collab_prepare', {
         title: 'Prepare a bounded collaboration',
-        description: 'Builds a collaboration goal and a declared capability card from an objective and explicit resources, then claims them. A declared card cannot authorize a work launch.',
-        inputSchema: {
+        description: 'Prepares a bounded collaboration from an explicit shared pappra/collaboration-goal/1 document plus a shared domain root, then claims its resources. Identities, configuration, cwd, roles and capabilities are never inferred. No capability card is generated: derive and preflight actual runtime evidence separately before a user-authorized CLI launch. The legacy flat objective form is unsupported.',
+        inputSchema: z.strictObject({
             domainRoot: z.string().min(1).max(4096),
-            objective: z.string().min(1).max(4000),
-            task: z.string().min(1).max(128),
-            acceptance: z.array(z.string().min(1).max(1000)).min(1).max(32),
-            resources: z
-                .array(z.object({
-                path: z.string().min(1).max(4096),
-                access: z.enum(['read', 'write']),
-            }))
-                .min(1)
-                .max(32),
-            coordinatorSession: z.string().min(1).max(256),
-            assigneeSession: z.string().min(1).max(256),
-            harness: z.enum(['pi', 'codex', 'claude']).optional(),
-            subtaskId: z.string().min(1).max(128).optional(),
-            attempt: z.number().int().min(1).max(1000).optional(),
-            phase: z
-                .enum(['discovery', 'implementation', 'review', 'handoff', 'fix'])
-                .optional(),
-            prompt: z.string().min(1).max(20000).optional(),
-        },
-        annotations: { readOnlyHint: false },
+            goal: collaborationGoalSchema,
+        }),
+        annotations: { readOnlyHint: !allowWorkspaceWrites },
     }, async (args) => errorResult(async () => {
-        const result = await prepareFromObjective({
+        if (!allowWorkspaceWrites)
+            return cliRequired('pappra collab prepare');
+        const workspace = canonicalizeTarget(path.resolve(root)).path;
+        const privateDomain = path.join(workspace, '.pappra', 'local', 'collaboration');
+        const domain = canonicalizeTarget(path.resolve(args.domainRoot)).path;
+        if (!isPathInside(privateDomain, domain) ||
+            !isPathInside(workspace, canonicalizeTarget(args.goal.assignee.cwd).path) ||
+            args.goal.resources.some((resource) => !isPathInside(workspace, canonicalizeTarget(resource.path).path)))
+            return {
+                ok: false,
+                status: 'scope_refused',
+                message: 'MCP preparation is limited to a private workspace collaboration domain and workspace-local resources; use the authorized CLI for other scopes.',
+            };
+        const result = await prepareCollaboration(args.goal, {
             domainRoot: args.domainRoot,
-            objective: args.objective,
-            taskId: args.task,
-            acceptance: args.acceptance,
-            resources: args.resources,
-            coordinatorSession: args.coordinatorSession,
-            assigneeSession: args.assigneeSession,
-            ...(args.harness === undefined ? {} : { harness: args.harness }),
-            ...(args.subtaskId === undefined
-                ? {}
-                : { subtaskId: args.subtaskId }),
-            ...(args.attempt === undefined ? {} : { attempt: args.attempt }),
-            ...(args.phase === undefined ? {} : { phase: args.phase }),
-            ...(args.prompt === undefined ? {} : { prompt: args.prompt }),
         });
-        return result;
+        if (!result.ok) {
+            return {
+                ok: false,
+                status: result.status,
+                code: result.code,
+                message: result.message,
+                nextAction: result.nextAction,
+                diagnostics: result.diagnostics,
+            };
+        }
+        return {
+            ok: true,
+            prepared: result.value.prepared,
+            goal: result.value.goal,
+            notes: [
+                'No capability card is generated and no observation timestamp is manufactured. Supply actual capability evidence: derive a runtime card with pappra collab capabilities derive from the receiving session, check it with pappra collab preflight, then ask the user to launch with pappra collab run in the CLI.',
+                'The removed cardPath/card outputs were declared-only evidence and never authorized a launch.',
+            ],
+        };
     }));
     server.registerTool('collab_start', {
         title: 'Start one admitted collaboration launch',
-        description: 'Performs one admitted launch with an explicit controller and returns the report. Requires confirm: true and a runtime capability card; a declared card is refused by admission.',
+        description: 'Returns CLI guidance without launching. The user must launch through the CLI; an agent-supplied confirm flag is not user approval.',
         inputSchema: {
             prepared: z.string().min(1).max(4096),
             capabilities: z.string().min(1).max(4096),
             controller: z.enum(['fixture', 'pi-rpc']),
             confirm: z.boolean(),
         },
-        annotations: { readOnlyHint: false, destructiveHint: true },
-    }, async (args) => errorResult(async () => {
-        if (args.confirm !== true) {
-            return {
-                ok: false,
-                status: 'confirmation_required',
-                message: 'collab_start launches a process; the user must confirm before calling it with confirm: true.',
-            };
-        }
-        const controller = args.controller === 'fixture'
-            ? new FixtureController()
-            : new PiRpcController();
-        const started = await startPrepared(args.prepared, {
-            capabilitiesFile: args.capabilities,
-            controller,
-            controllerId: controller.id,
-        });
-        if (!started.ok)
-            return started;
-        try {
-            const finished = await finishStarted(started.value);
-            if (!finished.ok) {
-                return finished;
-            }
-            const report = submitResultReport(started.value, finished.value);
-            return {
-                ok: report.ok,
-                status: finished.value.status,
-                report,
-                finish: finished.value,
-            };
-        }
-        finally {
-            await started.value.session.dispose?.().catch(() => undefined);
-        }
-    }));
+        annotations: { readOnlyHint: true, destructiveHint: false },
+    }, async () => errorResult(async () => ({
+        ok: false,
+        status: 'cli_required',
+        message: 'MCP cannot authorize process launches. Ask the user to run pappra collab run --prepared <file> --capabilities <file> --controller <controller> --confirm in the CLI.',
+    })));
     server.registerTool('runtime_status', {
         title: 'Runtime status',
         description: 'Reports the workspace runtime binding and passive runtime state.',
@@ -511,8 +462,8 @@ export function createPappraMcpServer(options) {
     }));
     return server;
 }
-export async function runMcpServer(root) {
-    const server = createPappraMcpServer({ root });
+export async function runMcpServer(root, allowWorkspaceWrites = false) {
+    const server = createPappraMcpServer({ root, allowWorkspaceWrites });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/schemas/collaboration-state-validation.d.ts

@@ -0,0 +1,6 @@
+import type { TaskRecord, LockHolder, Message, Notification } from './collaboration-state.js';
+export { object, text, errorCode, parseJson } from '../infra/validation.js';
+export declare function isTaskRecord(value: unknown): value is TaskRecord;
+export declare function isLockHolder(value: unknown): value is LockHolder;
+export declare function isMessage(value: unknown): value is Message;
+export declare function isNotification(value: unknown): value is Notification;