@north-light/crouter 0.3.220 → 0.3.222

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

@@ -1,13 +1,14 @@
-import { join } from 'node:path';
+import { dirname, join, relative, resolve } from 'node:path';
 import { renameSync } from 'node:fs';
 import { defineLeaf } from '../../core/command.js';
-import { notFound } from '../../core/errors.js';
+import { general, notFound } from '../../core/errors.js';
 import { listAllMarketplaces, listAllPlugins, findMarketplaceByName } from '../../core/resolver.js';
 import { resolveScopeArg, requireScopeRoot } from '../../core/scope.js';
 import { updateConfig, updateState, ensureScopeInitialized, readConfig } from '../../core/config.js';
-import { pathExists, ensureDir, removePath, isSymlink, nowIso } from '../../core/fs-utils.js';
-import { clone, pull, deriveNameFromUrl, currentSha, isGitRepo } from '../../core/git.js';
-import { readMarketplaceManifest } from '../../core/manifest.js';
+import { pathExists, ensureDir, removePath, isSymlink, nowIso, readSymlinkTarget } from '../../core/fs-utils.js';
+import { clone, deriveNameFromUrl, currentSha, gitSync, isGitRepo } from '../../core/git.js';
+import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
+import { assertPluginCandidateValid, isMarketplaceRelativeSource } from './plugin-manage.js';
 import { resolveInstallScope } from './shared.js';
 /** Clone a marketplace repo into `scope` and register it in that scope's
  *  config. Shared by the `pkg market add` leaf and `crtr sys setup`, which
@@ -146,13 +147,158 @@ export const marketRemove = defineLeaf({
         return { name, removed: true };
     },
 });
+function stageGitRoot(url, ref, active, candidate) {
+    const result = gitSync(['clone', '--depth', '1', '--branch', ref, url, candidate]);
+    if (result.status !== 0) {
+        removePath(candidate);
+        return undefined;
+    }
+    return { active, candidate, previous: `${candidate}.previous` };
+}
+function activateStagedRoots(staged) {
+    const moved = [];
+    const activated = [];
+    try {
+        for (const root of staged) {
+            if (pathExists(root.previous))
+                throw general(`prior staged backup remains at ${root.previous}`);
+            renameSync(root.active, root.previous);
+            moved.push(root);
+        }
+        for (const root of staged) {
+            renameSync(root.candidate, root.active);
+            activated.push(root);
+        }
+    }
+    catch (error) {
+        for (const root of [...activated].reverse())
+            renameSync(root.active, root.candidate);
+        for (const root of [...moved].reverse())
+            renameSync(root.previous, root.active);
+        throw error;
+    }
+    for (const root of staged)
+        removePath(root.previous);
+}
+function candidatePlugin(plugin, root, manifest) {
+    return { plugin: { ...plugin, root, manifest }, scopeRoot: dirname(dirname(plugin.root)) };
+}
+async function updateMarketplaceTarget(target) {
+    const activeSha = currentSha(target.root) ?? '';
+    const sourcedPlugins = listAllPlugins().filter((plugin) => plugin.scope === target.scope && plugin.sourceMarketplace === target.name);
+    const stagedRoots = [];
+    const cleanupRoots = [];
+    let manifest;
+    let marketplaceCandidate;
+    const candidates = [];
+    try {
+        if (isGitRepo(target.root)) {
+            const candidate = join(dirname(target.root), `.${target.name}.${process.pid}.${Date.now()}.candidate`);
+            marketplaceCandidate = stageGitRoot(target.url, target.ref, target.root, candidate);
+            if (marketplaceCandidate !== undefined) {
+                cleanupRoots.push(candidate);
+                const candidateManifest = readMarketplaceManifest(candidate);
+                if (candidateManifest === null)
+                    throw notFound(`marketplace manifest not found in candidate checkout: ${candidate}/.crouter-marketplace/marketplace.json`);
+                manifest = candidateManifest;
+                if (currentSha(candidate) !== activeSha)
+                    stagedRoots.push(marketplaceCandidate);
+            }
+            else {
+                const activeManifest = readMarketplaceManifest(target.root);
+                if (activeManifest === null)
+                    throw notFound(`marketplace manifest not found after refresh: ${target.root}/.crouter-marketplace/marketplace.json`);
+                manifest = activeManifest;
+            }
+        }
+        else {
+            const activeManifest = readMarketplaceManifest(target.root);
+            if (activeManifest === null)
+                throw notFound(`marketplace manifest not found after refresh: ${target.root}/.crouter-marketplace/marketplace.json`);
+            manifest = activeManifest;
+        }
+        for (const plugin of sourcedPlugins) {
+            if (isSymlink(plugin.root)) {
+                if (marketplaceCandidate === undefined)
+                    continue;
+                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 observedSource = relative(target.root, resolve(dirname(plugin.root), symlinkTarget));
+                const candidateRoot = resolve(marketplaceCandidate.candidate, entry.source);
+                if (candidateRoot !== resolve(marketplaceCandidate.candidate, observedSource)) {
+                    throw general(`marketplace candidate moves installed relative-source plugin "${plugin.name}" from ${observedSource} 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`);
+                candidates.push(candidatePlugin(plugin, candidateRoot, candidateManifest));
+                continue;
+            }
+            if (!pathExists(plugin.root) || !isGitRepo(plugin.root))
+                continue;
+            const remote = gitSync(['config', '--get', 'remote.origin.url'], plugin.root).stdout.trim();
+            const branch = gitSync(['symbolic-ref', '--short', 'HEAD'], plugin.root).stdout.trim();
+            if (remote === '' || branch === '')
+                continue;
+            const scopeRoot = plugin.scope === 'project' ? requireScopeRoot('project') : requireScopeRoot('user');
+            const candidate = join(scopeRoot, 'tmp', `${plugin.name}.${process.pid}.${Date.now()}.candidate`);
+            ensureDir(join(scopeRoot, 'tmp'));
+            const staged = stageGitRoot(remote, branch, plugin.root, candidate);
+            if (staged === undefined)
+                continue;
+            cleanupRoots.push(candidate);
+            const candidateManifest = readPluginManifest(candidate);
+            if (candidateManifest === null)
+                throw notFound(`plugin manifest not found in update candidate: ${candidate}/.crouter-plugin/plugin.json`);
+            candidates.push(candidatePlugin(plugin, candidate, candidateManifest));
+            if (currentSha(candidate) !== currentSha(plugin.root))
+                stagedRoots.push(staged);
+        }
+        for (const candidate of candidates) {
+            await assertPluginCandidateValid(candidate.plugin.manifest, candidate.plugin.root, candidate.plugin.scope, candidate.scopeRoot, `${candidate.plugin.root}/.crouter-plugin/plugin.json`, candidates);
+        }
+        activateStagedRoots(stagedRoots);
+        updateState(target.scope, (state) => {
+            if (state.marketplaces[target.name] === undefined)
+                state.marketplaces[target.name] = {};
+            state.marketplaces[target.name].last_updated = nowIso();
+        });
+        for (const plugin of sourcedPlugins) {
+            const entry = manifest.plugins.find((candidate) => candidate.name === plugin.name);
+            if (entry?.version !== undefined) {
+                updateConfig(plugin.scope, (config) => {
+                    if (config.plugins[plugin.name] !== undefined)
+                        config.plugins[plugin.name].version = entry.version;
+                });
+            }
+            updateState(plugin.scope, (state) => {
+                if (state.plugins[plugin.name] === undefined)
+                    state.plugins[plugin.name] = {};
+                state.plugins[plugin.name].last_updated = nowIso();
+            });
+        }
+        const sha = currentSha(target.root) ?? '';
+        return { name: target.name, updated: activeSha !== sha, sha };
+    }
+    finally {
+        for (const root of cleanupRoots)
+            removePath(root);
+    }
+}
 export const marketUpdate = defineLeaf({
     name: 'update',
     description: 'pull latest marketplace source',
     whenToUse: 'refreshing one named marketplace source from git, or all registered marketplace sources when no name is given; also updates installed plugins sourced from refreshed marketplaces',
     help: {
         name: 'pkg market update',
-        summary: 'git pull one or all registered marketplaces',
+        summary: 'refresh one or all registered marketplaces',
         params: [
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Marketplace name to update. Omit to update all registered marketplaces.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Narrows resolution.' },
@@ -161,79 +307,23 @@ export const marketUpdate = defineLeaf({
             { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per marketplace processed: {name, updated, sha}.' },
         ],
         outputKind: 'object',
-        effects: ['Runs git pull in marketplace directories. Updates installed plugin content/version for plugins sourced from those marketplaces.'],
+        effects: ['Stages and validates marketplace and sourced-plugin revisions before atomically activating them. Updates installed plugin content/version for plugins sourced from refreshed marketplaces.'],
     },
     run: async (input) => {
         const name = input['name'];
         const scopeInput = input['scope'];
         const scope = scopeInput === undefined ? undefined : resolveScopeArg(scopeInput);
-        function pullIfGit(root) {
-            const shaBefore = currentSha(root);
-            if (!isGitRepo(root))
-                return { updated: false, sha: shaBefore ?? '' };
-            const res = pull(root);
-            if (res.status !== 0) {
-                return { updated: false, sha: shaBefore ?? '' };
-            }
-            const shaAfter = currentSha(root);
-            return { updated: shaBefore !== shaAfter, sha: shaAfter ?? '' };
-        }
-        async function doUpdate(targets) {
-            const results = [];
-            for (const target of targets) {
-                const pullSummary = pullIfGit(target.root);
-                const freshManifest = readMarketplaceManifest(target.root);
-                if (freshManifest === null) {
-                    throw notFound(`marketplace manifest not found after refresh: ${target.root}/.crouter-marketplace/marketplace.json`);
-                }
-                updateState(target.scope, (s) => {
-                    if (s.marketplaces[target.name] === undefined) {
-                        s.marketplaces[target.name] = {};
-                    }
-                    s.marketplaces[target.name].last_updated = nowIso();
-                });
-                const sourcedPlugins = listAllPlugins().filter((plugin) => plugin.scope === target.scope && plugin.sourceMarketplace === target.name);
-                for (const plugin of sourcedPlugins) {
-                    if (isSymlink(plugin.root)) {
-                        // Marketplace pull above updates symlinked relative-source plugins.
-                    }
-                    else if (pathExists(plugin.root)) {
-                        pullIfGit(plugin.root);
-                    }
-                    const pluginEntry = freshManifest.plugins.find((p) => p.name === plugin.name);
-                    if (pluginEntry !== undefined && pluginEntry.version !== undefined) {
-                        updateConfig(plugin.scope, (c) => {
-                            if (c.plugins[plugin.name] !== undefined) {
-                                c.plugins[plugin.name].version = pluginEntry.version;
-                            }
-                        });
-                    }
-                    updateState(plugin.scope, (s) => {
-                        if (s.plugins[plugin.name] === undefined) {
-                            s.plugins[plugin.name] = {};
-                        }
-                        s.plugins[plugin.name].last_updated = nowIso();
-                    });
-                }
-                results.push({ name: target.name, updated: pullSummary.updated, sha: pullSummary.sha });
-            }
-            return results;
-        }
-        if (name !== undefined) {
-            const found = scope === undefined || scope === 'all' || scope === 'builtin'
-                ? findMarketplaceByName(name)
-                : findMarketplaceByName(name, scope);
-            if (!found)
-                throw notFound(`marketplace not found: ${name}${scope === undefined || scope === 'all' || scope === 'builtin' ? '' : ` (scope: ${scope})`}`);
-            const results = await doUpdate([{ name: found.name, scope: found.scope, root: found.root }]);
-            return { updated: results };
-        }
-        const targets = (scope === undefined || scope === 'all'
-            ? listAllMarketplaces()
-            : scope === 'builtin'
-                ? []
-                : listAllMarketplaces().filter((marketplace) => marketplace.scope === scope)).map((m) => ({ name: m.name, scope: m.scope, root: m.root }));
-        const results = await doUpdate(targets);
-        return { updated: results };
+        const targets = name === undefined
+            ? (scope === undefined || scope === 'all' ? listAllMarketplaces() : scope === 'builtin' ? [] : listAllMarketplaces().filter((marketplace) => marketplace.scope === scope))
+            : (() => {
+                const found = scope === undefined || scope === 'all' || scope === 'builtin' ? findMarketplaceByName(name) : findMarketplaceByName(name, scope);
+                if (found === null)
+                    throw notFound(`marketplace not found: ${name}${scope === undefined || scope === 'all' || scope === 'builtin' ? '' : ` (scope: ${scope})`}`);
+                return [found];
+            })();
+        const updated = [];
+        for (const target of targets)
+            updated.push(await updateMarketplaceTarget(target));
+        return { updated };
     },
 });

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

@@ -4,8 +4,22 @@ import { paginate } from '../../core/pagination.js';
 import { listInstalledPlugins, findPluginByName, } from '../../core/resolver.js';
 import { listPluginMemoryDocs } from '../../core/memory-resolver.js';
 import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
-import { SUBTREE_NAMES, coreCommandPaths } from '../../build-root.js';
+import { compileHookRegistry, discoverHookRegistry } from '../../core/command-hooks/discovery.js';
+import { hasDeclaredHooks, hookReport } from '../../core/command-hooks/report.js';
+import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog } from '../../build-root.js';
 import { resolveScopeArg, projectScopeRoot } from '../../core/scope.js';
+async function hookInspectionReport(plugin) {
+    if (!hasDeclaredHooks(plugin.manifest))
+        return undefined;
+    const catalog = await coreHookCatalog();
+    const effective = discoverHookRegistry(catalog);
+    const validation = effective.validations.find((entry) => entry.plugin.root === plugin.root);
+    if (validation === undefined) {
+        const isolated = compileHookRegistry(catalog, [plugin]);
+        return hookReport(isolated.validations[0]);
+    }
+    return hookReport(validation, effective.issues.filter((issue) => issue.plugin === plugin.name && issue.scope === plugin.scope));
+}
 export const pluginList = defineLeaf({
     name: 'list',
     description: 'paginated list of installed plugins',
@@ -93,9 +107,10 @@ export const pluginShow = defineLeaf({
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
             { name: 'docs', type: 'object[]', required: true, constraint: 'Each: {name, path}. Memory docs provided by the plugin (its `<pluginName>/` memory subtree).' },
             { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically; command execution never occurs.' },
+            { name: 'hooks', type: 'object', required: false, constraint: 'Present for every hook declaration, including hook-only plugins. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[] ({code, path?, message, received, expected, next}), trust: string}. Static only: no hook executable runs.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only. Command manifests are validated statically; commands are never executed.'],
+        effects: ['None. Read-only. Command and hook manifests are validated statically; plugin executables are never executed.'],
     },
     run: async (input) => {
         const name = input['name'];
@@ -134,6 +149,7 @@ export const pluginShow = defineLeaf({
                 issues: v.issues,
             };
         }
+        const hooks = await hookInspectionReport(found);
         return {
             name: found.name,
             scope: found.scope,
@@ -145,6 +161,7 @@ export const pluginShow = defineLeaf({
                 path: d.path,
             })),
             ...(commands !== undefined ? { commands } : {}),
+            ...(hooks !== undefined ? { hooks } : {}),
         };
     },
 });

package/dist/commands/pkg/plugin-manage.d.ts

@@ -1,16 +1,21 @@
-import { type Scope } from '../../types.js';
+import { type HookPluginCandidate } from '../../core/command-hooks/discovery.js';
+import { type PluginManifest, type Scope } from '../../types.js';
 interface MarketplaceRef {
     marketplace: string;
     plugin: string;
 }
+/** Validate a package candidate before it gains an active plugin path. The
+ * candidate namespace shadows any installed declaration of the same name. */
+export declare function assertPluginCandidateValid(manifest: PluginManifest, root: string, scope: Scope, scopeRootPath: string, where: string, candidates?: readonly HookPluginCandidate[]): Promise<void>;
+export declare function isMarketplaceRelativeSource(source: string): boolean;
 /** Install one marketplace plugin into a scope. Exported so `sys setup` can
  *  install the default plugin set through the same path `pkg plugin install`
  *  uses — refresh the source, resolve the entry, link/clone, register. */
