@north-light/crouter 0.3.216 → 0.3.218

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

@@ -1,4 +1,4 @@
-import { join, resolve, isAbsolute, sep } from 'node:path';
+import { dirname, join, resolve, isAbsolute, relative, sep } from 'node:path';
 import { renameSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { defineLeaf } from '../../core/command.js';
@@ -7,9 +7,12 @@ import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../c
 import { 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, atomicWriteJson } from '../../core/fs-utils.js';
-import { clone, pull, deriveNameFromUrl, currentSha, gitSync, isGitRepo } from '../../core/git.js';
-import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
+import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink, readSymlinkTarget, atomicWriteJson, readText, 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 { lintSubstrateFrontmatter } from '../../core/substrate/frontmatter-validation.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
 import { normalizeEndpoint, validateEndpoint, validateHttpPluginTransport } from '../../core/command-plugins/endpoint.js';
 import { buildBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
@@ -118,6 +121,39 @@ function assertManifestPageComponentsValid(manifest, where) {
         throw general(`plugin manifest at ${where} declares an invalid page_components block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
     }
 }
+/** Validate a package candidate before it gains an active plugin path. The
+ * candidate namespace shadows any installed declaration of the same name. */
+function assertPluginCandidateValid(manifest, root, scope, scopeRootPath, where) {
+    try {
+        validatePluginManifestMemoryExtensions(manifest);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw general(`plugin manifest at ${where} declares invalid memory_extensions: ${detail}`);
+    }
+    assertManifestKindsValid(manifest, where);
+    assertManifestPageComponentsValid(manifest, where);
+    assertManifestBinValid(manifest, where);
+    assertManifestRequiresValid(manifest, where);
+    const memoryDir = join(root, 'memory');
+    const catalogDocPath = join(scopeRootPath, 'memory', '__plugin_candidate__.md');
+    for (const file of walkFiles(memoryDir, (name) => name.endsWith('.md'), (dir) => dir.startsWith('.'))) {
+        let frontmatter;
+        try {
+            frontmatter = parseFrontmatterGeneric(readText(file)).data;
+        }
+        catch (error) {
+            throw general(`plugin memory document ${relative(root, file)} has invalid YAML frontmatter: ${error instanceof Error ? error.message.split('\n')[0] : String(error)}`);
+        }
+        const substrateError = lintSubstrateFrontmatter(frontmatter);
+        if (substrateError !== null) {
+            throw general(`plugin memory document ${relative(root, file)} is invalid: ${substrateError}`);
+        }
+        for (const issue of validateMemoryExtensionValues(frontmatter?.['extensions'], memoryExtensionValidationCatalog({ scope, path: catalogDocPath }, { candidate: manifest }))) {
+            throw general(`plugin memory document ${relative(root, file)} is invalid: ${issue.path}: ${issue.message}`);
+        }
+    }
+}
 function invocationTransport(bundle) {
     return { kind: 'http', endpoint: new URL(bundle.endpoint).origin, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) };
 }
@@ -139,7 +175,8 @@ function writeStagedBundle(stagingRoot, manifest, bundle) {
         writeFileSync(target, document.bytes);
     }
 }
-async function validateStagedBundle(name, scope, root, manifest) {
+async function validateStagedBundle(name, scope, root, scopeRootPath, manifest) {
+    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) {
@@ -198,6 +235,7 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
         // copy is what makes the components authorable — and dropping it on a
         // later archive that no longer declares them is what retires them.
         ...(validated.bundle.page_components !== undefined ? { page_components: validated.bundle.page_components } : {}),
+        ...(validated.bundle.memory_extensions !== undefined ? { memory_extensions: validated.bundle.memory_extensions } : {}),
     };
     const tmpRoot = join(scopeRootPath, 'tmp');
     const staging = join(tmpRoot, `${name}.${process.pid}`);
@@ -210,7 +248,7 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
     try {
         ensureDir(staging);
         writeStagedBundle(staging, manifest, validated.bundle);
-        await validateStagedBundle(name, scope, staging, manifest);
+        await validateStagedBundle(name, scope, staging, scopeRootPath, manifest);
         let movedPrevious = false;
         if (pathExists(root)) {
             renameSync(root, previous);
@@ -265,21 +303,6 @@ function classifyInstallRef(raw) {
 function isMarketplaceRelativeSource(source) {
     return source.startsWith('./') || source.startsWith('../') || (!isAbsolute(source) && !isGitUrl(source));
 }
-function pullGitCheckout(root, label, opts) {
-    const shaBefore = currentSha(root);
-    if (!isGitRepo(root)) {
-        return { updated: false, sha: shaBefore ?? '' };
-    }
-    const res = pull(root);
-    if (res.status !== 0) {
-        if (opts.strict) {
-            throw general(`git pull failed for ${label}: ${res.stderr.trim()}`);
-        }
-        return { updated: false, sha: shaBefore ?? '' };
-    }
-    const shaAfter = currentSha(root);
-    return { updated: shaBefore !== shaAfter, sha: shaAfter ?? '' };
-}
 function refreshMarketplace(name, cache, opts) {
     const cached = cache.get(name);
     if (cached !== undefined)
@@ -290,28 +313,70 @@ function refreshMarketplace(name, cache, opts) {
             throw notFound(`marketplace not found: ${name}`);
         return null;
     }
-    const pullSummary = pullGitCheckout(marketplace.root, `marketplace "${name}"`, opts);
-    const freshManifest = readMarketplaceManifest(marketplace.root);
-    if (freshManifest === null) {
-        throw notFound(`marketplace manifest not found after refresh: ${marketplace.root}/.crouter-marketplace/marketplace.json`);
-    }
-    updateState(marketplace.scope, (s) => {
-        if (s.marketplaces[name] === undefined) {
-            s.marketplaces[name] = {};
+    const activeManifest = readMarketplaceManifest(marketplace.root);
+    if (activeManifest === null)
+        throw notFound(`marketplace manifest not found: ${marketplace.root}/.crouter-marketplace/marketplace.json`);
+    if (!isGitRepo(marketplace.root)) {
+        const unchanged = { marketplace, manifest: activeManifest, pull: { updated: false, sha: currentSha(marketplace.root) ?? '' } };
+        cache.set(name, unchanged);
+        return unchanged;
+    }
+    const activeSha = currentSha(marketplace.root);
+    const staging = join(dirname(marketplace.root), `.${name}.${process.pid}.${Date.now()}.candidate`);
+    const previous = `${staging}.previous`;
+    try {
+        clone(marketplace.url, staging, { ref: marketplace.ref, depth: 1 });
+        const manifest = readMarketplaceManifest(staging);
+        if (manifest === null)
+            throw notFound(`marketplace manifest not found in candidate checkout: ${staging}/.crouter-marketplace/marketplace.json`);
+        const observers = listAllPlugins().filter((plugin) => plugin.sourceMarketplace === name && isSymlink(plugin.root));
+        for (const plugin of observers) {
+            const entry = manifest.plugins.find((candidate) => candidate.name === plugin.name);
+            if (entry === undefined || !isMarketplaceRelativeSource(entry.source)) {
+                throw general(`marketplace candidate removes relative-source plugin "${plugin.name}" while it is installed`);
+            }
+            const symlinkTarget = readSymlinkTarget(plugin.root);
+            if (symlinkTarget === null)
+                throw general(`installed marketplace plugin "${plugin.name}" has no readable symlink target`);
+            const observedRelativeSource = relative(marketplace.root, resolve(dirname(plugin.root), symlinkTarget));
+            const candidateRoot = resolve(staging, entry.source);
+            if (candidateRoot !== resolve(staging, observedRelativeSource)) {
+                throw general(`marketplace candidate moves installed relative-source plugin "${plugin.name}" from ${observedRelativeSource} to ${entry.source}`);
+            }
+            if (!pathExists(candidateRoot))
+                throw notFound(`marketplace candidate source path does not exist for plugin "${plugin.name}": ${candidateRoot}`);
+            const candidateManifest = readPluginManifest(candidateRoot);
+            if (candidateManifest === null)
+                throw notFound(`plugin manifest not found in marketplace candidate: ${candidateRoot}/.crouter-plugin/plugin.json`);
+            const pluginScopeRoot = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
+            assertPluginCandidateValid(candidateManifest, candidateRoot, plugin.scope, pluginScopeRoot, `${candidateRoot}/.crouter-plugin/plugin.json`);
         }
-        s.marketplaces[name].last_updated = nowIso();
-    });
-    const refreshed = { marketplace, manifest: freshManifest, pull: pullSummary };
-    cache.set(name, refreshed);
-    return refreshed;
-}
-/** Restore a source checkout after an updated manifest fails its install-time
- *  gate. `--merge` returns it to the previous commit without discarding local
- *  changes unrelated to the pull. */
-function restoreSourceCheckout(root, previousSha) {
-    const restored = gitSync(['reset', '--merge', previousSha], root);
-    if (restored.status !== 0) {
-        throw general(`updated plugin manifest was rejected, but crouter could not restore the previous checkout at ${root}: ${restored.stderr.trim()}`);
+        renameSync(marketplace.root, previous);
+        try {
+            renameSync(staging, marketplace.root);
+        }
+        catch (error) {
+            renameSync(previous, marketplace.root);
+            throw error;
+        }
+        removePath(previous);
+        for (const plugin of observers) {
+            const entry = manifest.plugins.find((candidate) => candidate.name === plugin.name);
+            updatePluginVersion(plugin.scope, plugin.name, entry.version ?? plugin.manifest.version);
+        }
+        updateState(marketplace.scope, (s) => {
+            if (s.marketplaces[name] === undefined)
+                s.marketplaces[name] = {};
+            s.marketplaces[name].last_updated = nowIso();
+        });
+        const refreshed = { marketplace, manifest, pull: { updated: activeSha !== currentSha(marketplace.root), sha: currentSha(marketplace.root) ?? '' } };
+        cache.set(name, refreshed);
+        return refreshed;
+    }
+    finally {
+        removePath(staging);
+        if (pathExists(previous) && !pathExists(marketplace.root))
+            renameSync(previous, marketplace.root);
     }
 }
 function updatePluginVersion(scope, name, version) {
@@ -336,46 +401,28 @@ function installFromGit(source, ref, scope) {
     const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
     ensureScopeInitialized(scope, scopeRootPath);
     const pDir = join(scopeRootPath, 'plugins');
-    ensureDir(pDir);
     const tempName = deriveNameFromUrl(source);
-    const tempDir = join(pDir, tempName);
-    if (pathExists(tempDir)) {
-        throw general(`plugin directory already exists: ${tempDir}\nRemove the existing plugin first with \`pkg plugin remove ${tempName}\`.`);
-    }
-    clone(source, tempDir, { ref: ref !== undefined ? ref : undefined, depth: 1 });
-    const manifest = readPluginManifest(tempDir);
-    if (manifest === null) {
-        removePath(tempDir);
-        throw general(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${source}`);
-    }
+    const staging = join(scopeRootPath, 'tmp', `${tempName}.${process.pid}.${Date.now()}`);
+    ensureDir(join(scopeRootPath, 'tmp'));
     try {
-        assertManifestKindsValid(manifest, `${source}/.crouter-plugin/plugin.json`);
-        assertManifestPageComponentsValid(manifest, `${source}/.crouter-plugin/plugin.json`);
-        assertManifestBinValid(manifest, `${source}/.crouter-plugin/plugin.json`);
-        assertManifestRequiresValid(manifest, `${source}/.crouter-plugin/plugin.json`);
+        clone(source, staging, { ref, depth: 1 });
+        const manifest = readPluginManifest(staging);
+        if (manifest === null)
+            throw general(`cloned repo does not contain a valid .crouter-plugin/plugin.json: ${source}`);
+        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}`);
+        ensureDir(pDir);
+        renameSync(staging, finalDir);
+        updateConfig(scope, (cfg) => {
+            cfg.plugins[manifest.name] = { enabled: true, version: manifest.version };
+        });
+        return { name: manifest.name, scope, path: finalDir };
     }
-    catch (error) {
-        removePath(tempDir);
-        throw error;
-    }
-    const finalName = manifest.name;
-    let finalDir = tempDir;
-    if (finalName !== tempName) {
-        const candidateDir = join(pDir, finalName);
-        if (pathExists(candidateDir)) {
-            removePath(tempDir);
-            throw general(`plugin "${finalName}" is already installed at ${candidateDir}`);
-        }
-        renameSync(tempDir, candidateDir);
-        finalDir = candidateDir;
+    finally {
+        removePath(staging);
     }
-    updateConfig(scope, (cfg) => {
-        cfg.plugins[finalName] = {
-            enabled: true,
-            version: manifest.version,
-        };
-    });
-    return { name: finalName, scope, path: finalDir };
 }
 function installFromLocal(source, scope) {
     const sourcePath = resolve(source);
@@ -383,11 +430,8 @@ function installFromLocal(source, scope) {
     if (manifest === null) {
         throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
     }
-    assertManifestKindsValid(manifest, `${sourcePath}/.crouter-plugin/plugin.json`);
-    assertManifestPageComponentsValid(manifest, `${sourcePath}/.crouter-plugin/plugin.json`);
-    assertManifestBinValid(manifest, `${sourcePath}/.crouter-plugin/plugin.json`);
-    assertManifestRequiresValid(manifest, `${sourcePath}/.crouter-plugin/plugin.json`);
     const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
+    assertPluginCandidateValid(manifest, sourcePath, scope, scopeRootPath, `${sourcePath}/.crouter-plugin/plugin.json`);
     ensureScopeInitialized(scope, scopeRootPath);
     const destDir = join(scopeRootPath, 'plugins', manifest.name);
     if (pathExists(destDir)) {
@@ -416,33 +460,36 @@ export function installFromMarketplace(ref, scope) {
     const destRoot = requireScopeRoot(scope);
     ensureScopeInitialized(scope, destRoot);
     const destPluginDir = join(destRoot, 'plugins', ref.plugin);
+    if (pathExists(destPluginDir))
+        throw general(`plugin "${ref.plugin}" is already installed at ${destPluginDir}`);
+    let pluginManifest;
     if (isMarketplaceRelativeSource(entry.source)) {
         const sourcePath = join(refreshed.marketplace.root, entry.source);
-        if (!pathExists(sourcePath)) {
+        if (!pathExists(sourcePath))
             throw notFound(`plugin source path does not exist: ${sourcePath}`);
-        }
+        const candidateManifest = readPluginManifest(sourcePath);
+        if (candidateManifest === null)
+            throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
+        assertPluginCandidateValid(candidateManifest, sourcePath, scope, destRoot, `${sourcePath}/.crouter-plugin/plugin.json`);
         linkOrCopy(sourcePath, destPluginDir);
+        pluginManifest = candidateManifest;
     }
     else {
-        if (pathExists(destPluginDir)) {
-            removePath(destPluginDir);
+        const staging = join(destRoot, 'tmp', `${ref.plugin}.${process.pid}.${Date.now()}`);
+        ensureDir(join(destRoot, 'tmp'));
+        try {
+            clone(entry.source, staging, { depth: 1 });
+            const candidateManifest = readPluginManifest(staging);
+            if (candidateManifest === null)
+                throw notFound(`plugin manifest not found at ${staging}/.crouter-plugin/plugin.json`);
+            assertPluginCandidateValid(candidateManifest, staging, scope, destRoot, `${staging}/.crouter-plugin/plugin.json`);
+            ensureDir(join(destRoot, 'plugins'));
+            renameSync(staging, destPluginDir);
+            pluginManifest = candidateManifest;
+        }
+        finally {
+            removePath(staging);
         }
-        clone(entry.source, destPluginDir, { depth: 1 });
-    }
-    const pluginManifest = readPluginManifest(destPluginDir);
-    if (pluginManifest === null) {
-        removePath(destPluginDir);
-        throw notFound(`plugin manifest not found at ${destPluginDir}/.crouter-plugin/plugin.json`);
-    }
-    try {
-        assertManifestKindsValid(pluginManifest, `${destPluginDir}/.crouter-plugin/plugin.json`);
-        assertManifestPageComponentsValid(pluginManifest, `${destPluginDir}/.crouter-plugin/plugin.json`);
-        assertManifestBinValid(pluginManifest, `${destPluginDir}/.crouter-plugin/plugin.json`);
-        assertManifestRequiresValid(pluginManifest, `${destPluginDir}/.crouter-plugin/plugin.json`);
-    }
-    catch (error) {
-        removePath(destPluginDir);
-        throw error;
     }
     const version = entry.version ?? pluginManifest.version;
     updateConfig(scope, (cfg) => {
@@ -456,6 +503,58 @@ export function installFromMarketplace(ref, scope) {
     });
     return { name: ref.plugin, scope, path: destPluginDir };
 }
+function updateGitPluginCandidate(plugin) {
+    if (isSymlink(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();
+        assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
+        return { updated: false, sha: currentSha(plugin.root) ?? '', manifest };
+    }
+    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();
+        assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
+        return { updated: false, sha: '', manifest };
+    }
+    const remote = gitSync(['config', '--get', 'remote.origin.url'], plugin.root).stdout.trim();
+    if (remote === '')
+        throw general(`plugin "${plugin.name}" has no origin remote to stage an update from`);
+    const branch = gitSync(['symbolic-ref', '--short', 'HEAD'], plugin.root).stdout.trim();
+    if (branch === '')
+        throw general(`plugin "${plugin.name}" is detached at its installed revision and has no tracked branch to update`);
+    const scopeRootPath = plugin.scope === 'project' ? requireScopeRoot('project') : userScopeRoot();
+    const staging = join(scopeRootPath, 'tmp', `${plugin.name}.${process.pid}.${Date.now()}.candidate`);
+    const previous = `${staging}.previous`;
+    const before = currentSha(plugin.root);
+    ensureDir(join(scopeRootPath, 'tmp'));
+    try {
+        clone(remote, staging, { ref: branch, depth: 1 });
+        const manifest = readPluginManifest(staging);
+        if (manifest === null)
+            throw notFound(`plugin manifest not found in update candidate: ${staging}/.crouter-plugin/plugin.json`);
+        assertPluginCandidateValid(manifest, staging, plugin.scope, scopeRootPath, `${staging}/.crouter-plugin/plugin.json`);
+        renameSync(plugin.root, previous);
+        try {
+            renameSync(staging, plugin.root);
+        }
+        catch (error) {
+            renameSync(previous, plugin.root);
+            throw error;
+        }
+        removePath(previous);
+        const sha = currentSha(plugin.root) ?? '';
+        return { updated: before !== sha, sha, manifest };
+    }
+    finally {
+        removePath(staging);
+        if (pathExists(previous) && !pathExists(plugin.root))
+            renameSync(previous, plugin.root);
+    }
+}
 async function updateOnePlugin(plugin, marketplaceCache, opts) {
     const sourceInstalled = isSourceInstalled(plugin);
     if (!sourceInstalled && plugin.manifest.bundle !== undefined) {
@@ -464,63 +563,25 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
     }
     if (plugin.manifest.transport?.kind === 'http' && !sourceInstalled)
         rejectLegacyHttpPlugin(plugin.name);
-    const previousSha = currentSha(plugin.root);
-    let contentUpdate = { updated: false, sha: currentSha(plugin.root) ?? '' };
     let marketplaceVersion;
+    let marketplaceUpdated = false;
     if (plugin.sourceMarketplace !== undefined) {
         const refreshed = refreshMarketplace(plugin.sourceMarketplace, marketplaceCache, opts);
         if (refreshed !== null) {
-            const entry = refreshed.manifest.plugins.find((p) => p.name === plugin.name);
+            const entry = refreshed.manifest.plugins.find((candidate) => candidate.name === plugin.name);
             marketplaceVersion = entry?.version;
-            if (isSymlink(plugin.root)) {
-                const shaAfter = currentSha(plugin.root);
-                contentUpdate = { updated: refreshed.pull.updated, sha: shaAfter ?? refreshed.pull.sha };
-            }
-            else {
-                contentUpdate = pullGitCheckout(plugin.root, `plugin "${plugin.name}"`, opts);
-            }
-        }
-    }
-    else {
-        contentUpdate = pullGitCheckout(plugin.root, `plugin "${plugin.name}"`, opts);
-    }
-    const manifest = readPluginManifest(plugin.root);
-    try {
-        if (manifest === null) {
-            throw general(`plugin manifest not found after updating ${plugin.root}: ${plugin.root}/.crouter-plugin/plugin.json`);
-        }
-        assertManifestKindsValid(manifest, `${plugin.root}/.crouter-plugin/plugin.json`);
-        assertManifestPageComponentsValid(manifest, `${plugin.root}/.crouter-plugin/plugin.json`);
-        assertManifestBinValid(manifest, `${plugin.root}/.crouter-plugin/plugin.json`);
-        assertManifestRequiresValid(manifest, `${plugin.root}/.crouter-plugin/plugin.json`);
-    }
-    catch (error) {
-        if (contentUpdate.updated && previousSha !== null && isGitRepo(plugin.root)) {
-            restoreSourceCheckout(plugin.root, previousSha);
-            // Marketplace plugins are symlinks into the shared marketplace checkout.
-            // Its cached manifest and pull state must move back with that checkout so
-            // later entries in this bulk update neither see the rejected revision nor
-            // record its versions as accepted.
-            if (plugin.sourceMarketplace !== undefined) {
-                const cached = marketplaceCache.get(plugin.sourceMarketplace);
-                if (cached !== undefined) {
-                    marketplaceCache.set(plugin.sourceMarketplace, {
-                        ...cached,
-                        pull: { updated: false, sha: currentSha(cached.marketplace.root) ?? '' },
-                    });
-                }
-            }
+            marketplaceUpdated = refreshed.pull.updated;
         }
-        throw error;
     }
-    updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? manifest.version);
+    const candidate = updateGitPluginCandidate(plugin);
+    updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? candidate.manifest.version);
     const commands = await commandReport(plugin.name, plugin.scope);
-    const warnings = missingRequirementWarnings(manifest);
+    const warnings = missingRequirementWarnings(candidate.manifest);
     return {
         name: plugin.name,
         ...(plugin.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
-        updated: contentUpdate.updated,
-        sha: contentUpdate.sha,
+        updated: marketplaceUpdated || candidate.updated,
+        sha: candidate.sha,
         ...(commands !== undefined ? { commands } : {}),
         ...(warnings.length > 0 ? { warnings } : {}),
     };

package/dist/core/__tests__/human-cancel-guard.test.js

@@ -13,7 +13,7 @@ import { createNode } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
 import { nodeDir } from '../canvas/paths.js';
 import { atomicWriteJson, bindTicketReplyRoute, pageManifestPath } from '../human/convention.js';
-import { cancelTicket } from '../human/tickets.js';
+import { cancelTicket, readTicketResult } from '../human/tickets.js';
 import { humanCancel } from '../../commands/human/queue.js';
 import { createApiServer } from '../../daemon/api/server.js';
 import { apiSocketPath } from '../canvas/paths.js';
@@ -46,7 +46,7 @@ function node(id) {
 }
 /** Publish a reply-bearing page ticket in the bridge node's directory, exactly as
  *  `human send` does: reply route first, then the page manifest. */
-function publishTicket(id) {
+function publishTicket(id, slots = []) {
     const dir = nodeDir(id);
     mkdirSync(dir, { recursive: true });
     bindTicketReplyRoute(dir, id);
@@ -58,7 +58,7 @@ function publishTicket(id) {
         delivery: { placement: 'inline', inbox: true, reply: true },
         document: 'page.tsx',
         steps: 1,
-        slots: [],
+        slots,
     });
 }
 before(() => {
@@ -80,13 +80,31 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
-test('cancel on an already-canceled ticket is a no-op, never throws on the finalize', async () => {
-    const id = 'canceledJob';
-    createNode(node(id));
-    publishTicket(id);
-    cancelTicket(nodeDir(id), { actor: 'human' }); // settled by the first cancel
-    const res = (await humanCancel.run({ ticket_id: id }));
-    assert.equal(res['canceled'], false);
-    assert.equal(res['reason'], 'already_resolved');
-    assert.equal(res['ticket_id'], id);
+test('cancel accepts newer page config and treats an already-canceled ticket as a no-op', async () => {
+    const newerId = 'newerPage';
+    createNode(node(newerId));
+    publishTicket(newerId, [{
+            id: 'decision',
+            kind: 'options',
+            step: 0,
+            config: {
+                label: 'Decision',
+                body: 'Choose one.',
+                options: [{ id: 'yes', label: 'Yes' }],
+                mode: 'single',
+                futureField: true,
+            },
+        }]);
+    const canceled = (await humanCancel.run({ ticket_id: newerId }));
+    assert.equal(canceled['canceled'], true);
+    assert.equal(canceled['ticket_id'], newerId);
+    assert.equal(readTicketResult(nodeDir(newerId))?.kind, 'canceled');
+    const settledId = 'canceledJob';
+    createNode(node(settledId));
+    publishTicket(settledId);
+    cancelTicket(nodeDir(settledId), { actor: 'human' });
+    const settled = (await humanCancel.run({ ticket_id: settledId }));
+    assert.equal(settled['canceled'], false);
+    assert.equal(settled['reason'], 'already_resolved');
+    assert.equal(settled['ticket_id'], settledId);
 });

package/dist/core/bash-jobs.d.ts

@@ -77,11 +77,8 @@ export declare function jobStartedAtMs(jobId: string): number | undefined;
  * notice, the `node bash background` result/toast, and the attach cockpit)
  * shows it: `<60s -> "12s"`; `60s-59m -> "3m 40s"`; `>=60m -> "1h 04m"`. */
 export declare function formatBashElapsed(ms: number): string;
-/** The command line worth SHOWING for a job. `cmd.sh` opens with the harness's
- * injected environment preamble (`export CRTR_PREVIEW_RESULT_PATH=…`), so its
- * literal first line names no command at all: skip leading assignment lines and
- * return the first real one, whitespace-collapsed to a single line. A job whose
- * command is nothing but assignments falls back to its first non-empty line. */
+/** The command line worth SHOWING for a job: the first non-empty line of
+ * `cmd.sh`, whitespace-collapsed to one line. */
 export declare function bashJobCommandLine(command: string): string;
 export interface BashJobStatus {
     jobId: string;

package/dist/core/bash-jobs.js

@@ -189,15 +189,11 @@ export function formatBashElapsed(ms) {
     const minutes = totalMinutes % 60;
     return `${hours}h ${String(minutes).padStart(2, '0')}m`;
 }
-/** The command line worth SHOWING for a job. `cmd.sh` opens with the harness's
- * injected environment preamble (`export CRTR_PREVIEW_RESULT_PATH=…`), so its
- * literal first line names no command at all: skip leading assignment lines and
- * return the first real one, whitespace-collapsed to a single line. A job whose
- * command is nothing but assignments falls back to its first non-empty line. */
+/** The command line worth SHOWING for a job: the first non-empty line of
+ * `cmd.sh`, whitespace-collapsed to one line. */
 export function bashJobCommandLine(command) {
-    const lines = command.split('\n').map((line) => line.trim()).filter((line) => line !== '');
-    const real = lines.find((line) => !/^(export\s+)?[A-Za-z_][A-Za-z0-9_]*=/.test(line));
-    return (real ?? lines[0] ?? '').replace(/\s+/g, ' ');
+    const first = command.split('\n').map((line) => line.trim()).find((line) => line !== '');
+    return (first ?? '').replace(/\s+/g, ' ');
 }
 /** Every live backgrounded bash job for this node — job.bg present, job.exit
  * absent — whether handed off by the menu, the valve deadline, or broker

package/dist/core/command-plugins/bundle.d.ts

@@ -1,5 +1,5 @@
 import { type ValidatedCommandManifest } from '../command-manifests/manifest.js';
-import type { KindConfig, PageComponentRegistration } from '../../types.js';
+import type { KindConfig, MemoryExtensionDeclarations, PageComponentRegistration } from '../../types.js';
 export interface BundleIssue {
     code: string;
     path?: string;
@@ -20,6 +20,9 @@ export interface ValidatedBundle {
      *  manifest, where `resolvePageComponents` reads it — see
      *  `PluginManifest.page_components`. */
     page_components?: PageComponentRegistration[];
+    /** Plugin-owned memory metadata declarations copied into the synthesized
+     * installed manifest alongside the archive's memory documents. */
+    memory_extensions?: MemoryExtensionDeclarations;
     commands: ValidatedCommandManifest;
     commandsBytes: Uint8Array;
     directories: ReadonlyArray<{

package/dist/core/command-plugins/bundle.js

@@ -2,6 +2,7 @@ import { Parser } from 'tar';
 import { validateCommandManifest } from '../command-manifests/manifest.js';
 import { invalidPluginKindsReasons } from '../config.js';
 import { invalidPageComponentsReasons, normalizePageComponents } from '../human/page-catalog.js';
+import { validateMemoryExtensionDeclarations } from '../memory/extensions.js';
 function issue(code, message, received, expected, next, path) {
     return { code, message, received, expected, next, ...(path !== undefined ? { path } : {}) };
 }
@@ -144,10 +145,10 @@ function parseBundleMetadata(bytes) {
         };
     }
     const record = raw;
-    const unknownKeys = Object.keys(record).filter((key) => key !== 'bundleVersion' && key !== 'kinds' && key !== 'page_components');
+    const unknownKeys = Object.keys(record).filter((key) => key !== 'bundleVersion' && key !== 'kinds' && key !== 'page_components' && key !== 'memory_extensions');
     if (record['bundleVersion'] !== 1 || unknownKeys.length > 0) {
         return {
-            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most kinds and page_components blocks', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optionally kinds and page_components', 'Set bundle.json to {"bundleVersion":1} plus an optional kinds object and page_components array.', 'bundle.json'),
+            issue: bundleInvalid('bundle.json must contain bundleVersion 1 and at most kinds, page_components, and memory_extensions blocks', JSON.stringify(raw), 'an object with bundleVersion set to 1 and optional kinds, page_components, and memory_extensions', 'Set bundle.json to {"bundleVersion":1} plus optional contribution blocks.', 'bundle.json'),
         };
     }
     // Install-time strictness: a bad block fails the install loudly here, because
@@ -169,9 +170,21 @@ function parseBundleMetadata(bytes) {
             };
         }
     }
+    let memoryExtensions;
+    if (record['memory_extensions'] !== undefined) {
+        try {
+            memoryExtensions = validateMemoryExtensionDeclarations(record['memory_extensions']);
+        }
+        catch (error) {
+            return {
+                issue: bundleInvalid('bundle.json memory_extensions block is invalid', error instanceof Error ? error.message : String(error), 'a valid memory_extensions declaration object', 'Fix the memory_extensions declarations in bundle.json.', 'bundle.json'),
+            };
+        }
+    }
     return {
         ...(record['kinds'] !== undefined ? { kinds: record['kinds'] } : {}),
         ...(record['page_components'] !== undefined ? { page_components: normalizePageComponents(record['page_components']) } : {}),
+        ...(memoryExtensions !== undefined ? { memory_extensions: memoryExtensions } : {}),
     };
 }
 function parseCommands(bytes, reservedCoreNames, coreCommandPaths) {
@@ -219,6 +232,7 @@ export async function validatePluginBundle(archive, options) {
             bundleVersion: 1,
             ...(metadata.kinds !== undefined ? { kinds: metadata.kinds } : {}),
             ...(metadata.page_components !== undefined ? { page_components: metadata.page_components } : {}),
+            ...(metadata.memory_extensions !== undefined ? { memory_extensions: metadata.memory_extensions } : {}),
             commands: commandValidation.commands,
             commandsBytes: commands.bytes,
             directories: parsed.members