@north-light/crouter 0.3.198 → 0.3.200

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

@@ -5,12 +5,14 @@ import { defineLeaf } from '../../core/command.js';
 import { notFound, usage, general, network } from '../../core/errors.js';
 import { findMarketplaceByName, findPluginByName, listAllPlugins } from '../../core/resolver.js';
 import { pluginsDir, ensureProjectScopeRoot, userScopeRoot, resolveScopeArg, projectScopeRoot, requireScopeRoot, } from '../../core/scope.js';
-import { updateConfig, updateState, ensureScopeInitialized, invalidPluginKindsReasons } from '../../core/config.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, isGitRepo } from '../../core/git.js';
+import { clone, pull, deriveNameFromUrl, currentSha, gitSync, isGitRepo } from '../../core/git.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 { buildBrokerEnv, resolvePathExecutable } from '../../core/runtime/spawn-env.js';
 import { validatePluginBundle } from '../../core/command-plugins/bundle.js';
 import { fetchHttpPluginBundle } from '../../core/command-plugins/transport/http-fetch.js';
 import { SUBTREE_NAMES, coreCommandPaths } from '../../build-root.js';
@@ -45,6 +47,15 @@ function validateHttpInstall(name, endpoint, authEnv) {
         throw usage(`invalid HTTP plugin transport: ${transportValidation.errors.join('; ')}`);
     return transportValidation.transport;
 }