-export declare function installFromMarketplace(ref: MarketplaceRef, scope: Scope): {
+export declare function installFromMarketplace(ref: MarketplaceRef, scope: Scope): Promise<{
     name: string;
     scope: Scope;
     path: string;
-};
+}>;
 export declare const pluginInstall: import("../../core/command.js").LeafDef;
 export declare const pluginRemove: import("../../core/command.js").LeafDef;
 export declare const pluginEnable: import("../../core/command.js").LeafDef;

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

@@ -17,8 +17,10 @@ import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../c
 import { normalizeEndpoint, validateEndpoint, validateHttpPluginTransport } from '../../core/command-plugins/endpoint.js';
 import { buildBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
 import { validatePluginBundle } from '../../core/command-plugins/bundle.js';
+import { compileHookRegistry, discoverCandidateHookRegistry, discoverCandidateHookRegistryForCandidates, discoverHookRegistry } from '../../core/command-hooks/discovery.js';
+import { hasDeclaredHooks, hookReport } from '../../core/command-hooks/report.js';
 import { fetchHttpPluginBundle } from '../../core/command-plugins/transport/http-fetch.js';
-import { SUBTREE_NAMES, coreCommandPaths } from '../../build-root.js';
+import { SUBTREE_NAMES, coreCommandPaths, coreHookCatalog } from '../../build-root.js';
 import { isGitUrl, 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
@@ -121,9 +123,44 @@ 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 });
     }
 }
