@phyzess/pappra 0.1.0-beta.11 → 0.1.0-beta.12

package/README.md

@@ -8,7 +8,7 @@ Pappra is the manager. External coding hosts, code-graph engines and collaborati
 
 Requirements: Node.js 24 or later. `pnpm` 12.3.4 is required only for development inside this repository; Git is required only when a command observes repository identity.
 
-The package is published as `@phyzess/pappra`. Run it with `npx` from the target workspace, or install it globally when you use it every day.
+The package is published as `@phyzess/pappra`. Install it once for daily use (`npm install -g @phyzess/pappra@beta`, the command is `pappra`), or run it with `npx` when you want a zero-install, version-pinned invocation.
 
 ```sh
 # In an empty target workspace
@@ -38,6 +38,11 @@ that action pending instead; the result is then `ok:true` with
 `status:"external-actions-pending"` and a nonzero exit, which is a partial configuration
 write rather than a claim that a runtime exists.
 
+For a new workspace or a new machine, `pappra onboard --dry-run --json` shows the plan and
+the host version matrix; `pappra onboard --yes --apply-host --json` applies config, runtime
+and verified host wiring (host trust still needs one approval). See
+[portability](docs/portability.md).
+
 The runtime copy can be managed directly:
 
 ```sh
@@ -89,7 +94,7 @@ The check runs the source policy, type checks, formatting, deterministic tests a
 
 ## Status and limits
 
