@north-light/crouter 0.3.227 → 0.3.229

package/dist/commands/pkg/plugin-manage.js

@@ -4,13 +4,15 @@ import { createHash } from 'node:crypto';
 import { defineLeaf } from '../../core/command.js';
 import { notFound, usage, general, network } from '../../core/errors.js';
 import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../core/resolver.js';
-import { pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
+import { NEUTRAL_PROJECT_MEMORY, pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
 import { updateConfig, updateState, ensureScopeInitialized, invalidPluginKindsReasons, invalidPluginBinReasons, invalidPluginRequiresReasons, normalizeRequires } from '../../core/config.js';
 import { invalidPageComponentsReasons } from '../../core/human/page-catalog.js';
-import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink, readSymlinkTarget, atomicWriteJson, readText, walkFiles } from '../../core/fs-utils.js';
+import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink, readSymlinkTarget, atomicWriteJson, readText, realpathOrSelf, walkFiles } from '../../core/fs-utils.js';
 import { clone, deriveNameFromUrl, currentSha, gitSync, isGitRepo } from '../../core/git.js';
 import { readMarketplaceManifest, readPluginManifest, validatePluginManifestMemoryExtensions } from '../../core/manifest.js';
 import { memoryExtensionValidationCatalog, validateMemoryExtensionValues } from '../../core/memory/extensions.js';
+import { lintMemoryStore, MEMORY_LINT_IDENTITY_RULES } from '../../core/memory/lint.js';
+import { buildCorpusSnapshot, loadCorpusSnapshots, parseFailureBlockers, runCorpusMigrations } from '../../migrations/corpus.js';
 import { lintSubstrateFrontmatter } from '../../core/substrate/frontmatter-validation.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
@@ -21,7 +23,7 @@ import { compileHookRegistry, discoverCandidateHookRegistry, discoverCandidateHo
 import { hasDeclaredHooks, hookReport } from '../../core/command-hooks/report.js';
 import { fetchHttpPluginBundle } from '../../core/command-plugins/transport/http-fetch.js';
 import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog } from '../../build-root.js';
-import { isGitUrl, setPluginEnabled, resolveInstallScope } from './shared.js';
+import { isGitUrl, resolvePluginConfigTarget, setPluginEnabled, resolveInstallScope } from './shared.js';
 /** Validate a just-installed/updated plugin's command manifest, if it declares
  *  one. Returns undefined for plugins without a `commands` pointer. Never
  *  executes the plugin binary — validation is fully static. */
@@ -158,9 +160,71 @@ async function assertManifestHooksValid(manifest, root, scope, scopeRootPath, wh
     if (issues.length > 0)
         throw invalidBundleError(`plugin hook behavior at ${where} is invalid`, issues);
 }