+/** Static hook report for an installed plugin. An inactive/shadowed plugin
+ * still receives its own artifact and target validation; only effective plugins
+ * additionally carry collisions from the complete active registry. */
+async function hookLifecycleReport(name, scope) {
+    const plugin = findPluginByName(name, scope);
+    if (plugin === null || !hasDeclaredHooks(plugin.manifest))
+        return undefined;
+    const catalog = await coreHookCatalog();
+    const effective = discoverHookRegistry(catalog);
+    const validation = effective.validations.find((entry) => entry.plugin.root === plugin.root);
+    if (validation === undefined) {
+        const isolated = compileHookRegistry(catalog, [plugin]);
+        return hookReport(isolated.validations[0]);
+    }
+    return hookReport(validation, effective.issues.filter((issue) => issue.plugin === plugin.name && issue.scope === plugin.scope));
+}
+/** Validate a source candidate's complete hook behavior before activation. The
+ * candidate claims its future scope/name slot, so stale targets and replacement
+ * collisions reject the candidate without disturbing installed bytes. */
+async function assertManifestHooksValid(manifest, root, scope, scopeRootPath, where, candidates) {
+    if (!hasDeclaredHooks(manifest))
+        return;
+    const candidate = { name: manifest.name, scope, root, manifest, enabled: true };
+    const registryCandidates = candidates ?? [{ plugin: candidate, scopeRoot: scopeRootPath }];
+    const catalog = await coreHookCatalog();
+    const effective = candidates === undefined
+        ? discoverCandidateHookRegistry(catalog, candidate, scopeRootPath)
+        : discoverCandidateHookRegistryForCandidates(catalog, registryCandidates);
+    const validation = effective.validations.find((entry) => entry.plugin.root === root);
+    const issues = validation === undefined
+        ? compileHookRegistry(catalog, [candidate]).issues
+        : effective.issues.filter((issue) => issue.plugin === candidate.name && issue.scope === candidate.scope);
+    if (issues.length > 0)
+        throw invalidBundleError(`plugin hook behavior at ${where} is invalid`, issues);
+}
 /** 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) {
+export async function assertPluginCandidateValid(manifest, root, scope, scopeRootPath, where, candidates) {
     try {
         validatePluginManifestMemoryExtensions(manifest);
     }
@@ -135,6 +172,11 @@ function assertPluginCandidateValid(manifest, root, scope, scopeRootPath, where)
     assertManifestPageComponentsValid(manifest, where);
     assertManifestBinValid(manifest, where);
     assertManifestRequiresValid(manifest, where);
+    const commandValidation = validatePluginCommands({ name: manifest.name, scope, root, manifest, enabled: true }, new Set(SUBTREE_NAMES), await coreCommandPaths());
+    if (commandValidation.issues.length > 0) {
+        throw invalidBundleError(`plugin command behavior at ${where} is invalid`, commandValidation.issues);
+    }
+    await assertManifestHooksValid(manifest, root, scope, scopeRootPath, where, candidates);
     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('.'))) {
@@ -176,7 +218,7 @@ function writeStagedBundle(stagingRoot, manifest, bundle) {
     }
 }
 async function validateStagedBundle(name, scope, root, scopeRootPath, manifest) {
-    assertPluginCandidateValid(manifest, root, scope, scopeRootPath, `${root}/.crouter-plugin/plugin.json`);
+    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) {
@@ -300,10 +342,10 @@ function classifyInstallRef(raw) {
     throw usage(`invalid plugin install ref: ${raw}\n` +
         'Accepted forms: marketplace/plugin, git URL (https://, ssh://, git@, file://, or *.git), or local path starting ./, ../, or /. Bare plugin names are not install refs.');
 }
-function isMarketplaceRelativeSource(source) {
+export function isMarketplaceRelativeSource(source) {
     return source.startsWith('./') || source.startsWith('../') || (!isAbsolute(source) && !isGitUrl(source));
 }
-function refreshMarketplace(name, cache, opts) {
+async function refreshMarketplace(name, cache, opts) {
     const cached = cache.get(name);
     if (cached !== undefined)
         return cached;
@@ -349,7 +391,7 @@ function refreshMarketplace(name, cache, opts) {
             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`);
+            await assertPluginCandidateValid(candidateManifest, candidateRoot, plugin.scope, pluginScopeRoot, `${candidateRoot}/.crouter-plugin/plugin.json`);
         }
         renameSync(marketplace.root, previous);
         try {
@@ -397,7 +439,7 @@ function updatePluginVersion(scope, name, version) {
         s.plugins[name].last_updated = nowIso();
     });
 }
-function installFromGit(source, ref, scope) {
+async function installFromGit(source, ref, scope) {
     const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
     ensureScopeInitialized(scope, scopeRootPath);
     const pDir = join(scopeRootPath, 'plugins');
@@ -409,7 +451,7 @@ 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}`);
-        assertPluginCandidateValid(manifest, staging, scope, scopeRootPath, `${source}/.crouter-plugin/plugin.json`);
+        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}`);
@@ -424,14 +466,14 @@ function installFromGit(source, ref, scope) {
         removePath(staging);
     }
 }
-function installFromLocal(source, scope) {
+async function installFromLocal(source, scope) {
     const sourcePath = resolve(source);
     const manifest = readPluginManifest(sourcePath);
     if (manifest === null) {
         throw notFound(`plugin manifest not found at ${sourcePath}/.crouter-plugin/plugin.json`);
     }
     const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
-    assertPluginCandidateValid(manifest, sourcePath, scope, scopeRootPath, `${sourcePath}/.crouter-plugin/plugin.json`);
+    await assertPluginCandidateValid(manifest, sourcePath, scope, scopeRootPath, `${sourcePath}/.crouter-plugin/plugin.json`);
     ensureScopeInitialized(scope, scopeRootPath);
     const destDir = join(scopeRootPath, 'plugins', manifest.name);
     if (pathExists(destDir)) {
@@ -449,8 +491,8 @@ function installFromLocal(source, scope) {
 /** Install one marketplace plugin into a scope. Exported so `sys setup` can
  *  install the default plugin set through the same path `pkg plugin install`
  *  uses — refresh the source, resolve the entry, link/clone, register. */