+/** Fold structured validation issues into the thrown message so every surface
+ *  (prose and --json) names the exact offender — the error payload renderer
+ *  carries only message/received/next scalars, so an `issues` array left in
+ *  details alone never reaches the caller. The first issue's own remedy becomes
+ *  the `Next:` line. */
+function invalidBundleError(summary, issues) {
+    const lines = issues.map((i) => `- ${i.code}${i.path !== undefined ? ` at ${i.path}` : ''}: ${i.message} (received ${JSON.stringify(i.received)}, expected ${i.expected})`);
+    return general(`${summary}:\n${lines.join('\n')}`, { issues, ...(issues.length > 0 ? { next: issues[0].next } : {}) });
+}
 /** Fail a SOURCE install (git/local/marketplace) loudly when the plugin's
  *  authored manifest declares an invalid `kinds` block — the same install-time
  *  strictness `validatePluginBundle` applies to an archive's bundle.json. The
@@ -55,7 +66,56 @@ function assertManifestKindsValid(manifest, where) {
         return;
     const reasons = invalidPluginKindsReasons(manifest.kinds);
     if (reasons.length > 0) {
-        throw general(`plugin manifest at ${where} declares an invalid kinds block`, { issues: reasons });
+        throw general(`plugin manifest at ${where} declares an invalid kinds block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
+    }
+}
+/** Fail a SOURCE install (git/local/marketplace) loudly when the plugin's
+ *  authored manifest declares an invalid `bin` block. The read side
+ *  (`normalizeBin`) drops invalid entries silently, so without this the plugin
+ *  would install cleanly and its bare command would simply never appear on any
+ *  node's PATH. */
+function assertManifestBinValid(manifest, where) {
+    if (manifest.bin === undefined)
+        return;
+    const reasons = invalidPluginBinReasons(manifest.bin);
+    if (reasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid bin block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
+    }
+}
+/** Fail a source install or update only when `requires` itself is malformed.
+ *  A well-formed requirement missing from PATH stays advisory and becomes an
+ *  install warning after the plugin is registered. */
+function assertManifestRequiresValid(manifest, where) {
+    if (manifest.requires === undefined)
+        return;
+    const reasons = invalidPluginRequiresReasons(manifest.requires);
+    if (reasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid requires block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
+    }
+}
+/** Advisory diagnostics for the PATH an ordinary node launched here receives.
+ *  `buildBrokerEnv` includes contributed bare binaries, so one plugin can
+ *  satisfy another plugin's requirement without either being installed globally. */
+function missingRequirementWarnings(manifest) {
+    if (manifest.requires === undefined)
+        return [];
+    const env = buildBrokerEnv({ argv: [], env: { CRTR_NODE_CWD: process.cwd(), CRTR_PROFILE_ID: process.env['CRTR_PROFILE_ID'] ?? '' } });
+    return Object.entries(normalizeRequires(manifest.requires))
+        .filter(([name]) => resolvePathExecutable(name, env, process.cwd()) === null)
+        .map(([name, hint]) => `Warning: plugin "${manifest.name}" requires "${name}" on PATH — ${hint}`);
+}
+/** Fail a SOURCE install (git/local/marketplace) loudly when the plugin's
+ *  authored manifest declares an invalid `page_components` block — the same
+ *  install-time strictness `validatePluginBundle` applies to an archive's
+ *  bundle.json. `resolvePageComponents` throws on a malformed block, so an
+ *  unchecked install would break every page-authoring surface at read time
+ *  instead of at the install that introduced it. */
+function assertManifestPageComponentsValid(manifest, where) {
+    if (manifest.page_components === undefined)
+        return;
+    const reasons = invalidPageComponentsReasons(manifest.page_components);
+    if (reasons.length > 0) {
+        throw general(`plugin manifest at ${where} declares an invalid page_components block:\n${reasons.map((r) => `- ${r}`).join('\n')}`, { issues: reasons });
     }
 }
 function invocationTransport(bundle) {
@@ -83,7 +143,7 @@ async function validateStagedBundle(name, scope, root, manifest) {
     const staged = { name, scope, root, manifest, enabled: true };
     const validation = validatePluginCommands(staged, new Set(SUBTREE_NAMES), await coreCommandPaths());
     if (validation.issues.length > 0) {
-        throw general(`bundle staged package for "${name}" is invalid`, { issues: validation.issues });
+        throw invalidBundleError(`bundle staged package for "${name}" is invalid`, validation.issues);
     }
 }
 function isSourceInstalled(plugin) {
@@ -120,7 +180,7 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
     }
     const validated = await validatePluginBundle(fetched.raw, { reservedCoreNames: new Set(SUBTREE_NAMES), coreCommandPaths: await coreCommandPaths() });
     if (validated.bundle === undefined)
-        throw general(`HTTP plugin bundle for "${name}" is invalid`, { issues: validated.issues });
+        throw invalidBundleError(`HTTP plugin bundle for "${name}" is invalid`, validated.issues);
     const version = createHash('sha256').update(fetched.raw).digest('hex').slice(0, 12);
     const manifest = {
         name,
@@ -133,6 +193,11 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
         // what registers them: readMergedLaunchConfig reads kinds from installed
         // plugin MANIFESTS, never from bundle.json directly.
         ...(validated.bundle.kinds !== undefined ? { kinds: validated.bundle.kinds } : {}),
+        // Page-component contributions from the archive's bundle.json, likewise
+        // already validated. `resolvePageComponents` reads the MANIFEST, so this
+        // 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 } : {}),
     };
     const tmpRoot = join(scopeRootPath, 'tmp');
     const staging = join(tmpRoot, `${name}.${process.pid}`);
@@ -177,7 +242,7 @@ async function replaceBundlePlugin(name, bundleSource, scope, options) {
     const commands = await commandReport(name, scope);
     if (commands === undefined)
         throw general(`bundle plugin "${name}" has no staged command report`);
-    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, kinds: Object.keys(validated.bundle.kinds ?? {}).length, commands };
+    return { name, scope, path: root, transport: 'http', version, docs: validated.bundle.memory.length, kinds: Object.keys(validated.bundle.kinds ?? {}).length, pageComponents: (validated.bundle.page_components ?? []).length, commands };
 }
 async function installHttpPlugin(name, endpoint, authEnv, scope) {
     const source = validateHttpInstall(name, endpoint, authEnv);
@@ -240,6 +305,15 @@ function refreshMarketplace(name, cache, opts) {
     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()}`);
+    }
+}
 function updatePluginVersion(scope, name, version) {
     updateConfig(scope, (cfg) => {
         const entry = cfg.plugins[name];
@@ -276,6 +350,9 @@ function installFromGit(source, ref, scope) {
     }
     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`);
     }
     catch (error) {
         removePath(tempDir);
@@ -307,6 +384,9 @@ function installFromLocal(source, scope) {
         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();
     ensureScopeInitialized(scope, scopeRootPath);
     const destDir = join(scopeRootPath, 'plugins', manifest.name);
@@ -356,6 +436,9 @@ export function installFromMarketplace(ref, scope) {
     }
     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);
@@ -377,10 +460,11 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
     const sourceInstalled = isSourceInstalled(plugin);
     if (!sourceInstalled && plugin.manifest.bundle !== undefined) {
         const replaced = await replaceBundlePlugin(plugin.name, plugin.manifest.bundle, plugin.scope, { enable: plugin.enabled });
-        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, kinds: replaced.kinds, commands: replaced.commands };
+        return { name: plugin.name, transport: 'http', updated: true, version: replaced.version, docs: replaced.docs, kinds: replaced.kinds, pageComponents: replaced.pageComponents, commands: replaced.commands };
     }
     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;
     if (plugin.sourceMarketplace !== undefined) {
@@ -401,14 +485,44 @@ async function updateOnePlugin(plugin, marketplaceCache, opts) {
         contentUpdate = pullGitCheckout(plugin.root, `plugin "${plugin.name}"`, opts);
     }
     const manifest = readPluginManifest(plugin.root);
-    updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? manifest?.version);
+    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) ?? '' },
+                    });
+                }
+            }
+        }
+        throw error;
+    }
+    updatePluginVersion(plugin.scope, plugin.name, marketplaceVersion ?? manifest.version);
     const commands = await commandReport(plugin.name, plugin.scope);