-Pappra is development software (`0.1.0-beta.11`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.11`, because pre-release versions are never republished.
+Pappra is development software (`0.1.0-beta.12`) published as `@phyzess/pappra` under the `beta` dist-tag. Releases are published from GitHub Actions with npm trusted publishing (OIDC), so no npm token is stored in this repository. Pin either the moving `beta` tag or an exact version such as `@phyzess/pappra@0.1.0-beta.12`, because pre-release versions are never republished.
 
 The deterministic suite covers synthetic workspaces, fixtures and local process boundaries. It does not establish real-model behavior, native host callability on every platform, CodeGraph completeness, Windows/Linux parity or production performance. A host adapter version pin is an observed support claim, not proof that a particular native installation will load or run correctly.
 

package/assets/integrations/skills/pappra/references/operations.md

@@ -1,5 +1,8 @@
 # Operations reference
 
+- `pappra onboard` plans or applies a whole workspace setup (config, durable runtime,
+  verified host wiring). `--dry-run` writes nothing; `--apply-host` still leaves host trust
+  to the person.
 - `pappra init` plans or applies workspace configuration. `--yes` derives
   selections from discovery, `--print-choices` prints that document without
   writing, `--reconfigure` rebuilds an existing valid `workspace.json`, and

package/dist/app/init.d.ts

@@ -6,6 +6,7 @@ import { type WorkspaceConfig, type WorkspaceValidation } from '../schemas/works
 import type { MachineConfigInspection, WorkspaceConfigInspection } from '../workspace/config.js';
 import { type WorkspaceDiscovery } from '../workspace/discover.js';
 import { type PlannedFileContent } from '../install/plan.js';
+import { type RuntimeInstallResult } from '../install/runtime.js';
 export type InitFailureStatus = 'needs_input' | 'invalid' | 'conflict' | 'unavailable';
 export interface InitFailure {
     readonly ok: false;
@@ -150,6 +151,7 @@ export interface DerivedInitChoices {
     readonly rules: readonly InitChoiceRule[];
     readonly candidates: InitChoiceCandidates;
 }
+export declare function detectedHostVersion(command: string, pathEnv: string): string | null;
 /**
  * Derives deterministic init selections from discovery alone. Every value is
  * reported with the rule that produced it so a caller can audit the choice
@@ -169,3 +171,16 @@ export declare function planWorkspaceInit(options: PlanInitOptions): Promise<Ini
  * reported as pending and never executed here.
  */
 export declare function applyInitPlan(bundle: InitPlanBundle, options?: InitApplyOptions): Promise<InitApplyResult>;
+export interface RuntimeFlowResult {
+    readonly ok: boolean;
+    readonly completion: boolean;
+    readonly runtime: RuntimeInstallResult | null;
+    readonly diagnostics: readonly Diagnostic[];
+}
+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.
+ */
+export declare function ensureDefaultRuntime(root: string, targetVersion: string): Promise<RuntimeFlowResult>;

package/dist/app/init.js

@@ -7,7 +7,7 @@ import { INIT_CHOICES_SCHEMA, initPlanSchema, parseInitChoices, } from '../schem
 import { machineConfigSchema } from '../schemas/machine.js';
 import { isExternalRepositoryPath, isPathInside, isPortableRelativePath, normalizePortableRelativePath, resolvePortableRelativePath, samePath, } from '../schemas/paths.js';
 import { WORKSPACE_SCHEMA, validateWorkspaceConfigSemantics, workspaceConfigSchema, } from '../schemas/workspace.js';
-import { getPackageInfo } from '../package-info.js';
+import { getPackageInfo, getPackageRoot } from '../package-info.js';
 import { spawnSync } from 'node:child_process';
 import { executableOnPath } from '../hosts/detect.js';
 import { HOST_SUPPORT } from '../hosts/integration/support.js';
@@ -17,7 +17,8 @@ import { discoverWorkspace, } from '../workspace/discover.js';
 import { resolveWorkspaceRoot } from '../workspace/resolve.js';
 import { buildInitPlan } from '../install/plan.js';
 import { backupPath, ensureStatePathBoundary, readWorkspaceManifest, writeWorkspaceManifest, } from '../install/ownership.js';
-import { beginManagedApply, completeManagedApply, failManagedApply, recordManagedFile, } from '../install/apply.js';
+import { beginManagedApply, completeManagedApply, failManagedApply, recordManagedFile, updateMachineRuntime, } from '../install/apply.js';
+import { installRuntime, } from '../install/runtime.js';
 const workspaceConfigRelativePath = '.pappra/workspace.json';
 const machineConfigRelativePath = '.pappra/local/machine.json';
 function failure(status, code, message, diagnostics = [], nextAction = null) {
@@ -251,7 +252,7 @@ const derivedExcludes = [
     'test-results',
 ];
 const derivedValidationScripts = ['lint', 'typecheck', 'test'];
-function detectedHostVersion(command, pathEnv) {
+export function detectedHostVersion(command, pathEnv) {
     const executable = executableOnPath(command, pathEnv);
     if (executable === null)
         return null;
@@ -1440,3 +1441,81 @@ export async function applyInitPlan(bundle, options = {}) {
         };
     }
 }
+export async function bindAndRecordRuntime(root, installed) {
+    if (!installed.ok || installed.manifest === null) {
+        return {
+            ok: false,
+            completion: false,
+            runtime: installed,
+            diagnostics: installed.diagnostics,
+        };
+    }
+    const updated = await updateMachineRuntime(root, installed.manifest);
+    if (!updated.ok) {
+        return {
+            ok: false,
+            completion: false,
+            runtime: installed,
+            diagnostics: updated.diagnostics,
+        };
+    }
+    const followUp = await planWorkspaceInit({ root });
+    if (!followUp.ok) {
+        return {
+            ok: false,
+            completion: false,
+            runtime: installed,
+            diagnostics: followUp.diagnostics,
+        };
+    }
+    if (followUp.bundle.plan.files.length > 0 ||
+        followUp.bundle.plan.externalActions.length > 0) {
+        return {
+            ok: false,
+            completion: false,
+            runtime: installed,
+            diagnostics: [
+                {
+                    code: diagnosticCodes.initRuntimeSourceRequired,
+                    severity: 'error',
+                    message: 'Runtime installation succeeded but init still has pending file or external actions.',
+                    source: 'init runtime',
+                    pointer: null,
+                    hint: 'Run pappra init again to review the remaining plan; initialization is not complete.',
+                },
+            ],
+        };
+    }
+    return {
+        ok: true,
+        completion: true,
+        runtime: installed,
+        diagnostics: [],
+    };
+}
+/**
+ * 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.
+ */
+export async function ensureDefaultRuntime(root, targetVersion) {
+    const machine = await inspectMachineConfig(root);
+    const binding = machine.value?.runtime ?? null;
+    if (binding !== null && binding.version === targetVersion) {
+        const executable = await observePath(binding.executable);
+        if (executable.kind === 'file') {
+            return {
+                ok: true,
+                completion: true,
+                runtime: null,
+                diagnostics: [],
+            };
+        }
+    }
+    const installed = await installRuntime({
+        version: targetVersion,
+        source: { kind: 'self', path: getPackageRoot() },
+        packageName: getPackageInfo().name,
+    });
+    return bindAndRecordRuntime(root, installed);
+}

package/dist/app/onboard.d.ts

@@ -0,0 +1,60 @@
+import type { Diagnostic } from '../schemas/diagnostics.js';
+import type { HostName } from '../schemas/host.js';
+import type { InitChoices } from '../schemas/init.js';
+import { type InitContext, type InitPlanBundle } from './init.js';
+export type OnboardHostState = 'verified' | 'unverified' | 'unsupported' | 'missing';
+export interface OnboardHostPlan {
+    readonly host: HostName;
+    readonly command: string;
+    readonly detectedVersion: string | null;
+    readonly pinnedVersion: string;
+    readonly state: OnboardHostState;
+}
+export interface OnboardHostResult extends OnboardHostPlan {
+    readonly action: 'planned' | 'installed' | 'unchanged' | 'skipped' | 'failed';
+    readonly appliedFiles: readonly string[];
+    readonly nextActions: readonly string[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface OnboardPlan {
+    readonly context: InitContext;
+    readonly choices: InitChoices;
+    readonly bundle: InitPlanBundle;
+    readonly hosts: readonly OnboardHostPlan[];
+    readonly requestedHosts: readonly HostName[];
+}
+export interface OnboardResult {
+    readonly schema: 'pappra/onboard/1';
+    readonly ok: boolean;
+    readonly dryRun: boolean;
+    readonly workspaceRoot: string;
+    readonly files: readonly {
+        readonly path: string;
+        readonly operation: string;
+    }[];
+    readonly runtime: {
+        readonly version: string;
+        readonly status: string;
+    } | null;
+    readonly initComplete: boolean;
+    readonly hosts: readonly OnboardHostResult[];
+    readonly manualSteps: readonly string[];
+    readonly nextActions: readonly string[];
+    readonly diagnostics: readonly Diagnostic[];
+}
+export interface OnboardFailure {
+    readonly ok: false;
+    readonly reason: 'invalid' | 'needs_input' | 'unavailable' | 'failed';
+    readonly message: string;
+    readonly diagnostics: readonly Diagnostic[];
+}
+export declare function parseHostList(value: string | null): HostName[] | null;
+export declare function planOnboard(options: {
+    readonly root: string;
+    readonly choices?: InitChoices | null;
+    readonly hosts?: readonly HostName[] | null;
+    readonly pathEnv?: string;
+}): Promise<OnboardPlan | OnboardFailure>;
+export declare function applyOnboard(plan: OnboardPlan, options: {
+    readonly applyHosts: boolean;
+}): Promise<OnboardResult>;

package/dist/app/onboard.js

@@ -0,0 +1,259 @@
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { HOST_SUPPORT } from '../hosts/integration/support.js';
+import { exportHostPluginBundle } from '../hosts/integration/bundle-export.js';
+import { HostIntegrationService } from '../hosts/integration/service.js';
+import { getPackageInfo } from '../package-info.js';
+import { resolveWorkspaceRoot } from '../workspace/resolve.js';
+import { applyInitPlan, deriveInitChoices, detectedHostVersion, ensureDefaultRuntime, inspectInitContext, planWorkspaceInit, } from './init.js';
+const HOSTS = ['claude', 'codex', 'pi'];
+const HOST_COMMAND = {
+    claude: 'claude',
+    codex: 'codex',
+    pi: 'pi',
+};
+function sameMinor(left, right) {
+    const [leftMajor, leftMinor] = left.split('.');
+    const [rightMajor, rightMinor] = right.split('.');
+    return leftMajor === rightMajor && leftMinor === rightMinor;
+}
+function hostState(detected, pinned) {
+    if (detected === null)
+        return 'missing';
+    if (detected === pinned)
+        return 'verified';
+    return sameMinor(detected, pinned) ? 'unverified' : 'unsupported';
+}
+function detectHosts(pathEnv, requested) {
+    return HOSTS.filter((host) => requested === null || requested.includes(host)).map((host) => {
+        const pinnedVersion = HOST_SUPPORT[host].version;
+        const detectedVersion = detectedHostVersion(HOST_COMMAND[host], pathEnv);
+        return {
+            host,
+            command: HOST_COMMAND[host],
+            detectedVersion,
+            pinnedVersion,
+            state: hostState(detectedVersion, pinnedVersion),
+        };
+    });
+}
+export function parseHostList(value) {
+    if (value === null || value.trim() === '')
+        return null;
+    const parsed = [];
+    for (const entry of value.split(',')) {
+        const name = entry.trim();
+        if (name === 'claude' || name === 'codex' || name === 'pi') {
+            if (!parsed.includes(name))
+                parsed.push(name);
+            continue;
+        }
+        throw new Error(`Unknown host: ${name}`);
+    }
+    return parsed;
+}
+export async function planOnboard(options) {
+    const requestedRoot = resolve(options.root);
+    const resolution = await resolveWorkspaceRoot({ startPath: requestedRoot });
+    if (resolution.state === 'unavailable' || resolution.state === 'incomplete') {
+        return {
+            ok: false,
+            reason: 'unavailable',
+            message: `Cannot initialize from ${requestedRoot}.`,
+            diagnostics: resolution.diagnostics,
+        };
+    }
+    const root = resolution.root ?? requestedRoot;
+    const contextResult = await inspectInitContext(root);
+    if (!contextResult.ok) {
+        return {
+            ok: false,
+            reason: contextResult.status === 'invalid' ? 'invalid' : 'failed',
+            message: contextResult.message,
+            diagnostics: contextResult.diagnostics,
+        };
+    }
+    const context = contextResult.context;
+    const pathEnv = options.pathEnv ?? process.env['PATH'] ?? '';
+    const requestedHosts = options.hosts ?? null;
+    const derived = options.choices ??
+        (await deriveInitChoices(context.discovery, { pathEnv })).choices;
+    const choices = requestedHosts === null
+        ? derived
+        : { ...derived, hosts: [...requestedHosts] };
+    const prepared = await planWorkspaceInit({
+        root: context.root,
+        choices,
+        context,
+    });
+    if (!prepared.ok) {
+        return {
+            ok: false,
+            reason: prepared.status === 'invalid' ? 'invalid' : 'failed',
+            message: prepared.message,
+            diagnostics: prepared.diagnostics,
+        };
+    }
+    return {
+        context,
+        choices,
+        bundle: prepared.bundle,
+        hosts: detectHosts(pathEnv, requestedHosts),
+        requestedHosts: choices.hosts,
+    };
+}
+function hostTarget(host, root) {
+    if (host === 'claude')
+        return join(root, '.claude');
+    if (host === 'codex') {
+        const configured = process.env['CODEX_HOME'];
+        return configured === undefined || configured === ''
+            ? join(homedir(), '.codex')
+            : resolve(configured);
+    }
+    return null;
+}
+async function wireHost(plan, root, packageVersion) {
+    if (plan.state !== 'verified') {
+        const detail = plan.state === 'missing'
+            ? `Host ${plan.command} is not installed.`
+            : `Host ${plan.command} ${plan.detectedVersion ?? '(unknown)'} does not match the pinned ${plan.pinnedVersion}.`;
+        return {
+            ...plan,
+            action: 'skipped',
+            appliedFiles: [],
+            nextActions: [
+                `${detail} Install the pinned version, or use pappra host install --mode project-settings explicitly.`,
+            ],
+            diagnostics: [],
+        };
+    }
+    if (plan.host === 'pi') {
+        const outDir = join(root, '.pappra', 'host-bundles', 'pi');
+        try {
+            const exported = await exportHostPluginBundle({
+                host: 'pi',
+                hostVersion: plan.pinnedVersion,
+                outDir,
+                packageVersion,
+            });
+            return {
+                ...plan,
+                action: 'installed',
+                appliedFiles: exported.files.map((file) => `host-bundles/pi/${file}`),
+                nextActions: [
+                    `Run: pi install ${outDir} -l -a`,
+                    'Approve the project package trust prompt once in Pi.',
+                ],
+                diagnostics: [],
+            };
+        }
+        catch (error) {
+            return {
+                ...plan,
+                action: 'failed',
+                appliedFiles: [],
+                nextActions: [error instanceof Error ? error.message : String(error)],
+                diagnostics: [],
+            };
+        }
+    }
+    const target = hostTarget(plan.host, root);
+    if (target === null) {
+        return {
+            ...plan,
+            action: 'skipped',
+            appliedFiles: [],
+            nextActions: [`No install root is defined for ${plan.host}.`],
+            diagnostics: [],
+        };
+    }
+    await mkdir(target, { recursive: true });
+    const service = new HostIntegrationService({
+        root,
+        homeDir: homedir(),
+        pathEnv: process.env['PATH'] ?? '',
+        hostVersion: plan.pinnedVersion,
+        observedAt: new Date().toISOString(),
+    });
+    const installed = await service.install(plan.host, {
+        hostRoot: target,
+        hostVersion: plan.pinnedVersion,
+        apply: true,
+    });
+    const trust = plan.host === 'codex'
+        ? 'Approve the Pappra hook once in Codex; project `.codex/hooks.json` is not loaded by 0.163.0.'
+        : 'Reload the session and trust the Pappra hook if Claude Code prompts.';
+    return {
+        ...plan,
+        action: installed.status === 'applied'
+            ? 'installed'
+            : installed.status === 'unchanged'
+                ? 'unchanged'
+                : 'failed',
+        appliedFiles: installed.appliedFiles,
+        nextActions: [trust],
+        diagnostics: installed.diagnostics,
+    };
+}
+export async function applyOnboard(plan, options) {
+    const applied = await applyInitPlan(plan.bundle);
+    const diagnostics = [
+        ...plan.bundle.diagnostics,
+        ...applied.diagnostics,
+    ].filter((entry) => entry.severity !== 'info');
+    const runtime = applied.ok
+        ? await ensureDefaultRuntime(plan.bundle.scope.workspaceRoot, plan.bundle.scope.runtimeVersion)
+        : null;
+    if (runtime !== null) {
+        diagnostics.push(...runtime.diagnostics.filter((entry) => entry.severity !== 'info'));
+    }
+    const initComplete = applied.ok &&
+        applied.residualPaths.length === 0 &&
+        runtime?.completion === true;
+    const packageVersion = getPackageInfo().version;
+    const hosts = [];
+    const manualSteps = [];
+    for (const host of plan.hosts) {
+        const result = options.applyHosts
+            ? await wireHost(host, plan.bundle.scope.workspaceRoot, packageVersion)
+            : {
+                ...host,
+                action: 'planned',
+                appliedFiles: [],
+                nextActions: [
+                    'Rerun with --apply-host to write this host integration.',
+                ],
+                diagnostics: [],
+            };
+        hosts.push(result);
+        manualSteps.push(...result.nextActions);
+    }
+    const nextActions = [];
+    if (plan.choices.knowledge.sources.length > 0) {
+        nextActions.push('pappra docs scan --apply');
+    }
+    if (plan.choices.code.graph !== 'none' &&
+        plan.choices.repositories.length > 0) {
+        nextActions.push(`pappra code prepare --repo ${plan.choices.repositories[0]?.path ?? '<repo>'} --apply`);
+    }
+    return {
+        schema: 'pappra/onboard/1',
+        ok: initComplete && hosts.every((host) => host.action !== 'failed'),
+        dryRun: false,
+        workspaceRoot: plan.bundle.scope.workspaceRoot,
+        files: applied.appliedFiles.map((path) => ({ path, operation: 'write' })),
+        runtime: runtime?.runtime === null || runtime === null
+            ? null
+            : {
+                version: runtime.runtime.version,
+                status: runtime.runtime.status,
+            },
+        initComplete,
+        hosts,
+        manualSteps: [...new Set(manualSteps)],
+        nextActions,
+        diagnostics,
+    };
+}

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

@@ -1,6 +1,4 @@
-import type { Diagnostic } from '../../schemas/diagnostics.js';
 import { type InitChoices } from '../../schemas/init.js';
-import { type RuntimeInstallResult } from '../../install/runtime.js';
 import { type InitContext } from '../../app/init.js';
 import type { CliOutput } from '../output.js';
 export interface SelectOption {
@@ -41,12 +39,6 @@ export interface InitCommandOptions {
     /** Rebuilds workspace.json from the selections even when a valid config exists. */
     readonly reconfigure?: boolean;
 }
-export interface RuntimeFlowResult {
-    readonly ok: boolean;
-    readonly completion: boolean;
-    readonly runtime: RuntimeInstallResult | null;
-    readonly diagnostics: readonly Diagnostic[];
-}
 export interface InitCommandDeps {
     readonly ui?: WizardUi;
     readonly interactive?: boolean;

package/dist/cli/commands/init.js

@@ -2,12 +2,10 @@ import { basename, resolve } from 'node:path';
 import * as prompts from '@clack/prompts';
 import { diagnosticCodes } from '../../schemas/errors.js';
 import { INIT_CHOICES_SCHEMA, parseInitChoices, } from '../../schemas/init.js';
-import { observePath, readTextFileBounded } from '../../infra/fs.js';
-import { getPackageInfo, getPackageRoot } from '../../package-info.js';
-import { installRuntime, } from '../../install/runtime.js';
-import { updateMachineRuntime } from '../../install/apply.js';
-import { inspectMachineConfig } from '../../workspace/config.js';
-import { applyInitPlan, inspectInitContext, listKnowledgeCandidates, deriveInitChoices, listRepositoryCandidates, planWorkspaceInit, } from '../../app/init.js';
+import { readTextFileBounded } from '../../infra/fs.js';
+import { getPackageInfo } from '../../package-info.js';
+import { installRuntime } from '../../install/runtime.js';
+import { applyInitPlan, bindAndRecordRuntime, ensureDefaultRuntime, inspectInitContext, listKnowledgeCandidates, deriveInitChoices, listRepositoryCandidates, planWorkspaceInit, } from '../../app/init.js';
 export const clackWizardUi = {
     intro: (message) => prompts.intro(message),
     outro: (message) => prompts.outro(message),
@@ -250,84 +248,6 @@ function runtimeOptionsFailure(message, nextAction) {
         nextAction,
     };
 }
-async function bindAndRecordRuntime(root, installed) {
-    if (!installed.ok || installed.manifest === null) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: installed.diagnostics,
-        };
-    }
-    const updated = await updateMachineRuntime(root, installed.manifest);
-    if (!updated.ok) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: updated.diagnostics,
-        };
-    }
-    const followUp = await planWorkspaceInit({ root });
-    if (!followUp.ok) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: followUp.diagnostics,
-        };
-    }
-    if (followUp.bundle.plan.files.length > 0 ||
-        followUp.bundle.plan.externalActions.length > 0) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: [
-                {
-                    code: diagnosticCodes.initRuntimeSourceRequired,
-                    severity: 'error',
-                    message: 'Runtime installation succeeded but init still has pending file or external actions.',
-                    source: 'init runtime',
-                    pointer: null,
-                    hint: 'Run pappra init again to review the remaining plan; initialization is not complete.',
-                },
-            ],
-        };
-    }
-    return {
-        ok: true,
-        completion: true,
-        runtime: installed,
-        diagnostics: [],
-    };
-}
-/**
- * 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.
- */
-async function ensureDefaultRuntime(root, targetVersion) {
-    const machine = await inspectMachineConfig(root);
-    const binding = machine.value?.runtime ?? null;
-    if (binding !== null && binding.version === targetVersion) {
-        const executable = await observePath(binding.executable);
-        if (executable.kind === 'file') {
-            return {
-                ok: true,
-                completion: true,
-                runtime: null,
-                diagnostics: [],
-            };
-        }
-    }
-    const installed = await installRuntime({
-        version: targetVersion,
-        source: { kind: 'self', path: getPackageRoot() },
-        packageName: getPackageInfo().name,
-    });
-    return bindAndRecordRuntime(root, installed);
-}
 async function installAndRecordRuntime(root, targetVersion, options) {
     const tarball = options.runtimeTarball ?? null;
     const requestedVersion = options.runtimeVersion ?? null;
@@ -400,48 +320,7 @@ async function installAndRecordRuntime(root, targetVersion, options) {
             diagnostics: installed.diagnostics,
         };
     }
-    const updated = await updateMachineRuntime(root, installed.manifest);
-    if (!updated.ok) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: updated.diagnostics,
-        };
-    }
-    const followUp = await planWorkspaceInit({ root });
-    if (!followUp.ok) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: followUp.diagnostics,
-        };
-    }
-    if (followUp.bundle.plan.files.length > 0 ||
-        followUp.bundle.plan.externalActions.length > 0) {
-        return {
-            ok: false,
-            completion: false,
-            runtime: installed,
-            diagnostics: [
-                {
-                    code: diagnosticCodes.initRuntimeSourceRequired,
-                    severity: 'error',
-                    message: 'Runtime installation succeeded but init still has pending file or external actions.',
-                    source: 'init runtime',
-                    pointer: null,
-                    hint: 'Run pappra init again to review the remaining plan; initialization is not complete.',
-                },
-            ],
-        };
-    }
-    return {
-        ok: true,
-        completion: true,
-        runtime: installed,
-        diagnostics: [],
-    };
+    return bindAndRecordRuntime(root, installed);
 }
 function formatFailure(failure) {
     switch (failure.status) {