-export function installFromMarketplace(ref, scope) {
-    const refreshed = refreshMarketplace(ref.marketplace, new Map(), { strict: true });
+export async function installFromMarketplace(ref, scope) {
+    const refreshed = await refreshMarketplace(ref.marketplace, new Map(), { strict: true });
     if (refreshed === null)
         throw notFound(`marketplace not found: ${ref.marketplace}`);
     const entry = refreshed.manifest.plugins.find((p) => p.name === ref.plugin);
@@ -470,7 +512,7 @@ export function installFromMarketplace(ref, scope) {
         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`);
+        await assertPluginCandidateValid(candidateManifest, sourcePath, scope, destRoot, `${sourcePath}/.crouter-plugin/plugin.json`);
         linkOrCopy(sourcePath, destPluginDir);
         pluginManifest = candidateManifest;
     }
@@ -482,7 +524,7 @@ export function installFromMarketplace(ref, scope) {
             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`);
+            await assertPluginCandidateValid(candidateManifest, staging, scope, destRoot, `${staging}/.crouter-plugin/plugin.json`);
             ensureDir(join(destRoot, 'plugins'));
             renameSync(staging, destPluginDir);
             pluginManifest = candidateManifest;
@@ -503,13 +545,13 @@ export function installFromMarketplace(ref, scope) {
     });
     return { name: ref.plugin, scope, path: destPluginDir };
 }