+    const warnings = missingRequirementWarnings(manifest);
     return {
         name: plugin.name,
         ...(plugin.manifest.transport !== undefined ? { transport: plugin.manifest.transport.kind } : {}),
         updated: contentUpdate.updated,
         sha: contentUpdate.sha,
         ...(commands !== undefined ? { commands } : {}),
+        ...(warnings.length > 0 ? { warnings } : {}),
     };
 }
 export const pluginInstall = defineLeaf({
@@ -434,13 +548,16 @@ export const pluginInstall = defineLeaf({
             { 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: '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: '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',
         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 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, and any kind-registry entries the bundle.json declares (they join the launch registry below this scope\u2019s own config.json kinds); a fetch or validation failure preserves the prior package.',
+            '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.',
+            '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.',
         ],
     },
     run: async (input) => {
@@ -471,10 +588,12 @@ export const pluginInstall = defineLeaf({
                 : installFromGit(classified.value, gitRef, scope);
         const plugin = findPluginByName(installed.name, installed.scope);
         const commands = await commandReport(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 } : {}),
+            ...(warnings.length > 0 ? { warnings } : {}),
         };
     },
 });
@@ -586,7 +705,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?, commands?, 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, and kinds is the declared kind-registry entry 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[]}.' },
+            { 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.' },
         ],
         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.'],

package/dist/commands/profile/delete.js

@@ -1,12 +1,12 @@
 import { defineLeaf } from '../../core/command.js';