+function pluginCandidateStore(name, scope, storeRoot) {
+    return { scope, storeRoot, namespace: name, plugin: name, mountStatus: 'ready', projectMemory: NEUTRAL_PROJECT_MEMORY };
+}
+function storeRelative(storeRoot, path) {
+    const rel = relative(storeRoot, path);
+    return rel === '' ? storeRoot : rel;
+}
+function corpusBlockedError(name, where, storeRoot, blockers, wrote) {
+    const lines = blockers.map((b) => `- ${b.kind}${b.path === undefined ? '' : ` at ${storeRelative(storeRoot, b.path)}`}: ${b.message}`);
+    return general(`plugin "${name}" memory corpus at ${where} cannot be migrated to exact canonical identity:\n${lines.join('\n')}`, {
+        blockers,
+        next: wrote === 0
+            ? `Correct the package's memory corpus, then retry — nothing was written and "${name}" was not activated.`
+            : `Correct the package's memory corpus, then re-run — the rewrite is on disk but failed verification, and "${name}" was not activated.`,
+    });
+}
+/** Converge a candidate package's memory corpus onto exact canonical identity
+ * through the same corpus planner `crtr sys migrate` runs, then refuse the
+ * candidate on any identity finding that would leave it unmountable. The
+ * package is one store no target mounts, so its links and routes resolve
+ * against itself; a blocked plan writes nothing at all. */
+function migratePluginMemory(manifest, root, scope, where, ownership) {
+    const storeRoot = join(root, 'memory');
+    if (!pathExists(storeRoot))
+        return undefined;
+    const discovery = {
+        roots: [{ reason: 'plugin', root: storeRoot, boundary: 'store', detail: manifest.name }],
+        stores: [{
+                key: realpathOrSelf(storeRoot),
+                descriptor: pluginCandidateStore(manifest.name, scope, storeRoot),
+                discovery: [{ reason: 'plugin', root: storeRoot }],
+                targets: [],
+                writable: true,
+            }],
+        targets: [],
+        blockers: [],
+        nodeMetadata: { available: true, nodes: 0 },
+    };
+    const load = () => {
+        const { snapshots, skipped } = loadCorpusSnapshots(discovery);
+        return { corpus: buildCorpusSnapshot(discovery, snapshots), blockers: parseFailureBlockers(skipped) };
+    };
+    const initial = load();
+    const run = runCorpusMigrations(initial.corpus, { blockers: initial.blockers, rebuild: () => load().corpus });
+    const wrote = run.wrote.consumers.length + run.wrote.identities.length;
+    if (run.blocked)
+        throw corpusBlockedError(manifest.name, where, storeRoot, run.blockers, wrote);
+    // Reference checks are deliberately skipped (no `resolvable`): a package's
+    // links reach documents that only exist in the corpus it will be mounted
+    // into, which this isolated store cannot see.
+    const lint = lintMemoryStore(pluginCandidateStore(manifest.name, scope, storeRoot));
+    const identityErrors = lint.errors.filter((finding) => MEMORY_LINT_IDENTITY_RULES.has(finding.rule));
+    if (identityErrors.length > 0) {
+        const lines = identityErrors.map((f) => `- ${f.rule} at ${storeRelative(storeRoot, f.path)}: ${f.message}`);
+        throw general(`plugin "${manifest.name}" memory corpus at ${where} is incompatible with exact canonical identity:\n${lines.join('\n')}`, { issues: identityErrors, next: `Correct the package's memory documents, then retry — "${manifest.name}" was not activated.` });
+    }
+    return {
+        docs: lint.documents,
+        migrated: [...new Set([...run.wrote.consumers, ...run.wrote.identities])].map((path) => storeRelative(storeRoot, path)).sort(),
+        ...(ownership === 'linked' ? { linkedSource: realpathOrSelf(storeRoot) } : {}),
+    };
+}
 /** Validate a package candidate before it gains an active plugin path. The
  * candidate namespace shadows any installed declaration of the same name. */
-export async function assertPluginCandidateValid(manifest, root, scope, scopeRootPath, where, candidates) {
+export async function assertPluginCandidateValid(manifest, root, scope, scopeRootPath, where, candidates, ownership = 'package') {
     try {
         validatePluginManifestMemoryExtensions(manifest);
     }
@@ -195,6 +259,7 @@ export async function assertPluginCandidateValid(manifest, root, scope, scopeRoo
             throw general(`plugin memory document ${relative(root, file)} is invalid: ${issue.path}: ${issue.message}`);
         }
     }
+    return migratePluginMemory(manifest, root, scope, where, ownership);
 }
 function invocationTransport(bundle) {
     return { kind: 'http', endpoint: new URL(bundle.endpoint).origin, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) };