-function updateGitPluginCandidate(plugin) {
+async 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`);
+        await 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)) {
@@ -517,7 +559,7 @@ 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();
-        assertPluginCandidateValid(manifest, plugin.root, plugin.scope, scopeRootPath, `${plugin.root}/.crouter-plugin/plugin.json`);
+        await 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();
@@ -536,7 +578,7 @@ function updateGitPluginCandidate(plugin) {
         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`);
+        await assertPluginCandidateValid(manifest, staging, plugin.scope, scopeRootPath, `${staging}/.crouter-plugin/plugin.json`);
         renameSync(plugin.root, previous);
         try {
             renameSync(staging, plugin.root);
@@ -566,16 +608,17 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
     let marketplaceVersion;
     let marketplaceUpdated = false;
     if (plugin.sourceMarketplace !== undefined) {
-        const refreshed = refreshMarketplace(plugin.sourceMarketplace, marketplaceCache, opts);
+        const refreshed = await refreshMarketplace(plugin.sourceMarketplace, marketplaceCache, opts);
         if (refreshed !== null) {
             const entry = refreshed.manifest.plugins.find((candidate) => candidate.name === plugin.name);
             marketplaceVersion = entry?.version;
             marketplaceUpdated = refreshed.pull.updated;
         }
     }
-    const candidate = updateGitPluginCandidate(plugin);
+    const candidate = await updateGitPluginCandidate(plugin);
     updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? candidate.manifest.version);
     const commands = await commandReport(plugin.name, plugin.scope);
