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

package/dist/app/collaboration.js

@@ -1,11 +1,13 @@
+import { object as isRecord } from '../infra/validation.js';
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { collaborationCommandSchema, collaborationGoalSchema, collaborationPreparedSchema, } from '../schemas/collaboration.js';
-import { admitLaunch, reserveLaunch, settleLaunch, } from '../collab/admission.js';
+import { admitLaunch, reserveLaunch, settleLaunch, runnerForHarness, } from '../collab/admission.js';
 import { buildMessage, sha256File } from '../collab/envelope.js';
 import { findAttempt } from '../collab/lifecycle.js';
 import { submitMessage } from '../collab/messages.js';
+import { readMessageFromTaskRoot } from './collab-messages.js';
 import { claimResources, releaseClaim } from '../collab/resources.js';
 import { initTask, nowIso, readRecord, taskRootFor } from '../collab/store.js';
 import { observePath, resolveRealpath } from '../infra/fs.js';
@@ -303,9 +305,6 @@ function publishCurrentResult(namespace, file, bytes) {
         };
     }
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
-}
 function assistantRecord(record) {
     if (!isRecord(record))
         return null;
@@ -556,8 +555,13 @@ export async function prepareCollaboration(input, options) {
     if (!path.isAbsolute(options.domainRoot)) {
         return failure('invalid', 'domain_root_required', 'Domain root must be absolute.');
     }
-    if (!fs.existsSync(goal.assignee.cwd)) {
-        return failure('needs_input', 'cwd_unavailable', 'Assignee cwd does not exist.');
+    const runnerName = runnerForHarness(goal.assignee.harness);
+    if (runnerName === null) {
+        return failure('invalid', 'assignee_harness_unsupported', `Assignee harness ${goal.assignee.harness} has no supported runner; the supported harnesses are pi, codex and claude.`);
+    }
+    const assigneeCwd = await observePath(goal.assignee.cwd).catch(() => null);
+    if (assigneeCwd?.kind !== 'directory') {
+        return failure('needs_input', 'cwd_unavailable', 'Assignee cwd is not a real existing directory.');
     }
     let taskRoot;
     let domainRoot;
@@ -626,6 +630,7 @@ export async function prepareCollaboration(input, options) {
             for (const claimId of claimIds) {
                 releaseClaim(taskRoot, {
                     claimId,
+                    holder: goal.assignee,
                     reason: 'prepare resource claim failed',
                 });
             }
@@ -637,6 +642,7 @@ export async function prepareCollaboration(input, options) {
             for (const claimId of claimIds) {
                 releaseClaim(taskRoot, {
                     claimId,
+                    holder: goal.assignee,
                     reason: 'prepare resource epoch missing',
                 });
             }
@@ -655,6 +661,7 @@ export async function prepareCollaboration(input, options) {
             for (const claimId of claimIds) {
                 releaseClaim(taskRoot, {
                     claimId,
+                    holder: goal.assignee,
                     reason: 'prepare failed before assignment',
                 });
             }
@@ -667,6 +674,7 @@ export async function prepareCollaboration(input, options) {
             for (const claimId of claimIds) {
                 releaseClaim(taskRoot, {
                     claimId,
+                    holder: goal.assignee,
                     reason: 'prepare failed before assignment',
                 });
             }
@@ -682,7 +690,7 @@ export async function prepareCollaboration(input, options) {
         attempt: goal.attempt,
         objective: goal.objective,
         acceptance: goal.acceptance,
-        roles: ['implementer'],
+        roles: goal.roles,
         coordinator: {
             agent_id: goal.coordinator.agent_id,
             session_id: goal.coordinator.session_id,
@@ -707,7 +715,7 @@ export async function prepareCollaboration(input, options) {
             resource_epoch: resourceEpochs[item.path],
         })),
         runner: {
-            name: 'pi-cli',
+            name: runnerName,
             mode: 'native',
             omitted_capabilities: [],
         },
@@ -723,6 +731,7 @@ export async function prepareCollaboration(input, options) {
             for (const claimId of claimIds) {
                 releaseClaim(taskRoot, {
                     claimId,
+                    holder: goal.assignee,
                     reason: 'prepare failed before assignment',
                 });
             }
@@ -762,6 +771,7 @@ export async function prepareCollaboration(input, options) {
         for (const claimId of claimIds) {
             releaseClaim(taskRoot, {
                 claimId,
+                holder: goal.assignee,
                 reason: 'assignment registration failed',
             });
         }
@@ -808,6 +818,10 @@ export async function admitPrepared(preparedFile, capabilitiesFile, options = {}
     if (!bundle.ok)
         return bundle;
     const { prepared, goal, assignment } = bundle.value;
+    if (typeof options.controllerHarness === 'string' &&
+        assignment.assignee.harness !== options.controllerHarness) {
+        return failure('invalid', 'controller_harness_mismatch', `This controller launches ${options.controllerHarness} assignments only; the prepared assignment names ${assignment.assignee.harness}.`, 'Prepare the goal for the controller-supported harness or choose the matching controller.');
+    }
     const card = (() => {
         try {
             return JSON.parse(fs.readFileSync(capabilitiesFile, 'utf8'));
@@ -846,10 +860,13 @@ export async function admitPrepared(preparedFile, capabilitiesFile, options = {}
         value: { prepared, goal, assignment, admission, token },
     };
 }
+/** Real controllers are bound to one harness; fixtures are not and stay explicit fixtures. */
+const CONTROLLER_HARNESS = { 'pi-rpc': 'pi' };
 export async function startPrepared(preparedFile, options) {
     const clock = options.clock ?? Date.now();
     const admitted = await admitPrepared(preparedFile, options.capabilitiesFile, {
         clock,
+        controllerHarness: CONTROLLER_HARNESS[options.controller.id] ?? null,
     });
     if (!admitted.ok)
         return admitted;
@@ -862,7 +879,7 @@ export async function startPrepared(preparedFile, options) {
         return captured.failure;
     let token = admitted.value.token;
     let reservationId = null;
-    if (options.controllerId === 'fixture') {
+    if (options.controller.id === 'fixture') {
         const reservation = reserveLaunch(prepared.task_root, {
             expectRevision: prepared.state_revision,
             clock,
@@ -1197,8 +1214,68 @@ export async function driveRun(started, commands, emit, { clock = Date.now() } =
                     });
                     continue;
                 }
+                const intentContentDigest = intent.content_digest;
+                if (intentContentDigest === null) {
+                    send('cancel', command.request_id, 'cancel-intent-unverified', 'The registered CANCEL has no content digest; native cancellation was not called.', {
+                        intent: true,
+                        native: {
+                            called: false,
+                            reason: 'cancel_intent_digest_missing',
+                        },
+                    });
+                    continue;
+                }
+                const registered = await readMessageFromTaskRoot(started.prepared.task_root, intent.message_id);
+                const registeredMessage = registered.ok
+                    ? registered.value.message
+                    : null;
+                const entry = registered.ok ? registered.value.entry : null;
+                const sameIdentity = (actual, expected) => actual !== null &&
+                    actual !== undefined &&
+                    actual.agent_id === expected.agent_id &&
+                    actual.session_id === expected.session_id &&
+                    (actual.harness ?? null) === (expected.harness ?? null);
+                const intentApplied = registeredMessage !== null &&
+                    entry !== null &&
+                    intentContentDigest !== null &&
+                    registeredMessage.message_id === intent.message_id &&
+                    registeredMessage.type === 'CANCEL' &&
+                    registeredMessage.task_id === started.prepared.task_id &&
+                    registeredMessage.subtask_id === started.prepared.subtask_id &&
+                    registeredMessage.attempt === started.prepared.attempt &&
+                    registeredMessage.owner_epoch ===
+                        started.goal.coordinator.owner_epoch &&
+                    registeredMessage.content_digest === intentContentDigest &&
+                    sameIdentity(registeredMessage.from, started.goal.coordinator) &&
+                    sameIdentity(registeredMessage.to, started.assignment.assignee) &&
+                    entry.message_id === intent.message_id &&
+                    entry.type === 'CANCEL' &&
+                    entry.state === 'applied' &&
+                    entry.subtask_id === started.prepared.subtask_id &&
+                    entry.attempt === started.prepared.attempt &&
+                    entry.owner_epoch === started.goal.coordinator.owner_epoch &&
+                    entry.content_digest === intentContentDigest &&
+                    sameIdentity(entry.from, started.goal.coordinator) &&
+                    sameIdentity(entry.to, started.assignment.assignee);
+                if (!registered.ok || !intentApplied) {
+                    send('cancel', command.request_id, 'cancel-intent-unverified', 'The registered CANCEL could not be verified as the applied intent for this run; native cancellation was not called.', {
+                        intent: true,
+                        native: {
+                            called: false,
+                            reason: registered.ok
+                                ? 'cancel_intent_not_applied'
+                                : registered.code,
+                        },
+                    });
+                    continue;
+                }
+                const cancellationIntent = {
+                    messageId: intent.message_id,
+                    contentDigest: intentContentDigest,
+                    fileDigest: registered.value.digest,
+                };
                 try {
-                    const cancel = await started.session.cancel();
+                    const cancel = await started.session.cancel(cancellationIntent);
                     send('cancel', command.request_id, 'cancel-requested', null, {
                         intent: true,
                         native: cancel,
@@ -1295,7 +1372,11 @@ export class FixtureController {
     }
 }
 export class PiRpcController {
+    options;
     id = 'pi-rpc';
+    constructor(options = {}) {
+        this.options = options;
+    }
     async start(token, request) {
         if (!validateLaunchToken(token, {
             taskRoot: request.taskRoot,
@@ -1312,6 +1393,7 @@ export class PiRpcController {
             };
         }
         const started = await startOwnedPiRpc({
+            ...this.options,
             taskRoot: request.taskRoot,
             cwd: request.assignment.assignee.cwd,
             assignmentFile: request.prepared.assignment_path,
@@ -1416,7 +1498,7 @@ export class PiRpcController {
                         };
                     }
                 },
-                cancel: async () => {
+                cancel: async (intent) => {
                     const namespaceProblem = liveNamespaceProblem();
                     if (namespaceProblem !== null) {
                         return {
@@ -1428,7 +1510,7 @@ export class PiRpcController {
                             },
                         };
                     }
-                    const cancel = await started.session.cancel();
+                    const cancel = await started.session.cancel(intent === undefined ? undefined : { intent });
                     const entry = cancel !== null && typeof cancel === 'object'
                         ? cancel
                         : {};
@@ -1641,3 +1723,10 @@ export function inspectPreparedHistory(preparedFile) {
         },
     };
 }
+// Read-only work-plan inspection is exposed alongside the collaboration app entry so an
+// installed consumer can evaluate a persisted plan without a second assignment registry.
+export { COLLAB_WORK_PLAN_REPORT_SCHEMA, inspectWorkPlan, } from './collab-work-plan.js';
+// Read-only rollover inspection is exposed alongside the collaboration app entry so an
+// installed consumer can inspect the exact record and linked bundle. There is no apply
+// path here: caller JSON is never accepted as native stop proof.
+export { COLLAB_ROLLOVER_REPORT_SCHEMA, COLLAB_ROLLOVER_REQUEST_SCHEMA, inspectOrPlanRollover, loadRolloverRequest, } from './collab-rollover.js';

package/dist/app/doctor.js

@@ -1,4 +1,4 @@
-import { join } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { diagnosticCodes } from '../schemas/errors.js';
 import { DOCTOR_REPORT_SCHEMA, doctorReportSchema, } from '../schemas/doctor.js';
@@ -10,6 +10,9 @@ import { resolveWorkspaceRoot } from '../workspace/resolve.js';
 import { resolveUserDataDir, inspectRuntimeStatePassive, } from '../install/runtime.js';
 import { ensureStatePathBoundary, inspectOwnedFile, readInstallJournal, readWorkspaceManifest, rootIdentityOf, scanJournalDirectory, workspaceInstallPaths, } from '../install/ownership.js';
 import { detectPassiveHosts, detectPassiveTool } from '../hosts/detect.js';
+import { inspectWorkspaceLocks } from '../install/repair.js';
+import { inspectLocalResetState } from '../install/reset-local.js';
+import { inspectPrivateLock } from '../infra/private-lock.js';
 function truncateText(value, limit) {
     return value.length <= limit
         ? value
@@ -127,7 +130,9 @@ async function inspectInstallState(root, observedAt) {
                 actions.push(`Review ${entry.path}; rollback/uninstall will preserve the user-modified file.`);
             }
             if (entry.backupRef !== null) {
-                const backupPath = join(root, ...entry.backupRef.split('/'));
+                const backupPath = isAbsolute(entry.backupRef)
+                    ? resolve(entry.backupRef)
+                    : join(root, ...entry.backupRef.split('/'));
                 const backupBoundary = await ensureStatePathBoundary(root, backupPath);
                 const realBackup = await resolveRealpath(backupPath);
                 const backupEscapes = realBackup !== null &&
@@ -247,6 +252,19 @@ function runtimeCheck(targetVersion, machineRuntime, passive, machinePath, obser
             nextActions: ['Run pappra init to establish a workspace runtime target.'],
         });
     }
+    if (passive?.status === 'incompatible') {
+        return makeCheck({
+            id: 'runtime.state',
+            code: diagnosticCodes.runtimeStateIncompatible,
+            status: 'error',
+            severity: 'error',
+            title: 'Runtime state requires reinitialization',
+            summary: diagnosticsSummary(passive.diagnostics),
+            source: passive.runtimeRoot,
+            observedAt,
+            nextActions: passive.diagnostics.flatMap((entry) => entry.hint === null ? [] : [entry.hint]),
+        });
+    }
     if (machineRuntime === null) {
         if (passive === null) {
             return makeCheck({
@@ -663,6 +681,63 @@ export async function runDoctor(options = {}) {
                 ],
     }));
     if (root !== null) {
+        const resetState = await inspectLocalResetState(root);
+        if (resetState === 'pending' || resetState === 'unreadable')
+            checks.push(makeCheck({
+                id: 'state.local-reset',
+                code: diagnosticCodes.initApplyResidual,
+                status: 'warning',
+                severity: 'warning',
+                title: 'Private local reset',
+                summary: `Local reset metadata is ${resetState}; retained archives were not changed.`,
+                source: join(root, '.pappra/local-archive/pending-reset.json'),
+                observedAt,
+                coverage: 'read-only local reset journal status; no process is stopped or adopted',
+                evidence: [],
+                nextActions: [
+                    'After stopping all affected writers, resume with pappra repair --reset-local --all-writers-stopped --apply.',
+                ],
+            }));
+        try {
+            const locks = await inspectWorkspaceLocks(root);
+            const needsRepair = locks.some((lock) => lock.state === 'dead' || lock.state === 'unknown');
+            checks.push(makeCheck({
+                id: 'state.writer-locks',
+                code: diagnosticCodes.document_locked,
+                status: needsRepair ? 'warning' : 'ok',
+                severity: needsRepair ? 'warning' : 'info',
+                title: 'Private writer locks',
+                summary: locks.length === 0
+                    ? 'No private writer lock remains.'
+                    : locks.map((lock) => `${lock.state}: ${lock.file}`).join('; '),
+                source: join(root, '.pappra/local'),
+                observedAt,
+                coverage: 'bounded install, knowledge and checkpoint lock inventory; process identity or positive owner-death evidence',
+                evidence: locks.map((lock) => fileEvidence(lock.file, observedAt, lock.digest)),
+                nextActions: needsRepair
+                    ? [
+                        'Run pappra repair to inspect owner states; use --apply only for provably dead writers. Unknown/live owners are preserved.',
+                    ]
+                    : [],
+            }));
+        }
+        catch (error) {
+            checks.push(makeCheck({
+                id: 'state.writer-locks',
+                code: diagnosticCodes.document_locked,
+                status: 'error',
+                severity: 'error',
+                title: 'Private writer locks',
+                summary: `Cannot inspect private lock state: ${error instanceof Error ? error.message : String(error)}`,
+                source: join(root, '.pappra/local'),
+                observedAt,
+                coverage: 'private lock paths are unsafe or inventory was unavailable',
+                evidence: [],
+                nextActions: [
+                    'Inspect pappra repair output and the reported path; no lock was changed.',
+                ],
+            }));
+        }
         const workspaceInspection = await inspectWorkspaceConfig(root, {
             missing: 'info',
         });
@@ -886,6 +961,7 @@ export async function runDoctor(options = {}) {
         ],
     }));
     const selectedHosts = machine?.selectedHosts ?? [];
+    const observableHosts = ['pi', 'codex', 'claude'];
     // Passive observation only: a host install can target the private default root, a
     // project directory, or Codex's user configuration directory.
     const hostInstallRoots = (host) => {
@@ -898,7 +974,7 @@ export async function runDoctor(options = {}) {
         }
         return roots;
     };
-    const installedHostBundle = (await Promise.all(selectedHosts.map(async (host) => {
+    const installedHostBundle = (await Promise.all(observableHosts.map(async (host) => {
         for (const base of hostInstallRoots(host)) {
             const path = join(base, 'pappra-host.json');
             if ((await observePath(path)).kind === 'file')
@@ -906,7 +982,34 @@ export async function runDoctor(options = {}) {
         }
         return null;
     }))).find((path) => path !== null) ?? null;
-    const installedHostSkill = (await Promise.all(selectedHosts.map(async (host) => {
+    const hostLocks = (await Promise.all(observableHosts.flatMap((host) => hostInstallRoots(host).map(async (base) => ({
+        host,
+        base,
+        owner: await inspectPrivateLock(join(base, '.pappra-host.lock')),
+    }))))).filter((entry) => entry.owner.state !== 'missing');
+    if (hostLocks.length > 0)
+        checks.push(makeCheck({
+            id: 'host.install-locks',
+            code: diagnosticCodes.host_install_conflict,
+            status: hostLocks.every((entry) => entry.owner.state === 'alive')
+                ? 'partial'
+                : 'warning',
+            severity: hostLocks.every((entry) => entry.owner.state === 'alive')
+                ? 'info'
+                : 'warning',
+            title: 'Host installation locks',
+            summary: `${hostLocks.length} host lock(s) observed; live owners are retained, dead owners can be reclaimed, and unknown owners require an explicit stopped-writer assertion.`,
+            source: hostLocks[0].owner.file,
+            observedAt,
+            coverage: 'known project/private/user host roots only',
+            evidence: hostLocks.map((entry) => fileEvidence(entry.owner.file, observedAt, entry.owner.digest)),
+            nextActions: hostLocks.map((entry) => entry.owner.state === 'alive'
+                ? `Let the verified live ${entry.host} writer finish; --force cannot override it.`
+                : entry.owner.state === 'dead'
+                    ? `Retry host install --host ${entry.host} --host-root ${JSON.stringify(entry.base)} to reclaim the proven dead owner.`
+                    : `Stop all writers for ${entry.base}, then run pappra host uninstall --host ${entry.host} --host-root ${JSON.stringify(entry.base)} --force --apply to archive an unknown lock.`),
+        }));
+    const installedHostSkill = (await Promise.all(observableHosts.map(async (host) => {
         for (const base of hostInstallRoots(host)) {
             const path = join(base, 'skills', 'pappra', 'SKILL.md');
             if ((await observePath(path)).kind === 'file')
@@ -922,7 +1025,7 @@ export async function runDoctor(options = {}) {
         severity: 'info',
         title: 'Host integration',
         summary: installedHostBundle === null
-            ? 'No P09 host bundle manifest was observed under the selected host roots; no host, session, or model was started.'
+            ? 'No host bundle manifest was observed under the known host roots; no host, session, or model was started.'
             : `P09 host bundle manifest exists at ${installedHostBundle}; native trust, reload and callability remain unverified and no host was started.`,
         source: installedHostBundle ?? root ?? homeDir,
         observedAt,

package/dist/app/host-mcp.js

@@ -1,6 +1,7 @@
 import { spawnSync } from 'node:child_process';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
+import { observePath, readTextFileBounded } from '../infra/fs.js';
+import { ensureStatePathBoundary, writeJsonAtomic, } from '../install/ownership.js';
 const MCP_ENTRY = { command: 'pappra', args: ['mcp'] };
 function mcpConfigPath(host, root) {
     if (host === 'claude')
@@ -19,10 +20,26 @@ function sameEntry(value) {
         args.length === MCP_ENTRY.args.length &&
         args.every((arg, index) => arg === MCP_ENTRY.args[index]));
 }
-async function readConfig(path) {
+async function readConfig(path, root) {
     let text;
     try {
-        text = await readFile(path, 'utf8');
+        const boundary = await ensureStatePathBoundary(root, path);
+        if (!boundary.ok)
+            return { ok: false, message: boundary.message };
+        const observation = await observePath(path);
+        if (observation.kind === 'missing') {
+            return { ok: true, value: {}, exists: false };
+        }
+        if (observation.kind !== 'file') {
+            return {
+                ok: false,
+                message: `MCP config is not a regular file: ${path}`,
+            };
+        }
+        const read = await readTextFileBounded(path);
+        if (!read.ok)
+            return { ok: false, message: read.message };
+        text = read.value.text;
     }
     catch (error) {
         if (typeof error === 'object' &&
@@ -72,7 +89,7 @@ export async function planHostMcp(host, root) {
             message: `No MCP registration is defined for ${host}.`,
         };
     }
-    const config = await readConfig(target);
+    const config = await readConfig(target, root);
     if (!config.ok) {
         return {
             host,
@@ -150,7 +167,8 @@ export async function applyHostMcp(plan, options) {
     if (target === null) {
         return { ...plan, applied: false, verified: false, detail: plan.message };
     }
-    const config = await readConfig(target);
+    const root = plan.host === 'pi' ? dirname(dirname(target)) : dirname(target);
+    const config = await readConfig(target, root);
     if (!config.ok) {
         return { ...plan, applied: false, verified: false, detail: config.message };
     }
@@ -161,8 +179,15 @@ export async function applyHostMcp(plan, options) {
             : {}),
         pappra: MCP_ENTRY,
     };
-    await mkdir(dirname(target), { recursive: true });
-    await writeFile(target, `${JSON.stringify({ ...config.value, mcpServers: nextServers }, null, 2)}\n`);
+    const written = await writeJsonAtomic(target, { ...config.value, mcpServers: nextServers }, root);
+    if (!written.ok) {
+        return {
+            ...plan,
+            applied: false,
+            verified: false,
+            detail: written.message,
+        };
+    }
     const verified = await verifyHostMcp(plan);
     return {
         ...plan,
@@ -210,7 +235,8 @@ export async function verifyHostMcp(plan) {
     if (plan.target === null) {
         return { ...plan, applied: false, verified: false, detail: plan.message };
     }
-    const config = await readConfig(plan.target);
+    const root = plan.host === 'pi' ? dirname(dirname(plan.target)) : dirname(plan.target);
+    const config = await readConfig(plan.target, root);
     if (!config.ok) {
         return { ...plan, applied: false, verified: false, detail: config.message };
     }

package/dist/app/host-probe.js

@@ -3,7 +3,7 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { HOST_SUPPORT } from '../hosts/integration/support.js';
+import { HOST_SUPPORT, isSupportedVersion, } from '../hosts/integration/support.js';
 function commandVersion(command) {
     const result = spawnSync(command, ['--version'], {
         encoding: 'utf8',
@@ -42,10 +42,10 @@ export function probeHost(host) {
             version,
             pinnedVersion,
             protocol: 'version-only',
-            ok: version === pinnedVersion,
+            ok: isSupportedVersion(host, version),
             details: { matchesPinnedVersion: version === pinnedVersion },
-            message: version === pinnedVersion
-                ? 'Version matches the pinned support matrix; lifecycle callability still needs a real session.'
+            message: isSupportedVersion(host, version)
+                ? 'Version matches an observed event contract; lifecycle callability still needs a real session.'
                 : `Version ${version} does not match the pinned ${pinnedVersion}.`,
         };
     }

package/dist/app/init.d.ts

@@ -3,6 +3,7 @@ import type { DiagnosticCode } from '../schemas/errors.js';
 import { type InitChoices, type InitExternalAction, type InitPlan } from '../schemas/init.js';
 import { type MachineConfig } from '../schemas/machine.js';
 import { type WorkspaceConfig, type WorkspaceValidation } from '../schemas/workspace.js';
+import { type GitRepositoryObservation } from '../infra/git.js';
 import type { MachineConfigInspection, WorkspaceConfigInspection } from '../workspace/config.js';
 import { type WorkspaceDiscovery } from '../workspace/discover.js';
 import { type PlannedFileContent } from '../install/plan.js';
@@ -96,6 +97,8 @@ export interface InitApplyResult {
 export interface InitApplyOptions {
     /** Fault-injection seam for tests; the CLI never supplies this hook. */
     readonly beforeWrite?: (relativePath: string, index: number) => Promise<void> | void;
+    /** Test seam after durable create, before its identity is journaled; never supplied by CLI. */
+    readonly afterWrite?: (relativePath: string, index: number) => Promise<void> | void;
 }
 export interface KnowledgeCandidate {
     readonly path: string;
@@ -113,6 +116,27 @@ export interface RepositoryCandidate {
     readonly dirty: boolean | null;
     readonly configured: boolean;
 }
+export type InitPathAdditionKind = 'repository' | 'knowledge';
+/** Read-only snapshot of one exact, explicitly entered workspace-relative path. */
+export interface InitPathObservation {
+    readonly kind: InitPathAdditionKind;
+    readonly requestedPath: string;
+    /** Canonical workspace-relative path suitable for an existing InitChoices field. */
+    readonly path: string;
+    readonly realPath: string;
+    readonly targetKind: 'file' | 'directory';
+    readonly device: number;
+    readonly inode: number;
+    /** Actual bounded Git metadata observation for repository additions. */
+    readonly git: GitRepositoryObservation | null;
+}
+export type InitPathInspectionResult = {
+    readonly ok: true;
+    readonly observation: InitPathObservation;
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly Diagnostic[];
+};
 export interface PlanInitOptions {
     readonly root: string;
     readonly choices?: InitChoices | null;
@@ -123,6 +147,8 @@ export interface PlanInitOptions {
     readonly discoveredAt?: string;
     /** Reuse an immediately preceding inspectInitContext result. */
     readonly context?: InitContext;
+    /** In-memory UI observations; planning re-inspects each path before use. */
+    readonly pathObservations?: readonly InitPathObservation[];
 }
 /** Resolves the explicit root and refuses to create a hidden nested workspace. */
 export declare function resolveInitRoot(rootPath: string): Promise<InitRootResult>;
@@ -151,6 +177,32 @@ export interface DerivedInitChoices {
     readonly rules: readonly InitChoiceRule[];
     readonly candidates: InitChoiceCandidates;
 }
+export interface CommonInitDefaults {
+    readonly name: string;
+    readonly knowledge: InitChoices['knowledge'];
+    readonly code: Pick<InitChoices['code'], 'symbols' | 'prepare'>;
+    readonly excludes: readonly string[];
+}
+/**
+ * Pure discovery-based selections shared by derived and interactive setup.
+ * Mode-specific repositories, validation, graph and host choices stay with
+ * their callers.
+ */
+export declare function deriveCommonInitDefaults(discovery: WorkspaceDiscovery): CommonInitDefaults;
+/**
+ * Converts an existing valid workspace/machine pair into a lossless editable
+ * selection draft. Extensions and continuity are intentionally not part of
+ * InitChoices; plan reconstruction preserves them from the existing config.
+ */
+export declare function existingInitChoices(config: WorkspaceConfig, machine: MachineConfig | null): InitChoices;
+export type InitEditableField = 'name' | 'newDocuments' | 'excludes' | 'repositoryPath' | 'knowledgePath';
+/**
+ * Immediate UI field feedback using the same name schema, portable-path rules,
+ * literal-prefix exclusion policy and workspace-relative semantics as planning.
+ */
+export declare function validateInitField(field: InitEditableField, value: string): string | null;
+/** Inspects one user-entered path only; it never broadens workspace discovery. */
+export declare function inspectInitPathAddition(root: string, kind: InitPathAdditionKind, inputPath: string, excludes?: readonly string[], location?: string | null): Promise<InitPathInspectionResult>;
 export declare function detectedHostVersion(command: string, pathEnv: string): string | null;
 /**
  * Derives deterministic init selections from discovery alone. Every value is
@@ -166,7 +218,7 @@ export declare function deriveInitChoices(discovery: WorkspaceDiscovery, options
  */
 export declare function planWorkspaceInit(options: PlanInitOptions): Promise<InitPreparation>;
 /**
- * Applies only create operations from a plan, after revalidating root,
+ * Applies create and managed replacement operations from a plan, after revalidating root,
  * configuration digest, target absence and exact bytes. External actions are
  * reported as pending and never executed here.
  */
@@ -179,8 +231,10 @@ export interface RuntimeFlowResult {
 }
 export declare function bindAndRecordRuntime(root: string, installed: RuntimeInstallResult): Promise<RuntimeFlowResult>;
 /**
- * Converges the runtime binding by installing a durable copy of the package that
- * is currently executing. Reusing an already verified copy is cheap: the install
- * machinery short-circuits before packing.
+ * Ensures and binds the runtime package that is currently executing.
+ *
+ * The installer reuses an existing runtime only after its manifest, package
+ * contents, executable and smoke checks pass; a regular file is not proof of a
+ * verified durable runtime.
  */
 export declare function ensureDefaultRuntime(root: string, targetVersion: string): Promise<RuntimeFlowResult>;