-import { deleteProfile, loadProfileManifest } from '../../core/profiles/manifest.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
 export const deleteLeaf = defineLeaf({
     name: 'delete',
-    description: 'remove a profile entirely',
-    whenToUse: 'a profile is no longer needed — deletes its manifest AND its own memory store irreversibly. Does not touch the project directories it pointed at.',
+    description: 'force-delete a profile and its owned runtime state',
+    whenToUse: 'a profile is no longer needed and you intend either to remove every node and schedule pinned to it, or to preserve that state while detaching the profile identity',
     help: {
         name: 'profile delete',
-        summary: 'remove a profile directory (manifest + memory store) after validating it exists',
+        summary: 'force-delete a profile and its owned state, or detach that state before removing the profile',
         params: [
             {
                 kind: 'positional',
@@ -14,26 +14,52 @@ export const deleteLeaf = defineLeaf({
                 required: true,
                 constraint: 'Exact profile id, or a unique manifest name.',
             },
+            {
+                kind: 'flag',
+                name: 'force',
+                type: 'bool',
+                required: true,
+                constraint: 'Required confirmation for this irreversible operation.',
+            },
+            {
+                kind: 'flag',
+                name: 'detach',
+                type: 'bool',
+                required: false,
+                constraint: 'Preserve nodes and inbox/review history; clear their profile identity and globalize matching crons before removing the profile.',
+            },
         ],
         output: [
-            { name: 'profile_id', type: 'string', required: true, constraint: 'The deleted profile\u2019s stable directory id.' },
-            { name: 'name', type: 'string', required: true, constraint: 'The deleted profile\u2019s manifest name.' },
-            { name: 'deleted', type: 'boolean', required: true, constraint: 'Always true on success.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+            { name: 'profile_id', type: 'string', required: true, constraint: 'The removed profile’s stable id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The removed profile’s manifest name.' },
+            { name: 'mode', type: 'string', required: true, constraint: '`deleted` for the destructive cascade; `detached` when --detach preserved nodes and history.' },
+            { name: 'nodes', type: 'number', required: true, constraint: 'Nodes hard-deleted or detached.' },
+            { name: 'crons', type: 'number', required: true, constraint: 'Crons deleted or globalized.' },
+            { name: 'tickets', type: 'number', required: true, constraint: 'Originating inbox ticket directories removed; zero in detach mode.' },
+            { name: 'reviews', type: 'number', required: true, constraint: 'Originating daemon review records removed; zero in detach mode.' },
+            { name: 'default_pins', type: 'number', required: true, constraint: 'Per-directory default profile pins cleared.' },
+            { name: 'accepted', type: 'boolean', required: false, constraint: 'True when the invoking node belongs to the profile and teardown begins after this result settles.' },
+            { name: 'grace_ms', type: 'number', required: false, constraint: 'Acknowledgement grace before an accepted self-deletion begins.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next action.' },
         ],
         outputKind: 'object',
         effects: [
-            'Recursively removes `<profiles-root>/<profile_id>/` — the manifest and its own memory store. Irreversible. Invalidates the process scope cache.',
+            'Always clears every per-directory default pin for the profile and removes the profile directory last. Blocks before mutation while any matching node owns an open managed worktree.',
+            'Without --detach: tears down and hard-deletes every node whose profile_id matches, deletes matching or anchored crons and their in-flight runs, and removes originating inbox tickets plus review records. Cross-profile children are preserved.',
+            'With --detach: preserves nodes, conversations, topology, inbox tickets, and reviews; rewrites node profile_id to null, restarts active brokers without the profile, and rewrites matching crons to global scope.',
         ],
     },
     run: async (input) => {
-        const { profileId, manifest } = loadProfileManifest(input['profile']);
-        deleteProfile(profileId);
+        const result = await cliClient().deleteProfile(input['profile'], {
+            force: input['force'],
+            detach: input['detach'],
+            caller_node_id: process.env['CRTR_NODE_ID'] ?? null,
+        }).catch(rethrowAsCliError);
         return {
-            profile_id: profileId,
-            name: manifest.name,
-            deleted: true,
-            follow_up: 'Run `crtr profile list` to see remaining profiles.',
+            ...result,
+            follow_up: result.accepted === true
+                ? 'The deletion was accepted; this node will stop after its result settles.'
+                : 'Run `crtr profile list` to see remaining profiles.',
         };
     },
 });

package/dist/commands/profile.js

@@ -30,7 +30,7 @@ export function registerProfile() {
         help: {
             name: 'profile',
             summary: 'create, inspect, and manage profiles \u2014 agent identities with their own project purview and memory store',
-            model: 'A profile owns a `home` — the first of its project dirs unless `project add --home` re-points it — and every node created under the profile is pinned there, so cwd selects the profile and the profile then supplies where its nodes run. Only `node new --cwd` (or inheriting a spawner already elsewhere, notably inside a managed worktree) overrides that; the root profile has no home, so nodes under it stay in the directory that created them. `new` creates one from a name (+ at most one initial `--project`, which becomes its home). `list` inventories every profile as JSONL. `show` prints one manifest in full. `rename` changes only the manifest name \u2014 the profile_id is stable across a rename. `delete` removes a profile\u2019s directory (manifest + its own memory store) entirely and does not touch the project directories it pointed at. `project` widens/narrows a profile\u2019s project purview (the dirs it resolves memory + config from). `default` pins which profile a directory defaults to at startup so the chooser stops asking \u2014 directory-scoped, independent of purview. `env` manages a profile-scoped 0600 store of env vars injected directly into every broker launched under that profile \u2014 set on stdin, list names only (never values), or remove one; no `spawnEnv.allow` entry needed. Every manifest verb but `new`/`list` takes <profile> as an exact id or a unique manifest name; an ambiguous name fails listing every matching id.',
+            model: 'A profile owns a `home` — the first of its project dirs unless `project add --home` re-points it — and every node created under the profile is pinned there, so cwd selects the profile and the profile then supplies where its nodes run. Only `node new --cwd` (or inheriting a spawner already elsewhere, notably inside a managed worktree) overrides that; the root profile has no home, so nodes under it stay in the directory that created them. `new` creates one from a name (+ at most one initial `--project`, which becomes its home). `list` inventories every profile as JSONL. `show` prints one manifest in full. `rename` changes only the manifest name \u2014 the profile_id is stable across a rename. `delete --force` removes the profile after cascading through its nodes, matching schedules, originating inbox/review state, and default pins; `--detach --force` instead preserves nodes and human history while clearing the profile identity and globalizing its schedules. Both modes block while a matching node owns an open managed worktree and never touch the project directories the profile pointed at. `project` widens/narrows a profile\u2019s project purview (the dirs it resolves memory + config from). `default` pins which profile a directory defaults to at startup so the chooser stops asking \u2014 directory-scoped, independent of purview. `env` manages a profile-scoped 0600 store of env vars injected directly into every broker launched under that profile \u2014 set on stdin, list names only (never values), or remove one; no `spawnEnv.allow` entry needed. Every manifest verb but `new`/`list` takes <profile> as an exact id or a unique manifest name; an ambiguous name fails listing every matching id.',
         },
         children: [newLeaf, listLeaf, showLeaf, renameLeaf, deleteLeaf, projectBranch, defaultBranch, envBranch],
     });

package/dist/commands/push.js

@@ -52,7 +52,7 @@ function makeTierLeaf(tier) {
             params: [
                 { kind: 'stdin', name: 'body', required: true, constraint: "Report body (markdown). Pipe it from a single-quoted heredoc (`<<'EOF'`) to preserve literal bytes." },
                 ...(tier === 'final'
-                    ? [{ kind: 'flag', name: 'force', type: 'bool', required: false, default: false, constraint: 'Override the guard that blocks `push final` on a human-attended node (a resident with no one to report up to). Only pass this after the user explicitly confirms they want this node finished.' }]
+                    ? [{ kind: 'flag', name: 'force', type: 'bool', required: false, default: false, constraint: 'Override the guard that blocks `push final` on a node the user is attending (a resident with no one to report up to). Only pass this after the user explicitly confirms they want this node finished.' }]
                     : []),
             ],
             output: [

package/dist/commands/surface/node/focus.js

@@ -1,15 +1,16 @@
 // `crtr surface node focus` — bring one viewer forward.
 import { defineLeaf } from '../../../core/command.js';
 import { InputError } from '../../../core/io.js';
+import { isFinishedWork, isLiveStatus } from '../../../core/canvas/node-order.js';
 import { cliClient, rethrowAsCliError } from '../../api-client.js';
 import { currentTmux, displayPopup, focusViewer, shellQuote } from './placement.js';
 export const surfaceNodeFocusLeaf = defineLeaf({
     name: 'focus',
     description: 'bring a node into view without accidentally reviving finished work',
-    whenToUse: 'you want to bring a specific node into view — live nodes open or move their viewer beside your current pane; completed, canceled, or crashed nodes open their saved transcript instead. Use `node lifecycle revive` only when you deliberately want to relaunch a dormant agent. Use `surface node cycle` to walk neighbors, and `node message send` to steer without leaving where you are',
+    whenToUse: 'you want to bring a specific node into view — a live node, or a resident agent that merely stopped, opens (resuming its saved conversation in place) beside your current pane; FINISHED work — a terminal worker, or any node that pushed a final report — opens its saved transcript instead of being put back to work. Use `node lifecycle revive` to deliberately relaunch finished work anyway. Use `surface node cycle` to walk neighbors, and `node message send` to steer without leaving where you are',
     help: {
         name: 'surface node focus',
-        summary: 'bring a node into view — attach to a live broker, or open a saved transcript for a non-live node without reviving it',
+        summary: 'bring a node into view — attach to a live broker, resume a resident agent that stopped, or open a saved transcript for finished work without reviving it',
         params: [
             { kind: 'positional', name: 'node', required: true, constraint: 'Node id to focus.' },
             { kind: 'flag', name: 'new-pane', type: 'bool', required: false, constraint: 'Always open a NEW viewer SIDE-BY-SIDE with your current pane instead of moving/reusing the node\'s existing viewer. Two agents on screen at once (F4).' },
@@ -19,11 +20,11 @@ export const surfaceNodeFocusLeaf = defineLeaf({
         output: [
             { name: 'focused', type: 'boolean', required: true, constraint: 'True when the node\'s viewer was brought into view.' },
             { name: 'session', type: 'string', required: false, constraint: 'The tmux session the viewer lives in.' },
-            { name: 'revived', type: 'boolean', required: true, constraint: 'True when focusing a live node had to relaunch its broker; false for a saved-transcript inspection.' },
+            { name: 'revived', type: 'boolean', required: true, constraint: 'True when focusing had to relaunch the node\'s broker (a live node whose engine was gone, or a stopped resident agent resumed in place); false when its viewer was already attached, and false for a saved-transcript inspection.' },
             { name: 'in_place', type: 'boolean', required: true, constraint: 'True when an existing viewer was navigated to (no new pane); false when a fresh viewer pane was opened or moved beside you.' },
         ],
         outputKind: 'object',
-        effects: ['For active/idle nodes: opens/moves the one surface-attach viewer beside the caller, or navigates to its existing viewer.', 'For done/dead/canceled nodes: opens a read-only saved transcript popup. It does not launch a broker or change node status.', 'With --new-pane/--in-place on a live node: controls whether the viewer splits beside or replaces the caller pane.'],
+        effects: ['For active/idle nodes: opens/moves the one surface-attach viewer beside the caller, or navigates to its existing viewer.', 'For a resident node that stopped without finalizing: resumes its saved conversation in place (status returns to active) and opens its viewer — the same path as a live node.', 'For finished work (a terminal node, or any node with a final report): opens a read-only saved transcript popup. It does not launch a broker or change node status.', 'With --new-pane/--in-place on a live node: controls whether the viewer splits beside or replaces the caller pane.'],
     },
     run: async (input) => {
         const id = input['node'];
@@ -38,17 +39,31 @@ 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; see it with \`crtr human list\`, or retract it with \`crtr human cancel ${id}\`.`,
+                next: `The pending question is queued for the user; 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
-        // no live broker to attach to, so show its persisted transcript in a popup;
-        // `node lifecycle revive` remains the explicit state-changing operation.
-        if (node.status !== 'active' && node.status !== 'idle') {
-            const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
-            const focused = pane !== undefined && pane !== ''
-                ? displayPopup(pane, node.cwd, `crtr node inspect transcript ${shellQuote(id)}`)
-                : false;
+        // Every focus needs a pane to place the viewer or popup into. Resolve it ONCE
+        // here and fail loudly when there is none: both downstream paths would
+        // otherwise return `focused: false` with no explanation, which reads as the
+        // command silently doing nothing.
+        const pane = input['pane'] ?? process.env['TMUX_PANE'] ?? currentTmux()?.pane;
+        if (pane === undefined || pane === '') {
+            throw new InputError({
+                error: 'no_pane',
+                message: `no tmux pane to focus ${id} into — surfaces need a tmux server, and this call has neither --pane nor a caller pane.`,
+                next: `Run it from inside tmux, pass \`--pane <id>\`, or read the node without a surface: \`crtr node inspect transcript ${id}\`.`,
+            });
+        }
+        // Opening history is not resuming work — but a non-live STATUS does not by
+        // itself mean the node finished anything. Finished work (a terminal worker, or
+        // any node that pushed a final report) is archive: show its persisted
+        // transcript, because reviving it would set completed work back in motion, and
+        // `node lifecycle revive` remains the explicit way to do that on purpose.
+        // A RESIDENT node with no final report never finished — its `done` is just a
+        // clean broker exit — so it falls through to the live path below, where
+        // ensureAttach's true resume replays the conversation exactly as it stood.
+        if (!isLiveStatus(node.status) && isFinishedWork({ lifecycle: node.lifecycle, finalized: node.final_report != null })) {
+            const focused = displayPopup(pane, node.cwd, `crtr node inspect transcript ${shellQuote(id)}`);
             return { focused, session: null, revived: false, in_place: false };
         }
         // Local viewer tail: open/move the broker-backed viewer beside the caller.
@@ -57,7 +72,7 @@ export const surfaceNodeFocusLeaf = defineLeaf({
         const res = await focusViewer(id, {
             cwd: node.cwd,
             name: node.name,
-            pane: input['pane'],
+            pane,
             newPane: input['newPane'] === true,
             inPlace: input['inPlace'] === true,
         });

package/dist/commands/surface-edit.js

@@ -69,10 +69,10 @@ const EDITOR_EXPR = '${EDITOR:-${VISUAL}}';
 export const surfaceEditLeaf = defineLeaf({
     name: 'edit',
     description: "open a file in the user's $EDITOR in a new pane beside the pane that opened this command",
-    whenToUse: "you (an agent) want the human to SEE a file WHILE THEY'RE WATCHING YOU — open it in their $EDITOR in a new pane split beside this node's viewer pane, without them hunting for it. Works headless (the broker reaches the tmux server over its socket). Requires this node to be on screen (a viewer open) or a caller pane; a background node with no viewer gets a no_pane error — report the path instead and it opens beside you once watched",
+    whenToUse: "you (an agent) want the user to SEE a file WHILE THEY'RE WATCHING YOU — open it in their $EDITOR in a new pane split beside this node's viewer pane, without them hunting for it. Works headless (the broker reaches the tmux server over its socket). Requires this node to be on screen (a viewer open) or a caller pane; a background node with no viewer gets a no_pane error — report the path instead and it opens beside you once watched",
     help: {
         name: 'surface edit',
-        summary: "Open <file> in a new pane running the user's $EDITOR (else $VISUAL), split beside THE PANE THAT OPENED THIS: an explicit --pane, the caller's own $TMUX_PANE, or this node's viewer pane (the pane where the human is watching it). Works from a HEADLESS broker (the tmux server is reached over its socket, no $TMUX needed). A background node with no viewer on screen has no pane to sit beside -> no_pane error. The split is -d, so focus is unchanged",
+        summary: "Open <file> in a new pane running the user's $EDITOR (else $VISUAL), split beside THE PANE THAT OPENED THIS: an explicit --pane, the caller's own $TMUX_PANE, or this node's viewer pane (the pane where the user is watching it). Works from a HEADLESS broker (the tmux server is reached over its socket, no $TMUX needed). A background node with no viewer on screen has no pane to sit beside -> no_pane error. The split is -d, so focus is unchanged",
         params: [
             {
                 kind: 'positional',
@@ -126,7 +126,7 @@ export const surfaceEditLeaf = defineLeaf({
             throw new InputError({
                 error: 'no_pane',
                 message: 'no pane to open the editor beside — this node has no viewer on screen (it is running in the background).',
-                next: 'Open a viewer on this node (`crtr surface node focus <id>` / `crtr surface attach`) and retry, pass --pane <pane-id>, or run from inside a tmux pane. To just point the human at a file, report its path instead.',
+                next: 'Open a viewer on this node (`crtr surface node focus <id>` / `crtr surface attach`) and retry, pass --pane <pane-id>, or run from inside a tmux pane. To just point the user at a file, report its path instead.',
             });
         }
         const command = `${EDITOR_EXPR} ${shellQuote(file)}`;

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

@@ -0,0 +1,2 @@
+import type { LeafDef } from '../core/command.js';
+export declare const surfaceInboxLeaf: LeafDef;

package/dist/commands/{human/inbox.js → surface-inbox.js}

@@ -1,5 +1,11 @@
-import { defineBranch, defineLeaf } from '../../core/command.js';
-import { currentTmux, displayClientMessage, liveViewerPanes, paneLocation, selectPane, selectWindow, sendAttachControl, switchClient, } from '../../core/runtime/placement-tmux.js';
+// `crtr surface inbox` — the tmux keybinding's target for the human inbox.
+//
+// A screen-facing viewer control, not a ticket verb: it delivers the private
+// attach-control action to one live viewer and focuses it. The human reaches
+// their own inbox through the inbox-toggle key (or `/inbox` in the viewer,
+// which toggles in-process and never shells out here).
+import { defineLeaf } from '../core/command.js';
+import { currentTmux, displayClientMessage, liveViewerPanes, paneLocation, selectPane, selectWindow, sendAttachControl, switchClient, } from '../core/runtime/placement-tmux.js';
 const NO_VIEWER_MESSAGE = 'No crouter viewer is running — attach to a node first (crtr surface attach to <node>).';
 function tmuxSocketFromEnvironment() {
     const socket = process.env['TMUX']?.split(',')[0]?.trim();
@@ -40,12 +46,13 @@ function focusViewer(viewer, targetPane, clientSession) {
     selectWindow(location.session, location.window);
     selectPane(viewer.pane);
 }
-const humanInboxToggle = defineLeaf({
-    name: 'toggle',
-    description: 'deliver the inbox toggle to a live viewer',
-    whenToUse: 'toggling the human inbox surface in a running crouter viewer; the selected viewer receives the private attach-control action and is focused afterward.',
+export const surfaceInboxLeaf = defineLeaf({
+    name: 'inbox',
+    description: 'human inbox toggle dispatcher (bound to the inbox-toggle key; not run by hand)',
+    whenToUse: 'never directly — the inbox-toggle keybinding routes the user’s own request through it. An agent that wants a decision uses crtr human send; how the user reaches their inbox is theirs.',
+    tier: 'hidden',
     help: {
-        name: 'human inbox toggle',
+        name: 'surface inbox',
         summary: 'deliver the human inbox toggle to a live viewer',
         guide: 'Selection prefers the target pane, then the resolved client session by newest viewer stamp, then newest globally; ties use pane id. The viewer decides whether the delivered toggle opens or closes the surface.',
         params: [
@@ -88,14 +95,3 @@ const humanInboxToggle = defineLeaf({
         return quiet ? undefined : outcome;
     },
 });
-export const humanInbox = defineBranch({
-    name: 'inbox',
-    description: 'deliver the human inbox toggle to a live viewer',
-    whenToUse: 'answering, reviewing, or managing pending human tickets from a running crouter viewer.',
-    help: {
-        name: 'human inbox',
-        summary: 'deliver the human inbox toggle to a live viewer',
-        model: 'The toggle leaf sends a private viewer control action; it never hosts the inbox itself.',
-    },
-    children: [humanInboxToggle],
-});

package/dist/commands/surface.js

@@ -8,6 +8,7 @@ import { surfaceEditLeaf } from './surface-edit.js';
 import { registerSurfaceNode } from './surface-node.js';
 import { surfaceInspectLeaf } from './surface-inspect.js';
 import { surfaceReloadLeaf } from './surface-reload.js';
+import { surfaceInboxLeaf } from './surface-inbox.js';
 export function registerSurface() {
     const attach = registerAttach('surface', 'important');
     return defineBranch({
@@ -22,6 +23,6 @@ export function registerSurface() {
             summary: 'open and manage screen-facing surfaces',
             model: 'Choose `node` for navigation among node viewers. The other commands open a broker attachment, node Inspector, subtree spread, reload, or adjacent editor pane.',
         },
-        children: [registerSurfaceNode(), attach, surfaceInspectLeaf, surfaceReloadLeaf, tmuxSpreadLeaf, surfaceEditLeaf],
+        children: [registerSurfaceNode(), attach, surfaceInspectLeaf, surfaceReloadLeaf, tmuxSpreadLeaf, surfaceEditLeaf, surfaceInboxLeaf],
     });
 }