+    const hooks = await hookLifecycleReport(plugin.name, plugin.scope);
     const warnings = missingRequirementWarnings(candidate.manifest);
     return {
         name: plugin.name,
@@ -583,6 +626,7 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
         updated: marketplaceUpdated || candidate.updated,
         sha: candidate.sha,
         ...(commands !== undefined ? { commands } : {}),
+        ...(hooks !== undefined ? { hooks } : {}),
         ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
@@ -611,6 +655,7 @@ export const pluginInstall = defineLeaf({
             { name: 'kinds', type: 'integer', required: false, constraint: 'Kind-registry entry count declared by an --endpoint archive\u2019s bundle.json.' },
             { name: 'pageComponents', type: 'integer', required: false, constraint: 'Page-component registration count declared by an --endpoint archive\u2019s bundle.json.' },
             { 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.' },
         ],
         outputKind: 'object',
@@ -618,6 +663,7 @@ export const pluginInstall = defineLeaf({
             'A ref install clones, links, or copies the plugin into the scope plugins directory and registers it with enabled=true. Marketplace installs refresh the source marketplace before resolving the plugin entry.',
             'An --endpoint install fetches and validates one authenticated uncompressed tar archive before writing. It replaces the complete plugin directory with synthesized provenance and invocation metadata, commands.json, memory docs, any kind-registry entries the bundle.json declares (they join the launch registry below this scope\u2019s own config.json kinds), and any page components it declares (they join the active page-component catalog alongside the user config entries); a fetch or validation failure preserves the prior package.',
             '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.',
         ],
     },
@@ -644,16 +690,18 @@ export const pluginInstall = defineLeaf({
         if (authEnv !== undefined)
             throw usage('--auth-env is only valid with --endpoint');
         const classified = classifyInstallRef(rawRef);
-        const installed = classified.kind === 'marketplace' ? installFromMarketplace(classified.value, scope)
-            : classified.kind === 'local' ? installFromLocal(classified.value, scope)
-                : installFromGit(classified.value, gitRef, scope);
+        const installed = classified.kind === 'marketplace' ? await installFromMarketplace(classified.value, scope)
+            : classified.kind === 'local' ? await installFromLocal(classified.value, scope)
+                : await installFromGit(classified.value, gitRef, scope);
         const plugin = findPluginByName(installed.name, installed.scope);
         const commands = await commandReport(installed.name, installed.scope);
+        const hooks = await hookLifecycleReport(installed.name, installed.scope);
         const warnings = plugin === null ? [] : missingRequirementWarnings(plugin.manifest);
         return {
             ...installed,
             ...(plugin?.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
             ...(commands !== undefined ? { commands } : {}),
+            ...(hooks !== undefined ? { hooks } : {}),
             ...(warnings.length > 0 ? { warnings } : {}),
         };
     },
@@ -766,7 +814,7 @@ 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?, 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[]}. 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?, 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.' },
         ],
         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.'],