@north-light/crouter 0.3.170 → 0.3.172

package/dist/commands/memory/__tests__/lint.test.js

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { lintShortPreviewBody } from '../lint.js';
+const previewMemory = {
+    'system-prompt-visibility': 'preview',
+    'file-read-visibility': 'none',
+};
+test('memory lint warns when a preview body is short enough to inline', () => {
+    const shortBody = Array.from({ length: 29 }, (_, index) => `word${index}`).join(' ');
+    assert.match(lintShortPreviewBody(previewMemory, shortBody) ?? '', /body is 29 words but system-prompt-visibility is `preview`; use `content`/);
+    const contentMemory = { ...previewMemory, 'system-prompt-visibility': 'content' };
+    assert.equal(lintShortPreviewBody(contentMemory, shortBody), null);
+    const thresholdBody = Array.from({ length: 30 }, (_, index) => `word${index}`).join(' ');
+    assert.equal(lintShortPreviewBody(previewMemory, thresholdBody), null);
+});

package/dist/commands/memory/delete.js

@@ -22,12 +22,12 @@ function pruneEmptyParents(filePath, nameSegments) {
 export const deleteLeaf = defineLeaf({
     name: 'delete',
     description: 'delete a memory document by name',
-    whenToUse: 'a stored document is wrong, obsolete, or superseded and should be removed — the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the name exactly as `read` does (node > project stack > profile > user precedence, leaf-name fallback) and removes that file: if you can read it, you can delete it. Refuses docs you do not own — builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`) — and refuses an ambiguous leaf name rather than guessing which doc to destroy; pass the full `area/topic` name or `--scope` to pin one.',
+    whenToUse: 'a stored document is wrong, obsolete, or superseded and should be removed — the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the name exactly as `read` does (exact/direct matches by node > project stack > profile > user precedence, then leaf-name fallback) and removes that file: if you can read it, you can delete it. Refuses docs you do not own — builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`) — and refuses an ambiguous leaf name rather than guessing which doc to destroy; pass the full `area/topic` name or `--scope` to pin one.',
     help: {
         name: 'memory delete',
         summary: 'resolve a path-derived name and remove that document from its scope store',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it: precedence node > project stack > profile > user, with leaf-name fallback. A leaf that maps to genuinely different docs across scopes is rejected as ambiguous — pass the full name or --scope to disambiguate. May be scope-prefixed (`user/topic`) to pin the store directly.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it: exact identity/direct path by precedence node > project stack > profile > user, then bare leaf fallback. A leaf matching multiple different docs in one source is rejected as ambiguous — pass the full name or --scope to disambiguate. May be scope-prefixed (`user/topic`) to pin the store directly.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope before deleting. Use it to disambiguate a leaf name present at multiple scopes, or to assert which store you mean. builtin is not a choice — builtin docs ship with the package and cannot be deleted.' },
         ],
         output: [

package/dist/commands/memory/lint.d.ts

@@ -3,6 +3,7 @@
  *  `docName` is the doc's canonical resolver identity (explicit frontmatter
  *  `name`, else the normalized path-derived name) — persona layers under
  *  `kinds/` are recognized by it and never capped. */
+export declare function lintShortPreviewBody(fm: Record<string, unknown>, body: string): string | null;
 export declare function lintBodyLength(fm: Record<string, unknown>, body: string, docName: string): string | null;
 /** Schema checks for a doc living in a substrate memory dir: a memory store
  *  holds ONLY substrate docs, so a missing/invalid `kind` is an authoring

package/dist/commands/memory/lint.js

@@ -44,6 +44,8 @@ const RUNG_FIELDS = ['system-prompt-visibility', 'file-read-visibility'];
 const SYSTEM_CONTENT_MAX_WORDS = 1000;
 const FILE_READ_MAX_WORDS = 1000;
 const SYSTEM_PREVIEW_MAX_WORDS = 3000;
+/** A routing line costs more than it saves for a short rule or fact. */
+const PREVIEW_TO_CONTENT_MAX_WORDS = 30;
 /** Rules a doc may suppress via frontmatter `lint-ignore`. */
 const SUPPRESSIBLE_RULES = ['length'];
 function ignoresRule(fm, rule) {
@@ -59,6 +61,19 @@ function countBodyWords(body) {
  *  `docName` is the doc's canonical resolver identity (explicit frontmatter
  *  `name`, else the normalized path-derived name) — persona layers under
  *  `kinds/` are recognized by it and never capped. */
+export function lintShortPreviewBody(fm, body) {
+    const words = countBodyWords(body);
+    if (words >= PREVIEW_TO_CONTENT_MAX_WORDS)
+        return null;
+    const previewAxes = [
+        fm['system-prompt-visibility'] === 'preview' ? 'system-prompt-visibility' : undefined,
+        fm['file-read-visibility'] === 'preview' ? 'file-read-visibility' : undefined,
+    ].filter((axis) => axis !== undefined);
+    if (previewAxes.length === 0)
+        return null;
+    const verb = previewAxes.length === 1 ? 'is' : 'are';
+    return `body is ${words} words but ${previewAxes.join(' and ')} ${verb} \`preview\`; use \`content\` on that axis so agents receive the whole rule without a separate memory read`;
+}
 export function lintBodyLength(fm, body, docName) {
     if (ignoresRule(fm, 'length'))
         return null;
@@ -175,7 +190,7 @@ export function lintSubstrateSchema(fm) {
  *  corpus. A dangling link is an authoring error caught HERE, never silently
  *  carried; leaf-name fallback is deliberately excluded so links stay stable
  *  as the graph grows and another document acquires the same leaf name. */
-function lintFile(file, substrateStore, findings, corpusNames, fallbackName) {
+function lintFile(file, substrateStore, findings, warnings, corpusNames, fallbackName) {
     let fm;
     let body;
     try {
@@ -195,6 +210,9 @@ function lintFile(file, substrateStore, findings, corpusNames, fallbackName) {
         const lengthError = lintBodyLength(fm, body, resolveDocName(fm, fallbackName));
         if (lengthError !== null)
             findings.push({ path: file, error: lengthError });
+        const shortPreviewWarning = lintShortPreviewBody(fm, body);
+        if (shortPreviewWarning !== null)
+            warnings.push(`${file}: ${shortPreviewWarning}`);
     }
     for (const name of docLinkNames(body)) {
         if (!corpusNames.has(name)) {
@@ -252,7 +270,7 @@ export const lintLeaf = defineLeaf({
                     continue;
                 memoryCount += 1;
                 const fallbackName = normalizeDocName(relPath.replace(/\.md$/, ''));
-                lintFile(file, basename(file) !== 'MEMORY.md', findings, corpusNames, fallbackName);
+                lintFile(file, basename(file) !== 'MEMORY.md', findings, warnings, corpusNames, fallbackName);
             }
         };
         for (const root of projectScopeRoots()) {
@@ -353,7 +371,7 @@ export const lintLeaf = defineLeaf({
             corpora: { memory_stores: memoryCount, profile_projects: profileProjects },
             findings: [],
             warnings,
-            follow_up: warnings.length > 0 ? 'Corpus green — resolve the warning above to give this directory a routed memory front door.' : 'Corpus green — zero invalid frontmatter docs.',
+            follow_up: warnings.length > 0 ? 'Corpus green — review the warnings above for non-fatal authoring improvements.' : 'Corpus green — zero invalid frontmatter docs.',
         };
     },
 });

package/dist/commands/memory/read.js

@@ -10,12 +10,12 @@ import { MEMORY_KINDS } from './shared.js';
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
-    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (node > project stack > profile > user > builtin), with leaf-name fallback. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
+    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Exact identity and direct-path matches resolve by scope precedence (node > project stack > profile > user > builtin); bare leaf-name fallback is considered only when no such match exists. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
     help: {
         name: 'memory read',
         summary: 'resolve a path-derived name to its document body, frontmatter stripped unless --frontmatter',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes by precedence: node > project stack > profile > user > builtin, with leaf-name fallback.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Exact identity and direct-path matches resolve by scope precedence: node > project stack > profile > user > builtin. A bare leaf falls back only when no exact/direct match exists.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Narrows resolution when the name is ambiguous across kinds.' },
             { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes the YAML frontmatter in the returned body. Off by default — only the body is returned.' },
         ],
@@ -35,8 +35,8 @@ export const readLeaf = defineLeaf({
         const nameRaw = input['name'];
         const kindFilter = input['kind'];
         const includeFrontmatter = input['frontmatter'];
-        // Resolve a substrate/memory document across scopes (node > project stack
-        // > profile > user > builtin, with leaf-name fallback). --kind is threaded
+        // Resolve a substrate/memory document across scopes: exact/direct matches
+        // by precedence first, then leaf-name fallback. --kind is threaded
         // INTO resolution (not a post-filter): a nearer wrong-kind doc is skipped
         // so a farther matching-kind doc is found instead of shadowing it into a
         // false not_found. The substrate corpus now includes plugin docs (mounted

package/dist/commands/node.js

@@ -3,7 +3,7 @@
 // flow through `crtr push`, and scheduled commands live under `crtr cron`.
 import { defineLeaf, defineBranch } from '../core/command.js';
 import { InputError } from '../core/io.js';
-import { inboxPopupHint } from '../core/keybindings/index.js';
+import { inboxHint } from '../core/keybindings/index.js';
 import { writeClipboardText } from '../core/clipboard-text.js';
 import { mark } from '../core/timing.js';
 import { displayMessage } from '../core/runtime/tmux-chrome.js';
@@ -737,7 +737,7 @@ export const surfaceNodeFocusLeaf = defineLeaf({
             throw new InputError({
                 error: 'not_focusable',
                 message: `node ${id} is a human-ask (kind:human), not a conversation — it has no pi session to focus.`,
-                next: `The pending question is queued for the human (${inboxPopupHint()} opens the inbox popup); see it with \`crtr human list\`, or retract it with \`crtr human cancel ${id}\`.`,
+                next: `The pending question is queued for the human (${inboxHint()} opens the inbox); see it with \`crtr human list\`, or retract it with \`crtr human cancel ${id}\`.`,
             });
         }
         // Opening history is not resuming work. A terminal/canceled/crashed node has
@@ -1733,11 +1733,11 @@ const nodeSubscription = defineBranch({
 const nodePromote = defineLeaf({
     name: 'promote',
     description: 'become an orchestrator of a chosen kind',
-    whenToUse: 'what remains needs decomposition across delegated children — many phases to delegate and persist across refreshes — so become an orchestrator: a long-lived, roadmap-holding node that fans work out to children and survives context refreshes (`node yield`). Specialize it to the kind of work it now steers, and optionally make it interactable so it stays dormant between inbox/human pings instead of owing a final. Do NOT reach for this for work that fits one window, or merely because you spawned a child — a base worker that spawns a helper and ends with `push final` never needs to promote',
+    whenToUse: 'the remaining work contains independent units that can run in parallel, and the task is large enough that coordinating and integrating them will materially improve intelligence, productivity, or elapsed throughput. Become a long-lived, roadmap-holding orchestrator whose primary job is steering those children across refreshes (`node yield`). Keep sequential or tightly coupled work in base mode even when it spans phases or context windows; spawning one helper does not itself require promotion',
     tier: 'important',
     help: {
         name: 'node promote',
-        summary: 'promote yourself to an orchestrator — do this when your task outgrows one context window (many phases to delegate and persist across refreshes); not for work that fits one window, and not merely because you spawned a child. Mode only — lifecycle stays as-is unless you pass --resident',
+        summary: 'promote yourself to an orchestrator when worthwhile parallel delegation should make coordination your primary job; task duration, sequential phases, or one helper do not qualify. Mode only — lifecycle stays as-is unless you pass --resident',
         params: [
             { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every top-level installable kind and when to use each; a sub-kind (e.g. plan/reviewers/security) is valid too by exact path but not listed here. For an exact composed persona list, use `crtr sys prompt-review --list --kind <kind>` with the target kind. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
             { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'ALSO flip lifecycle→resident: make the node interactable — it stays dormant, woken by inbox/human, and is never forced to submit a final. Omit to stay terminal/orchestrator (delegates + holds a roadmap, but still owes a final up the spine and reaps when done).' },
@@ -1882,14 +1882,14 @@ const nodeLifecycle = defineBranch({
 const nodeYield = defineLeaf({
     name: 'yield',
     description: 'refresh your context, same mode, against your roadmap or goal',
-    whenToUse: 'your context is filling but the mandate remains; refresh in the same mode, or combine the refresh with promotion when the remaining work now needs delegated phases',
+    whenToUse: 'your context is filling but the mandate remains; refresh in the same mode, or combine the refresh with promotion when meaningful independent work can run in parallel and coordinating it should become your primary job',
     help: {
         name: 'node yield',
         summary: 'request a fresh context window against your roadmap or original goal; mode stays unchanged unless --promote is passed',
         guide: 'Persist anything needed after refresh and send any pending human question before invoking; in-flight asks survive the refresh.',
         params: [
-            { kind: 'flag', name: 'promote', type: 'bool', required: false, constraint: 'Also become an orchestrator as you refresh — the one-step form of yield + promote, for when what remains needs decomposition across delegated children. Omit for a plain, mode-preserving refresh (a base node stays base). Already an orchestrator? This is not an error: your mode stays orchestrator and a missing roadmap is seeded.' },
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Respecialize as you refresh — change your kind to this (developer, review, spec, design, plan, explore, general). Defaults to your current kind. Combines with either form: with --promote it sets the orchestrator kind you become; without it, it reshapes your CURRENT mode in place.' },
+            { kind: 'flag', name: 'promote', type: 'bool', required: false, constraint: 'Also become an orchestrator as you refresh. Pass only when (1) the remaining work contains independent units that can run in parallel and (2) the task is large enough that parallel execution will materially improve intelligence, productivity, or elapsed throughput after coordination and synthesis. Task length, context exhaustion, sequential phases, or one helper are not enough; keep hands-on work in base mode and yield again as needed. Promote when coordinating and integrating children becomes your primary job. Already an orchestrator? This is not an error: your mode stays orchestrator and a missing roadmap is seeded.' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Respecialize as you refresh. The <kinds> list below names every top-level available kind and when to choose it; a sub-kind (e.g. plan/reviewers/security) is valid too by exact path but not listed here. Defaults to your current kind. With --promote it sets the orchestrator kind you become; without --promote it changes the kind while preserving your current mode.' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model your fresh revive runs on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. A node steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
             // Deliberate fail-first contract (#395): builtin orchestration guidance shows bare
             // `crtr node yield`; that invocation fails fast and surfaces yield's full help just in
@@ -1903,6 +1903,7 @@ const nodeYield = defineLeaf({
             { name: 'model', type: 'string', required: false, constraint: 'The model tier your fresh revive will run on, present only when you changed it with --model.' },
             { name: 'will_refresh', type: 'boolean', required: true, constraint: 'Always true: end your turn and you will revive fresh.' },
         ],
+        dynamicState: () => kindsStateBlock(),
         outputKind: 'object',
         effects: ['Sets intent=refresh; the stophook shuts the process down on next stop and the daemon revives it fresh.', '--kind and/or --model durably reshape the node (kind respecialization, model-tier pin) before the refresh-revive; --promote additionally flips mode→orchestrator and seeds a roadmap scaffold — mode is otherwise left exactly as it was.'],
     },

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

@@ -1,19 +1,19 @@
-import { join, resolve, isAbsolute } from 'node:path';
-import { renameSync } from 'node:fs';
+import { join, resolve, isAbsolute, sep } from 'node:path';
+import { renameSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { defineLeaf } from '../../core/command.js';
-import { CrtrError, notFound, usage, general, network } from '../../core/errors.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 { updateConfig, updateState, ensureScopeInitialized } from '../../core/config.js';
 import { pathExists, ensureDir, removePath, nowIso, linkOrCopy, isSymlink, atomicWriteJson } from '../../core/fs-utils.js';
 import { clone, pull, deriveNameFromUrl, currentSha, isGitRepo } from '../../core/git.js';
-import { pluginManifestPath, readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
+import { readMarketplaceManifest, readPluginManifest } from '../../core/manifest.js';
 import { validatePluginCommands, validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
 import { normalizeEndpoint, validateEndpoint, validateHttpPluginTransport } from '../../core/command-plugins/endpoint.js';
-import { resolveHttpPluginManifestStore, writeHttpPluginManifest } from '../../core/command-plugins/store.js';
-import { fetchHttpPluginManifest, refreshHttpPlugin } from '../../core/command-plugins/transport/http-fetch.js';
+import { validatePluginBundle } from '../../core/command-plugins/bundle.js';
+import { fetchHttpPluginBundle } from '../../core/command-plugins/transport/http-fetch.js';
 import { SUBTREE_NAMES } from '../../build-root.js';
-import { ExitCode } from '../../types.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
@@ -32,66 +32,137 @@ function commandReport(name, scope) {
     return { mounts: v.contributions.map((c) => c.node.name), issues: v.issues };
 }
 const PLUGIN_NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
-function unsafeHttpManifestPath(name, commands) {
-    throw new CrtrError('command_path_unsafe', `HTTP plugin "${name}" commands pointer escapes the plugin root or is not a regular file`, ExitCode.USAGE, { received: commands, field: 'commands', next: 'Fix plugin.json.commands.' });
-}
 function validateHttpInstall(name, endpoint, authEnv) {
-    if (typeof name !== 'string' || !PLUGIN_NAME_RE.test(name)) {
+    if (typeof name !== 'string' || !PLUGIN_NAME_RE.test(name))
         throw usage('invalid --name: expected a lowercase kebab-case plugin handle');
-    }
     const endpointValidation = validateEndpoint(endpoint);
-    if (!endpointValidation.isValid) {
+    if (!endpointValidation.isValid)
         throw usage(`invalid --endpoint: ${endpointValidation.errors.join('; ')}`);
-    }
     const normalizedEndpoint = normalizeEndpoint(endpoint);
-    const transportValidation = validateHttpPluginTransport({
-        kind: 'http',
-        endpoint: normalizedEndpoint,
-        ...(authEnv !== undefined ? { authEnv } : {}),
-    });
-    if (transportValidation.transport === undefined) {
+    const transportValidation = validateHttpPluginTransport({ kind: 'http', endpoint: normalizedEndpoint, ...(authEnv !== undefined ? { authEnv } : {}) });
+    if (transportValidation.transport === undefined)
         throw usage(`invalid HTTP plugin transport: ${transportValidation.errors.join('; ')}`);
-    }
     return transportValidation.transport;
 }
-async function installHttpPlugin(name, endpoint, authEnv, scope) {
-    const transport = validateHttpInstall(name, endpoint, authEnv);
-    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
-    const root = join(scopeRootPath, 'plugins', name);
-    if (pathExists(root) && readPluginManifest(root)?.transport?.kind !== 'http') {
-        throw general(`plugin "${name}" already exists at ${root} and is not an HTTP-transport plugin`);
+function invocationTransport(bundle) {
+    return { kind: 'http', endpoint: new URL(bundle.endpoint).origin, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) };
+}
+function stagedPath(stagingRoot, relative) {
+    const path = resolve(stagingRoot, relative);
+    if (path === stagingRoot || !path.startsWith(stagingRoot + sep)) {
+        throw general(`bundle member path escapes the staging directory: ${relative}`);
     }
-    if (pathExists(root) && resolveHttpPluginManifestStore({ root, commands: 'commands.json' }) === null) {
-        unsafeHttpManifestPath(name, 'commands.json');
+    return path;
+}
+function writeStagedBundle(stagingRoot, manifest, bundle) {
+    atomicWriteJson(stagedPath(stagingRoot, '.crouter-plugin/plugin.json'), manifest);
+    for (const directory of bundle.directories)
+        ensureDir(stagedPath(stagingRoot, directory.path));
+    writeFileSync(stagedPath(stagingRoot, 'commands.json'), bundle.commandsBytes);
+    for (const document of bundle.memory) {
+        const target = stagedPath(stagingRoot, document.path);
+        ensureDir(resolve(target, '..'));
+        writeFileSync(target, document.bytes);
     }
-    const fetched = await fetchHttpPluginManifest({
-        name,
-        endpoint: transport.endpoint,
-        ...(transport.authEnv !== undefined ? { authEnv: transport.authEnv } : {}),
-    });
+}
+function validateStagedBundle(name, scope, root, manifest) {
+    const staged = { name, scope, root, manifest, enabled: true };
+    const validation = validatePluginCommands(staged, new Set(SUBTREE_NAMES));
+    if (validation.issues.length > 0) {
+        throw general(`bundle staged package for "${name}" is invalid`, { issues: validation.issues });
+    }
+}
+function isSourceInstalled(plugin) {
+    return plugin.sourceMarketplace !== undefined || isGitRepo(plugin.root) || isSymlink(plugin.root);
+}
+function rejectLegacyHttpPlugin(name) {
+    throw general(`HTTP plugin "${name}" uses the removed commands-only endpoint format`, { next: `Run \`crtr pkg plugin remove ${name}\`, then reinstall it with \`crtr pkg plugin install --name ${name} --endpoint <archive-url>\`.` });
+}
+function existingBundleRoot(name, scope, root) {
+    if (!pathExists(root))
+        return undefined;
+    const existing = findPluginByName(name, scope);
+    if (existing?.manifest.bundle !== undefined)
+        return existing;
+    if (existing?.manifest.transport?.kind === 'http' && existing !== undefined && !isSourceInstalled(existing))
+        rejectLegacyHttpPlugin(name);
+    throw general(`plugin "${name}" already exists at ${root}; run \`crtr pkg plugin remove ${name}\` before installing the archive plugin.`);
+}
+async function replaceBundlePlugin(name, bundleSource, scope, options) {
+    const fetchTransport = validateHttpInstall(name, bundleSource.endpoint, bundleSource.authEnv);
+    const bundle = { endpoint: fetchTransport.endpoint, ...(fetchTransport.authEnv !== undefined ? { authEnv: fetchTransport.authEnv } : {}) };
+    const transport = invocationTransport(bundle);
+    const scopeRootPath = scope === 'project' ? ensureProjectScopeRoot() : userScopeRoot();
+    const root = join(scopeRootPath, 'plugins', name);
+    existingBundleRoot(name, scope, root);
+    const fetched = await fetchHttpPluginBundle({ name, endpoint: bundle.endpoint, ...(bundle.authEnv !== undefined ? { authEnv: bundle.authEnv } : {}) });
     if (fetched.status !== 200) {
-        const message = `HTTP plugin install failed for "${name}": ${fetched.message}`;
+        const message = `HTTP plugin bundle fetch failed for "${name}": ${fetched.message}`;
         if (fetched.status === 'auth_env_missing')
             throw usage(message);
         if (fetched.status === 'cli_unreachable')
             throw network(message);
         throw general(message);
     }
-    ensureScopeInitialized(scope, scopeRootPath);
-    atomicWriteJson(pluginManifestPath(root), {
+    const validated = await validatePluginBundle(fetched.raw, { reservedCoreNames: new Set(SUBTREE_NAMES) });
+    if (validated.bundle === undefined)
+        throw general(`HTTP plugin bundle for "${name}" is invalid`, { issues: validated.issues });
+    const version = createHash('sha256').update(fetched.raw).digest('hex').slice(0, 12);
+    const manifest = {
         name,
+        version,
         commands: 'commands.json',
         transport,
-    });
-    const store = resolveHttpPluginManifestStore({ root, commands: 'commands.json' });
-    if (store === null)
-        unsafeHttpManifestPath(name, 'commands.json');
-    writeHttpPluginManifest(store, fetched.raw);
+        bundle,
+    };
+    const tmpRoot = join(scopeRootPath, 'tmp');
+    const staging = join(tmpRoot, `${name}.${process.pid}`);
+    const previous = `${staging}.prev`;
+    if (pathExists(previous))
+        throw general(`cannot replace plugin "${name}": prior interrupted replacement remains at ${previous}`);
+    ensureDir(tmpRoot);
+    ensureDir(join(scopeRootPath, 'plugins'));
+    removePath(staging);
+    try {
+        ensureDir(staging);
+        writeStagedBundle(staging, manifest, validated.bundle);
+        validateStagedBundle(name, scope, staging, manifest);
+        let movedPrevious = false;
+        if (pathExists(root)) {
+            renameSync(root, previous);
+            movedPrevious = true;
+        }
+        try {
+            renameSync(staging, root);
+        }
+        catch (error) {
+            if (movedPrevious)
+                renameSync(previous, root);
+            throw error;
+        }
+        if (movedPrevious)
+            removePath(previous);
+    }
+    finally {
+        removePath(staging);
+    }
+    ensureScopeInitialized(scope, scopeRootPath);
     updateConfig(scope, (cfg) => {
-        cfg.plugins[name] = { enabled: true };
+        cfg.plugins[name] = { enabled: options.enable ? true : (cfg.plugins[name]?.enabled ?? true), version };
+    });
+    updateState(scope, (state) => {
+        if (state.plugins[name] === undefined)
+            state.plugins[name] = {};
+        state.plugins[name].last_updated = nowIso();
     });
     const commands = commandReport(name, scope);
-    return { name, scope, path: root, transport: 'http', ...(commands !== undefined ? { commands } : {}) };
+    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, commands };
+}
+async function installHttpPlugin(name, endpoint, authEnv, scope) {
+    const source = validateHttpInstall(name, endpoint, authEnv);
+    return replaceBundlePlugin(name, { endpoint: source.endpoint, ...(source.authEnv !== undefined ? { authEnv: source.authEnv } : {}) }, scope, { enable: true });
 }
 function classifyInstallRef(raw) {
     if (raw.startsWith('./') || raw.startsWith('../') || raw.startsWith('/')) {
@@ -269,22 +340,13 @@ export function installFromMarketplace(ref, scope) {
     return { name: ref.plugin, scope, path: destPluginDir };
 }
 async function updateOnePlugin(plugin, marketplaceCache, opts) {
-    if (plugin.manifest.transport?.kind === 'http') {
-        const commandsPath = plugin.manifest.commands;
-        if (typeof commandsPath !== 'string' || commandsPath.length === 0) {
-            throw usage(`HTTP plugin "${plugin.name}" has no commands path in plugin.json; fix the manifest before updating.`);
-        }
-        const store = resolveHttpPluginManifestStore({ root: plugin.root, commands: commandsPath });
-        if (store === null)
-            unsafeHttpManifestPath(plugin.name, commandsPath);
-        await refreshHttpPlugin({
-            name: plugin.name,
-            endpoint: plugin.manifest.transport.endpoint,
-            ...(plugin.manifest.transport.authEnv !== undefined ? { authEnv: plugin.manifest.transport.authEnv } : {}),
-        }, store);
-        const commands = commandReport(plugin.name, plugin.scope);
-        return { name: plugin.name, transport: 'http', updated: true, ...(commands !== undefined ? { commands } : {}) };
+    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, commands: replaced.commands };
     }
+    if (plugin.manifest.transport?.kind === 'http' && !sourceInstalled)
+        rejectLegacyHttpPlugin(plugin.name);
     let contentUpdate = { updated: false, sha: currentSha(plugin.root) ?? '' };
     let marketplaceVersion;
     if (plugin.sourceMarketplace !== undefined) {
@@ -309,7 +371,7 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
     const commands = commandReport(plugin.name, plugin.scope);
     return {
         name: plugin.name,
-        ...(plugin.manifest.transport?.kind === 'exec' ? { transport: 'exec' } : {}),
+        ...(plugin.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
         updated: contentUpdate.updated,
         sha: contentUpdate.sha,
         ...(commands !== undefined ? { commands } : {}),
@@ -318,13 +380,13 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
 export const pluginInstall = defineLeaf({
     name: 'install',
     description: 'install from a ref or HTTP endpoint',
-    whenToUse: 'installing one plugin from a marketplace ref, git URL, local path, or an HTTP command-manifest endpoint',
+    whenToUse: 'installing one plugin from a marketplace ref, git URL, local path, or an HTTP directory-archive endpoint',
     help: {
         name: 'pkg plugin install',
         summary: 'install a plugin from a ref or HTTP endpoint',
         params: [
             { kind: 'positional', name: 'install-ref', type: 'string', required: false, constraint: 'Plugin install ref. Provide exactly one of INSTALL-REF or --endpoint. Accepted ref forms: marketplace/plugin; git URL starting https://, ssh://, git@, file://, or ending .git; local path starting ./, ../, or /.' },
-            { kind: 'flag', name: 'endpoint', type: 'string', required: false, constraint: 'HTTP plugin endpoint. Provide exactly one of --endpoint or INSTALL-REF. Must be an absolute https: URL; http: is permitted only for localhost, 127.0.0.1, [::1], ::1, or host.docker.internal. Credentials and fragments are rejected.' },
+            { kind: 'flag', name: 'endpoint', type: 'string', required: false, constraint: 'HTTP plugin directory-archive endpoint. Provide exactly one of --endpoint or INSTALL-REF. Must be an absolute https: URL; http: is permitted only for localhost, 127.0.0.1, [::1], ::1, or host.docker.internal. Credentials and fragments are rejected.' },
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Required with --endpoint and rejected without it. Lowercase kebab-case plugin handle.' },
             { kind: 'flag', name: 'auth-env', type: 'string', required: false, constraint: 'Optional environment variable holding the HTTP bearer token. Accepted only with --endpoint; its value is never stored.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Default: project if available, else user.' },
@@ -335,12 +397,14 @@ export const pluginInstall = defineLeaf({
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the plugin was installed into.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the installed plugin directory.' },
             { name: 'transport', type: 'string', required: false, constraint: 'exec or http when the plugin declares commands. Always http for an --endpoint install.' },
+            { name: 'version', type: 'string', required: false, constraint: 'First 12 hex characters of the fetched archive SHA-256 for an --endpoint install.' },
+            { name: 'docs', type: 'integer', required: false, constraint: 'Memory document count written from an --endpoint archive.' },
             { 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.' },
         ],
         outputKind: 'object',
         effects: [
             '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 validates inputs, fetches the command manifest before writing, then writes plugin.json and commands.json and enables the plugin. Reinstalling the same HTTP plugin name replaces its stored manifest and metadata; a fetch failure writes nothing.',
+            '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, and memory docs; 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.',
         ],
     },
@@ -478,7 +542,7 @@ export const pluginDisable = defineLeaf({
 export const pluginUpdate = defineLeaf({
     name: 'update',
     description: 'update installed plugin content',
-    whenToUse: 'refreshing one named plugin or all installed plugins: HTTP plugins re-fetch their command manifest, while local plugins retain their git update behavior',
+    whenToUse: 'refreshing one named plugin or all installed plugins: archive plugins replace commands and memory together, while source-installed plugins retain their source update behavior',
     help: {
         name: 'pkg plugin update',
         summary: 'refresh one or all installed plugins',
@@ -486,10 +550,10 @@ export const pluginUpdate = defineLeaf({
             { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Plugin name to update. Omit to update all installed plugins.' },
         ],
         output: [
-            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, commands?}. HTTP plugins report transport=http and replace commands.json after an authenticated refetch; sha is present for git updates. commands is present only for plugins declaring a command manifest: {mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})} — validated statically, never executing commands.' },
+            { name: 'updated', type: 'object[]', required: true, constraint: 'One entry per plugin processed: {name, transport?, updated, sha?, version?, docs?, commands?, error?}. Archive plugins report transport=http and replace their complete directory after an authenticated refetch; version is the archive content identifier and docs is the written memory-document 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[]}.' },
         ],
         outputKind: 'object',
-        effects: ['HTTP plugins unconditionally re-fetch and replace commands.json; a fetch failure exits nonzero and preserves prior bytes. Other plugins retain their git pull, 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.'],
     },
     run: async (input) => {
         const name = input['name'];
@@ -503,8 +567,19 @@ export const pluginUpdate = defineLeaf({
         }
         const targets = listAllPlugins().filter((p) => p.scope !== 'builtin');
         const results = [];
-        for (const plugin of targets)
-            results.push(await updateOnePlugin(plugin, marketplaceCache, { strict: false }));
+        for (const plugin of targets) {
+            try {
+                results.push(await updateOnePlugin(plugin, marketplaceCache, { strict: false }));
+            }
+            catch (error) {
+                results.push({
+                    name: plugin.name,
+                    ...(plugin.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
+                    updated: false,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
         return { updated: results };
     },
 });

package/dist/commands/surface-inspect.js

@@ -4,7 +4,7 @@ import { inspectorCore } from '../core/inspector/core.js';
 import { inspectorText } from '../core/inspector/text.js';
 import { inspectorTui } from '../core/inspector/tui.js';
 import { inTmux } from '../core/runtime/placement-tmux.js';
-import { runCoreView } from '../core/tui/host.js';
+import { runInspector } from '../core/inspector/host.js';
 export const surfaceInspectLeaf = defineLeaf({
     name: 'inspect',
     description: 'host the native Inspector for one node',
@@ -24,7 +24,7 @@ export const surfaceInspectLeaf = defineLeaf({
     run: async (input) => {
         const node = input['node'];
         const section = (input['section'] ?? 'overview');
-        const host = () => runCoreView(inspectorCore, inspectorTui, inspectorText, { options: { target: node, section } });
+        const host = () => runInspector(inspectorCore, inspectorTui, inspectorText, { options: { target: node, section } });
         // Any non-interactive invocation (pipe, redirected stdout) is a static dump.
         if (!process.stdin.isTTY || !process.stdout.isTTY) {
             await host();

package/dist/commands/surface.js

@@ -1,11 +1,7 @@
 // `crtr surface` — the screen-facing entrypoints.
 //
-// Groups the four surface families under one canonical noun: standalone tmux
-// views, live broker attachment, the split editor workspace, and the browser
-// shell.
+// Groups the screen-facing surface families under one canonical noun.
 import { defineBranch } from '../core/command.js';
-import { registerView } from './view.js';
-import { registerWorkspace } from './workspace.js';
 import { registerWeb } from '../clients/web/web-cmd.js';
 import { registerAttach } from '../clients/attach/command.js';
 import { tmuxSpreadLeaf } from './surface-tmux-spread.js';
@@ -23,26 +19,24 @@ function namespaceForSurface(node) {
     }
 }
 export function registerSurface() {
-    const view = registerView();
     const attach = registerAttach();
-    const workspace = registerWorkspace();
     const web = registerWeb();
-    for (const child of [view, attach, workspace, web]) {
+    for (const child of [attach, web]) {
         child.tier = 'important';
         namespaceForSurface(child);
     }
     return defineBranch({
         name: 'surface',
         rootEntry: {
-            concept: 'screen-facing surfaces — node viewers, standalone views, live broker attachment, the editor workspace, and the browser shell',
+            concept: 'screen-facing surfaces — node viewers, live broker attachment, the Inspector, and the browser shell',
             desc: 'open and manage screen-facing surfaces',
-            useWhen: 'you need a UI or presentation surface rather than a node, document, or graph operation — node-viewer navigation, standalone tmux views, live broker attachment, the split workspace layout, or the browser-hosted shell',
+            useWhen: 'you need a UI or presentation surface rather than a node, document, or graph operation — node-viewer navigation, live broker attachment, node inspection, or the browser-hosted shell',
         },
         help: {
             name: 'surface',
             summary: 'open and manage screen-facing surfaces',
-            model: 'Choose `node` for navigation among node viewers. The other families select a host or layout: standalone view, broker attachment, editor workspace, browser shell, subtree spread, or adjacent editor pane.',
+            model: 'Choose `node` for navigation among node viewers. The other commands open a broker attachment, node Inspector, browser shell, subtree spread, or adjacent editor pane.',
         },
-        children: [registerSurfaceNode(), view, attach, workspace, web, surfaceInspectLeaf, surfaceReloadLeaf, tmuxSpreadLeaf, surfaceEditLeaf],
+        children: [registerSurfaceNode(), attach, web, surfaceInspectLeaf, surfaceReloadLeaf, tmuxSpreadLeaf, surfaceEditLeaf],
     });
 }