@@ -218,12 +283,13 @@ function writeStagedBundle(stagingRoot, manifest, bundle) {
     }
 }
 async function validateStagedBundle(name, scope, root, scopeRootPath, manifest) {
-    await assertPluginCandidateValid(manifest, root, scope, scopeRootPath, `${root}/.crouter-plugin/plugin.json`);
+    const memory = await assertPluginCandidateValid(manifest, root, scope, scopeRootPath, `${root}/.crouter-plugin/plugin.json`);
     const staged = { name, scope, root, manifest, enabled: true };
     const validation = validatePluginCommands(staged, new Set(SUBTREE_NAMES), await coreCommandPaths());
     if (validation.issues.length > 0) {
         throw invalidBundleError(`bundle staged package for "${name}" is invalid`, validation.issues);
     }
+    return memory;
 }
 function isSourceInstalled(plugin) {
     return plugin.sourceMarketplace !== undefined || isGitRepo(plugin.root) || isSymlink(plugin.root);
@@ -287,10 +353,11 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
     ensureDir(tmpRoot);
     ensureDir(join(scopeRootPath, 'plugins'));
     removePath(staging);
+    let memory;
     try {
         ensureDir(staging);
         writeStagedBundle(staging, manifest, validated.bundle);
-        await validateStagedBundle(name, scope, staging, scopeRootPath, manifest);
+        memory = await validateStagedBundle(name, scope, staging, scopeRootPath, manifest);
         let movedPrevious = false;
         if (pathExists(root)) {
             renameSync(root, previous);
@@ -322,7 +389,7 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
     const commands = await commandReport(name, scope);
     if (commands === undefined)
         throw general(`bundle plugin "${name}" has no staged command report`);
-    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, kinds: Object.keys(validated.bundle.kinds ?? {}).length, pageComponents: (validated.bundle.page_components ?? []).length, commands };
+    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, kinds: Object.keys(validated.bundle.kinds ?? {}).length, pageComponents: (validated.bundle.page_components ?? []).length, commands, ...(memory !== undefined ? { memory } : {}) };
 }
 async function installHttpPlugin(name, endpoint, authEnv, scope) {
     const source = validateHttpInstall(name, endpoint, authEnv);
@@ -451,7 +518,7 @@ async function installFromGit(source, ref, scope) {
         const manifest = readPluginManifest(staging);
         if (manifest === null)
             throw general(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${source}`);
-        await assertPluginCandidateValid(manifest, staging, scope, scopeRootPath, `${source}/.crouter-plugin/plugin.json`);
+        const memory = await assertPluginCandidateValid(manifest, staging, scope, scopeRootPath, `${source}/.crouter-plugin/plugin.json`);
         const finalDir = join(pDir, manifest.name);
         if (pathExists(finalDir))
             throw general(`plugin "${manifest.name}" is already installed at ${finalDir}`);
@@ -460,7 +527,7 @@ async function installFromGit(source, ref, scope) {
         updateConfig(scope, (cfg) => {
             cfg.plugins[manifest.name] = { enabled: true, version: manifest.version };
         });
-        return { name: manifest.name, scope, path: finalDir };
+        return { name: manifest.name, scope, path: finalDir, ...(memory !== undefined ? { memory } : {}) };
     }
     finally {
         removePath(staging);
@@ -473,7 +540,9 @@ async function installFromLocal(source, scope) {
         throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
     }
     const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
-    await assertPluginCandidateValid(manifest, sourcePath, scope, scopeRootPath, `${sourcePath}/.crouter-plugin/plugin.json`);
+    // The install keeps `sourcePath` as a live link, so the caller's own
+    // directory is the installed physical corpus and is converged in place.
+    const memory = await assertPluginCandidateValid(manifest, sourcePath, scope, scopeRootPath, `${sourcePath}/.crouter-plugin/plugin.json`, undefined, 'linked');
     ensureScopeInitialized(scope, scopeRootPath);
     const destDir = join(scopeRootPath, 'plugins', manifest.name);
     if (pathExists(destDir)) {
@@ -486,7 +555,7 @@ async function installFromLocal(source, scope) {
             version: manifest.version,
         };
     });
-    return { name: manifest.name, scope, path: destDir };
+    return { name: manifest.name, scope, path: destDir, ...(memory !== undefined ? { memory } : {}) };
 }
 /** Install one marketplace plugin into a scope. Exported so `sys setup` can
  *  install the default plugin set through the same path `pkg plugin install`
@@ -505,6 +574,7 @@ export async function installFromMarketplace(ref, scope) {
     if (pathExists(destPluginDir))
         throw general(`plugin "${ref.plugin}" is already installed at ${destPluginDir}`);
     let pluginManifest;
+    let memory;
     if (isMarketplaceRelativeSource(entry.source)) {
         const sourcePath = join(refreshed.marketplace.root, entry.source);
         if (!pathExists(sourcePath))
@@ -512,7 +582,9 @@ export async function installFromMarketplace(ref, scope) {
         const candidateManifest = readPluginManifest(sourcePath);
         if (candidateManifest === null)
             throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
-        await assertPluginCandidateValid(candidateManifest, sourcePath, scope, destRoot, `${sourcePath}/.crouter-plugin/plugin.json`);
+        // Linked to the marketplace checkout: that directory IS the installed
+        // corpus, so it is converged where it lies.
+        memory = await assertPluginCandidateValid(candidateManifest, sourcePath, scope, destRoot, `${sourcePath}/.crouter-plugin/plugin.json`, undefined, 'linked');
         linkOrCopy(sourcePath, destPluginDir);
         pluginManifest = candidateManifest;
     }
@@ -524,7 +596,7 @@ export async function installFromMarketplace(ref, scope) {
             const candidateManifest = readPluginManifest(staging);
             if (candidateManifest === null)
                 throw notFound(`plugin manifest not found at ${staging}/.crouter-plugin/plugin.json`);
-            await assertPluginCandidateValid(candidateManifest, staging, scope, destRoot, `${staging}/.crouter-plugin/plugin.json`);
+            memory = await assertPluginCandidateValid(candidateManifest, staging, scope, destRoot, `${staging}/.crouter-plugin/plugin.json`);
             ensureDir(join(destRoot, 'plugins'));
             renameSync(staging, destPluginDir);
             pluginManifest = candidateManifest;
@@ -543,7 +615,7 @@ export async function installFromMarketplace(ref, scope) {
             pluginCfg.version = version;
         cfg.plugins[ref.plugin] = pluginCfg;
     });
-    return { name: ref.plugin, scope, path: destPluginDir };
+    return { name: ref.plugin, scope, path: destPluginDir, ...(memory !== undefined ? { memory } : {}) };
 }
 async function updateGitPluginCandidate(plugin) {
     if (isSymlink(plugin.root)) {
@@ -551,16 +623,16 @@ async function updateGitPluginCandidate(plugin) {
         if (manifest === null)
             throw notFound(`plugin manifest not found at ${plugin.root}/.crouter-plugin/plugin.json`);
         const scopeRootPath = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
-        await assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
-        return { updated: false, sha: currentSha(plugin.root) ?? '', manifest };
+        const memory = await assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`, undefined, 'linked');
+        return { updated: false, sha: currentSha(plugin.root) ?? '', manifest, ...(memory !== undefined ? { memory } : {}) };
     }
     if (!isGitRepo(plugin.root)) {
         const manifest = readPluginManifest(plugin.root);
         if (manifest === null)
             throw notFound(`plugin manifest not found at ${plugin.root}/.crouter-plugin/plugin.json`);
         const scopeRootPath = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
-        await assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
-        return { updated: false, sha: '', manifest };
+        const memory = await assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
+        return { updated: false, sha: '', manifest, ...(memory !== undefined ? { memory } : {}) };
     }
     const remote = gitSync(['config', '--get', 'remote.origin.url'], plugin.root).stdout.trim();
     if (remote === '')
@@ -578,7 +650,7 @@ async function updateGitPluginCandidate(plugin) {
         const manifest = readPluginManifest(staging);
         if (manifest === null)
             throw notFound(`plugin manifest not found in update candidate: ${staging}/.crouter-plugin/plugin.json`);
-        await assertPluginCandidateValid(manifest, staging, plugin.scope, scopeRootPath, `${staging}/.crouter-plugin/plugin.json`);
+        const memory = await assertPluginCandidateValid(manifest, staging, plugin.scope, scopeRootPath, `${staging}/.crouter-plugin/plugin.json`);
         renameSync(plugin.root, previous);
         try {
             renameSync(staging, plugin.root);
@@ -589,7 +661,7 @@ async function updateGitPluginCandidate(plugin) {
         }
         removePath(previous);
         const sha = currentSha(plugin.root) ?? '';
-        return { updated: before !== sha, sha, manifest };
+        return { updated: before !== sha, sha, manifest, ...(memory !== undefined ? { memory } : {}) };
     }
     finally {
         removePath(staging);
@@ -601,7 +673,7 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
     const sourceInstalled = isSourceInstalled(plugin);
     if (!sourceInstalled && plugin.manifest.bundle !== undefined) {
         const replaced = await replaceBundlePlugin(plugin.name, plugin.manifest.bundle, plugin.scope, { enable: plugin.enabled });
-        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, kinds: replaced.kinds, pageComponents: replaced.pageComponents, commands: replaced.commands };
+        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, kinds: replaced.kinds, pageComponents: replaced.pageComponents, commands: replaced.commands, ...(replaced.memory !== undefined ? { memory: replaced.memory } : {}) };
     }
     if (plugin.manifest.transport?.kind === 'http' && !sourceInstalled)
         rejectLegacyHttpPlugin(plugin.name);
@@ -627,6 +699,7 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
         sha: candidate.sha,
         ...(commands !== undefined ? { commands } : {}),
         ...(hooks !== undefined ? { hooks } : {}),
+        ...(candidate.memory !== undefined ? { memory: candidate.memory } : {}),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
@@ -657,6 +730,7 @@ export const pluginInstall = defineLeaf({
             { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest. {mounts: string[] (accepted top-level command names now live for the next invocation), issues: object[] (typed validation issues that rejected a contribution — {code, path?, message, received, expected, next})}. Validated statically; commands are never executed.' },
             { name: 'hooks', type: 'object', required: false, constraint: 'Present only when the source plugin declares hooks. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[], trust: string}. Declarations, eligible targets, and replacement collisions are validated statically; hook executables are never run.' },
             { name: 'warnings', type: 'string[]', required: false, constraint: 'Advisory missing PATH executable requirements declared by the installed plugin. The install still succeeds and leaves the plugin enabled.' },
+            { name: 'memory', type: 'object', required: false, constraint: 'Present only when the plugin ships a memory store. {docs: integer (documents checked), migrated: string[] (store-relative documents rewritten to reach exact canonical identity), linkedSource?: string (the caller-owned directory converged in place, present only when the install keeps that directory as a live link)}.' },
         ],
         outputKind: 'object',
         effects: [
@@ -665,6 +739,7 @@ export const pluginInstall = defineLeaf({
             'If the plugin declares a command manifest, its commands go live on the next crtr invocation. Exec commands run trusted local code only when explicitly invoked; HTTP commands call their declared endpoint only when explicitly invoked.',
             'Source plugin hooks go live on the next crtr invocation. They run implicitly with caller authority, may receive normalized inputs and after results, may block or replace declared targets, and may transmit received data. Hook executables are never run during install or update validation.',
             'A plugin manifest `requires` declaration is checked against the PATH a node bash receives after install. Missing executables emit a warning with the declared install hint but never fail the install, disable the plugin, or remove its bare-binary contributions.',
+            'Before activation the candidate\u2019s memory corpus is migrated to exact canonical identity and refused if it cannot mount. A staged candidate is migrated in staging and rolls back with the package; a local path or marketplace-relative source stays a live link, so its own directory is rewritten in place, keeps that rewrite whether or not the install completes, and is named as `memory.linkedSource`. A refused corpus writes nothing and installs nothing.',
         ],
     },
     run: async (input) => {
@@ -775,11 +850,26 @@ export const pluginEnable = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'Plugin name.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the change was applied in.' },
             { name: 'enabled', type: 'boolean', required: true, constraint: 'Always true.' },
+            { name: 'memory', type: 'object', required: false, constraint: 'Present only when the plugin ships a memory store. {docs: integer (documents checked), migrated: string[] (store-relative documents rewritten to reach exact canonical identity), linkedSource?: string (the caller-owned directory converged in place, present only for a symlinked install)}.' },
         ],
         outputKind: 'object',
-        effects: ['Sets plugin enabled=true in config.json.'],
+        effects: [
+            'Validates the installed package before any config change: its memory corpus is migrated to exact canonical identity and refused if it cannot mount. A refusal leaves the plugin disabled.',
+            'Sets plugin enabled=true in config.json.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const target = resolvePluginConfigTarget(name, input['scope']);
+        if (target === null)
+            throw notFound(`plugin not found: ${name}`);
+        const manifest = readPluginManifest(target.root);
+        if (manifest === null)
+            throw notFound(`plugin manifest not found at ${target.root}/.crouter-plugin/plugin.json`);
+        const scopeRootPath = target.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
+        const memory = await assertPluginCandidateValid(manifest, target.root, target.scope, scopeRootPath, `${target.root}/.crouter-plugin/plugin.json`, undefined, isSymlink(target.root) ? 'linked' : 'package');
+        return { ...(await setPluginEnabled(input, true)), ...(memory !== undefined ? { memory } : {}) };
     },
-    run: async (input) => setPluginEnabled(input, true),
 });
 export const pluginDisable = defineLeaf({
     name: 'disable',
@@ -814,10 +904,13 @@ export const pluginUpdate = defineLeaf({
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, kinds?, pageComponents?, commands?, hooks?, warnings?, error?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, kinds is the declared kind-registry entry count, and pageComponents is the declared page-component registration count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}. hooks is present for source hook plugins: {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[], trust: string}; it is static and never executes hooks. warnings lists advisory PATH requirements that remain absent after update.' },
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, kinds?, pageComponents?, commands?, hooks?, memory?, warnings?, error?}. memory is present for a plugin shipping a memory store and reports the same corpus migration install performs: {docs, migrated, linkedSource?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier, docs is the written memory-document count, kinds is the declared kind-registry entry count, and pageComponents is the declared page-component registration count. sha is present for git updates. A bulk update reports and skips a failed archive plugin. commands is present for validated command plugins: {mounts: string[], issues: object[]}. hooks is present for source hook plugins: {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[], trust: string}; it is static and never executes hooks. warnings lists advisory PATH requirements that remain absent after update.' },
         ],
         outputKind: 'object',
-        effects: ['Archive plugins unconditionally re-fetch, validate, and replace their complete package; a named failure exits nonzero and preserves the prior package. Bulk update reports a failed archive plugin and continues. Source-installed plugins retain their source update, version, and last_updated behavior.'],
+        effects: [
+            'Archive plugins unconditionally re-fetch, validate, and replace their complete package; a named failure exits nonzero and preserves the prior package. Bulk update reports a failed archive plugin and continues. Source-installed plugins retain their source update, version, and last_updated behavior.',
+            'Each candidate passes the same pre-activation memory-corpus migration install performs, with the same linked-source rewrite semantics for a symlinked install.',
+        ],
     },
     run: async (input) => {
         const name = input['name'];

package/dist/commands/pkg/shared.d.ts

@@ -2,4 +2,12 @@ import type { Scope } from '../../types.js';
 export declare const GIT_URL_RE: RegExp;
 export declare function isGitUrl(arg: string): boolean;
 export declare function resolveInstallScope(scopeInput: string | undefined): Scope;
+/** The one installed copy an enable/disable acts on: the first scope in
+ *  precedence whose plugins dir holds `name`, disabled copies included. Enable
+ *  validates that exact copy before flipping its config, so both share this
+ *  resolution rather than each walking the scopes. */
+export declare function resolvePluginConfigTarget(name: string, scopeInput: string | undefined): {
+    scope: Scope;
+    root: string;
+} | null;
 export declare function setPluginEnabled(input: Record<string, unknown>, enabled: boolean): Promise<Record<string, unknown>>;

package/dist/commands/pkg/shared.js

@@ -21,9 +21,11 @@ export function resolveInstallScope(scopeInput) {
     // Default: project if available, else user
     return projectScopeRoot() !== null ? 'project' : 'user';
 }
-export async function setPluginEnabled(input, enabled) {
-    const name = input['name'];
-    const scopeInput = input['scope'];
+/** The one installed copy an enable/disable acts on: the first scope in
+ *  precedence whose plugins dir holds `name`, disabled copies included. Enable
+ *  validates that exact copy before flipping its config, so both share this
+ *  resolution rather than each walking the scopes. */
+export function resolvePluginConfigTarget(name, scopeInput) {
     let scopes;
     if (scopeInput !== undefined) {
         const resolved = resolveScopeArg(scopeInput);
@@ -34,28 +36,29 @@ export async function setPluginEnabled(input, enabled) {
     else {
         scopes = ['project', 'user'].filter((s) => s !== 'project' || projectScopeRoot() !== null);
     }
-    let actedScope;
     for (const scope of scopes) {
         const pDir = pluginsDir(scope);
         if (pDir === null)
             continue;
         const pluginDir = join(pDir, name);
-        if (!pathExists(pluginDir))
-            continue;
-        updateConfig(scope, (cfg) => {
-            const entry = cfg.plugins[name];
-            if (entry !== undefined) {
-                entry.enabled = enabled;
-            }
-            else {
-                cfg.plugins[name] = { enabled };
-            }
-        });
-        actedScope = scope;
-        break; // only act on first found scope
+        if (pathExists(pluginDir))
+            return { scope, root: pluginDir };
     }
-    if (actedScope === undefined) {
+    return null;
+}
+export async function setPluginEnabled(input, enabled) {
+    const name = input['name'];
+    const target = resolvePluginConfigTarget(name, input['scope']);
+    if (target === null)
         throw notFound(`plugin not found: ${name}`);
-    }
-    return { name, scope: actedScope, enabled };
+    updateConfig(target.scope, (cfg) => {
+        const entry = cfg.plugins[name];
+        if (entry !== undefined) {
+            entry.enabled = enabled;
+        }
+        else {
+            cfg.plugins[name] = { enabled };
+        }
+    });
+    return { name, scope: target.scope, enabled };
 }

package/dist/commands/surface-reload.d.ts

@@ -1,2 +1,7 @@
 import type { LeafDef } from '../core/command.js';
+/** The node a `crtr surface attach to <id>` command line targets. Panes opened
+ *  by a respawn path (the Markdown file-open bridge, the review companion) carry
+ *  a shell-quoted id, so the raw command line is not comparable to the canonical
+ *  one — the target node is. */
+export declare function attachTargetNode(command: string): string | undefined;
 export declare const surfaceReloadLeaf: LeafDef;

package/dist/commands/surface-reload.js

@@ -48,6 +48,14 @@ function paneTreeHasViewer(rootPid, nodeId) {
     }
     return false;
 }
+/** The node a `crtr surface attach to <id>` command line targets. Panes opened
+ *  by a respawn path (the Markdown file-open bridge, the review companion) carry
+ *  a shell-quoted id, so the raw command line is not comparable to the canonical
+ *  one — the target node is. */
+export function attachTargetNode(command) {
+    const match = /(?:^|\s)surface attach to\s+(?:'([^']*)'|"([^"]*)"|(\S+))/.exec(command);
+    return match?.[1] ?? match?.[2] ?? match?.[3];
+}
 export const surfaceReloadLeaf = defineLeaf({
     name: 'reload',
     description: 'respawn a viewer pane in place onto the current runtime generation',
@@ -94,7 +102,7 @@ export const surfaceReloadLeaf = defineLeaf({
         if (startCommand !== undefined && startCommand.startsWith('crtr surface attach ')) {
             // The start command must target the TAGGED node — a mismatch means the
             // tag is stale or the viewer belongs to another node; don't touch it.
-            if (startCommand !== viewerCommand) {
+            if (attachTargetNode(startCommand) !== nodeId) {
                 displayMessage('crtr: viewer/node mismatch in pane', pane);
                 throw new InputError({ error: 'no_viewer', message: `this pane's viewer command (${startCommand}) does not match its node tag (${nodeId})`, next: 'Pass --pane <pane-id> for a pane running `crtr surface attach to <node>`.' });
             }