@north-light/crouter 0.3.214 → 0.3.216

package/dist/core/__tests__/canvas-inbox-watcher-hold.test.js

@@ -14,6 +14,7 @@ import { appendInbox, readCursor } from '../feed/inbox.js';
 import { drainBearings } from '../runtime/kickoff.js';
 import { appendSituationalContext } from '../runtime/situational-context.js';
 import { createNode, getNode, recordPid, setIntent } from '../canvas/canvas.js';
+import { createProfile, pauseProfile, resumeProfile } from '../profiles/manifest.js';
 import { closeDb } from '../canvas/db.js';
 import { createApiServer } from '../../daemon/api/server.js';
 import { CrtrClient } from '../../api/client.js';
@@ -257,6 +258,45 @@ describe('canvas inbox watcher — hold + idle delivery', () => {
         assert.equal(pi.injected.length, 1);
         assert.equal(pi.injected[0].deliverAs, undefined, 'idle → sendUserMessage triggers a turn, no deliverAs');
     });
+    // Pause makes the profile inert while its broker is still alive: the entry
+    // must be RETAINED, not consumed. A critical entry is the sharpest case —
+    // its route aborts the live turn, exactly the punch-through pause forbids.
+    test('a paused profile holds queued entries in a live broker until resume', async () => {
+        freshNode('node-paused-profile');
+        closeDb();
+        const origUserHome = process.env.HOME;
+        const origProfile = process.env['CRTR_PROFILE_ID'];
+        const userHome = join(tmpdir(), `crtr-w-home-${Math.random().toString(36).slice(2, 8)}`);
+        mkdirSync(userHome, { recursive: true });
+        homes.push(userHome);
+        process.env.HOME = userHome;
+        try {
+            const profile = createProfile('paused watcher', ['/tmp']);
+            pauseProfile(profile.profileId);
+            process.env['CRTR_PROFILE_ID'] = profile.profileId;
+            const pi = makeFakePi();
+            disposers.push(registerWatcher(pi));
+            await wait(TICK_MS + 100);
+            appendInbox('node-paused-profile', { from: 'child-1', tier: 'critical', kind: 'update', label: 'sent while paused' });
+            await wait(SETTLE_MS);
+            assert.equal(pi.injected.length, 0, 'a paused profile delivers nothing to its live broker');
+            assert.equal(readCursor('node-paused-profile'), undefined, 'the held entry stays unconsumed');
+            resumeProfile(profile.profileId);
+            await wait(SETTLE_MS);
+            assert.equal(pi.injected.length, 1, 'resume delivers the entry that waited');
+            assert.match(pi.injected[0].content, /sent while paused/);
+        }
+        finally {
+            if (origUserHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = origUserHome;
+            if (origProfile === undefined)
+                delete process.env['CRTR_PROFILE_ID'];
+            else
+                process.env['CRTR_PROFILE_ID'] = origProfile;
+        }
+    });
 });
 // Lifecycle-ordering regression (the live inbox-delivery startup loop): pi
 // deliberately makes action methods (sendUserMessage/sendMessage) throw until

package/dist/core/__tests__/parse-argv-stdin-secret.test.js

@@ -9,11 +9,39 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { parseArgv } from '../command.js';
+// Companion lock: `crtr node yield "note"`, `crtr push "done"` and 11 sibling
+// leaves declare a `stdin` body and NO positional param, and take that body as
+// one bare token. A parser refactor dropped the branch that accepts it while
+// leaving the resolution code below it intact, so every one of them exited 2
+// with empty stderr — caught only indirectly, two suites away.
+const YIELD_SHAPED_PARAMS = [
+    { kind: 'flag', name: 'promote', type: 'bool', required: false, constraint: 'promote too' },
+    { kind: 'stdin', name: 'message', required: true, constraint: 'note to your future self' },
+];
 const PROFILE_SET_SHAPED_PARAMS = [
     { kind: 'positional', name: 'profile', required: true, constraint: 'profile id' },
     { kind: 'flag', name: 'name', type: 'string', required: true, constraint: 'var name' },
     { kind: 'stdin', name: 'value', required: true, constraint: 'value piped on stdin' },
 ];
+test('a lone positional supplies the stdin body on a leaf declaring no positional param', async () => {
+    const result = await parseArgv(YIELD_SHAPED_PARAMS, ['refresh against the original goal']);
+    assert.equal(result['message'], 'refresh against the original goal');
+});
+test('flags parse alongside the positional that supplies the stdin body', async () => {
+    const result = await parseArgv(YIELD_SHAPED_PARAMS, ['--promote', 'coordinate the fan-out']);
+    assert.equal(result['message'], 'coordinate the fan-out');
+    assert.equal(result['promote'], true);
+});
+test('allowPositional:false keeps a stdin-only leaf rejecting positionals by arity', async () => {
+    const params = [
+        { kind: 'stdin', name: 'document', required: false, allowPositional: false, constraint: 'page source on stdin' },
+    ];
+    await assert.rejects(() => parseArgv(params, ['page.tsx']), (err) => {
+        assert.equal(err.code, 'bad_invocation');
+        assert.match(err.message, /takes no positional arguments/);
+        return true;
+    });
+});
 test('an extra positional on a stdin-bearing leaf is rejected without echoing it', async () => {
     const secret = 'SUPERSECRET_ARGV';
     await assert.rejects(() => parseArgv(PROFILE_SET_SHAPED_PARAMS, ['some-profile', secret, '--name', 'REVIEW_TOKEN']), (err) => {

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -127,9 +127,12 @@ test('an already idle resident with no live obligation reconciles into completed
         intent: 'idle-release',
         pi_session_id: 'parked-session',
     });
+    subscribe(root, nodeId, true);
     await h.tick();
     assert.equal(h.node(nodeId)?.status, 'done', 'an older idle row becomes pruning-eligible without needing a broker revive');
     assert.equal(h.node(nodeId)?.intent, 'done', 'the reconciled row records clean completion');
+    const wake = readInboxSince(root).find((entry) => entry.from === nodeId && entry.data?.['reason'] === 'child-auto-done');
+    assert.ok(wake, 'the subscribing root learns that the parked resident completed without a final report');
 });
 test('an unattended resident with no live obligation completes on the daemon clock', { timeout: 30_000 }, async () => {
     // The park clock is read per supervision pass (unattendedParkMsForDaemon), so
@@ -153,6 +156,7 @@ test('an unattended resident with no live obligation completes on the daemon clo
                 env: {},
             },
         });
+        subscribe(root, nodeId, true);
         reviveNode(nodeId, { resume: true });
         const boot = await h.awaitBoot(nodeId);
         assert.equal(h.fleet.has(nodeId), true, 'the revived broker is fleet-owned');
@@ -170,6 +174,9 @@ test('an unattended resident with no live obligation completes on the daemon clo
         await h.awaitFleetExit(nodeId);
         assert.equal(h.fleet.has(nodeId), false, 'exit policy forgets the completed broker');
         assert.equal(h.node(nodeId)?.status, 'done', 'the row is terminal and eligible for history pruning');
+        const wake = readInboxSince(root).find((entry) => entry.from === nodeId && entry.data?.['reason'] === 'child-auto-done');
+        assert.ok(wake, 'the subscribing root is woken when the unattended clock completes the resident');
+        assert.match(wake.label, /sent no final report/, 'the wake distinguishes automatic completion from a final report');
         await h.tick();
         assert.equal(h.fleet.has(nodeId), false, 'a supervision tick does not revive completed history');
     }

package/dist/core/command.js

@@ -301,7 +301,7 @@ export async function parseArgv(params, tokens, options) {
     const provided = new Set(); // Track explicitly-provided parameter names
     const contextFilePaths = new Map();
     // Index params by kind for quick lookup
-    const positionalParam = params.find((p) => p.kind === 'positional');
+    const positionalParams = params.filter((p) => p.kind === 'positional');
     const stdinParam = params.find((p) => p.kind === 'stdin');
     const contextFileParam = params.find((p) => p.kind === 'context-file');
     const flagParams = params.filter((p) => p.kind === 'flag');
@@ -316,7 +316,7 @@ export async function parseArgv(params, tokens, options) {
         }
     }
     const positionalValues = [];
-    const repeatablePositional = positionalParam?.repeatable === true;
+    let positionalIndex = 0;
     let positionalWasSupplied = false; // Track if positional came from argv (not stdin)
     let forcedPositional = false; // true after bare --
     let i = 0;
@@ -419,46 +419,50 @@ export async function parseArgv(params, tokens, options) {
             continue;
         }
         // Positional (or token after --)
-        if (repeatablePositional && positionalParam !== undefined) {
+        const positionalParam = positionalParams[positionalIndex];
+        if (positionalParam !== undefined) {
+            const key = flagNameToKey(positionalParam.name);
+            if (positionalParam.repeatable === true) {
+                const values = result[key] ?? [];
+                values.push(token);
+                result[key] = values;
+            }
+            else {
+                result[key] = token;
+                positionalIndex++;
+            }
             positionalValues.push(token);
             positionalWasSupplied = true;
+            provided.add(key);
             i++;
             continue;
         }
         if (positionalValues.length > 0) {
             // A leaf that also declares a `stdin` param treats its stdin value as
             // write-only/sensitive by convention (`profile env set`'s value, etc.).
-            // An unexpected extra positional here is the single most likely misuse
-            // of that contract — a caller typing the secret as an argv token instead
-            // of piping it — so never echo the token or the full argv back; a
-            // sensitive value must not be disclosed by the very error that rejects
-            // the mistake.
+            // An unexpected extra positional is the likely secret-as-argv mistake, so
+            // never echo it back in the rejection.
             if (stdinParam !== undefined) {
                 throw parseArgvError('bad_invocation', `unexpected extra positional argument (value withheld: this leaf reads "${stdinParam.name}" from stdin, never argv)`, undefined, undefined, `Pipe it on stdin instead of passing it as a positional argument.`);
             }
-            throw parseArgvError('bad_invocation', `unexpected extra positional argument: ${token}`, tokens.join(' '), undefined, 'Use --flag for parameters; only one positional allowed.');
+            throw parseArgvError('bad_invocation', `unexpected extra positional argument: ${token}`, tokens.join(' '), undefined, 'Use declared flags or positional parameters. Run -h for the schema.');
         }
-        // A bare positional is accepted when the leaf declares a positional param,
-        // or when its stdin parameter explicitly permits a positional body.
-        if (positionalParam === undefined && (stdinParam === undefined || stdinParam.allowPositional === false)) {
+        // A leaf declaring no positional param may still take one bare token as its
+        // stdin body (`crtr node yield "note"`); the resolution below turns it into
+        // the stdin value. `allowPositional: false` opts out.
+        if (positionalParams.length === 0 && (stdinParam === undefined || stdinParam.allowPositional === false)) {
             throw parseArgvError('bad_invocation', `this leaf takes no positional arguments: ${token}`, token, undefined, 'Use --flag for parameters. Run -h for the schema.');
         }
         positionalValues.push(token);
         positionalWasSupplied = true;
         i++;
     }
-    // Assign positional (already tracked in provided set above)
-    if (positionalValues.length > 0 && positionalParam !== undefined) {
-        result[flagNameToKey(positionalParam.name)] = repeatablePositional
-            ? positionalValues
-            : positionalValues[0];
-    }
     // Resolve stdin if declared. Some leaves permit one positional token to
     // supply the stdin body; `-` then means read stdin. A positional alongside
     // genuinely piped, non-empty stdin is ambiguous and errors loudly.
     let stdinWasSupplied = false;
     if (stdinParam !== undefined) {
-        if (positionalValues.length > 0 && positionalParam === undefined && stdinParam.allowPositional !== false) {
+        if (positionalValues.length > 0 && positionalParams.length === 0 && stdinParam.allowPositional !== false) {
             const positionalValue = positionalValues[0];
             if (positionalValue === '-') {
                 const raw = await readStdinRaw();
@@ -505,10 +509,6 @@ export async function parseArgv(params, tokens, options) {
             stdinWasSupplied = !stdinIsTTY || positionalWasSupplied;
         }
     }
-    // Track provided positional param
-    if (positionalWasSupplied && positionalParam !== undefined) {
-        provided.add(flagNameToKey(positionalParam.name));
-    }
     // Track provided stdin param
     if (stdinWasSupplied && stdinParam !== undefined) {
         provided.add(flagNameToKey(stdinParam.name));

package/dist/core/config.d.ts

@@ -141,6 +141,11 @@ export declare function readMergedLaunchConfig(targetCwd?: string, targetProfile
  *  existence/launch-menu enumeration is a caller concern); this only
  *  resolves the config for a kind the caller already knows about. */
 export declare function resolveKindConfig(kind: string): KindConfig | undefined;
+/** Reject a kind no scope registers. The one validation gate for every
+ *  surface that PERSISTS a kind (`profile new/kind`, the profile-ensure API
+ *  route) — a stored unknown kind would poison future omitted-kind creates
+ *  through `default_kind` resolution. */
+export declare function assertInstalledKind(kind: string): void;
 /** The sub-kinds available to spawn FROM a given top-level kind — every
  *  registered sub-kind (full path contains `/`) whose `availableTo` (default:
  *  its own top-level ancestor, e.g. `plan/reviewers/security` defaults to

package/dist/core/config.js

@@ -2,6 +2,7 @@ import { dirname, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, WHIP_MESSAGE_MODES, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
 import { BINDING_CATALOG, BINDING_IDS, isAttachPaneBinding } from './keybindings/catalog.js';
+import { usage } from './errors.js';
 import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
@@ -753,6 +754,20 @@ export function readMergedLaunchConfig(targetCwd = process.cwd(), targetProfileI
 export function resolveKindConfig(kind) {
     return readMergedLaunchConfig().kinds[kind];
 }
+/** Reject a kind no scope registers. The one validation gate for every
+ *  surface that PERSISTS a kind (`profile new/kind`, the profile-ensure API
+ *  route) — a stored unknown kind would poison future omitted-kind creates
+ *  through `default_kind` resolution. */
+export function assertInstalledKind(kind) {
+    const kinds = Object.keys(readMergedLaunchConfig().kinds).sort();
+    if (!kinds.includes(kind)) {
+        throw usage(`unknown kind: ${kind}`, {
+            received: kind,
+            field: 'kind',
+            next: `Valid kinds: ${kinds.join(', ')}.`,
+        });
+    }
+}
 /** The sub-kinds available to spawn FROM a given top-level kind — every
  *  registered sub-kind (full path contains `/`) whose `availableTo` (default:
  *  its own top-level ancestor, e.g. `plan/reviewers/security` defaults to

package/dist/core/help.d.ts

@@ -6,7 +6,7 @@ export interface Field {
      *  token caps. Lives here, never in a separate Preconditions section. */
     constraint: string;
 }
-/** Positional argument — at most one parameter per leaf; optionally repeatable. */
+/** Positional argument. A repeatable positional consumes every remaining positional token. */
 export interface PositionalParam {
     kind: 'positional';
     name: string;

package/dist/core/keybindings/attach-control.d.ts

@@ -13,6 +13,9 @@ export declare const ATTACH_CONTROL_BINDINGS: readonly [{
 }, {
     readonly menuId: "crtr.tmux.menu.attach.inbox.toggle";
     readonly actionId: "crtr.attach.inbox.toggle";
+}, {
+    readonly menuId: "crtr.tmux.menu.attach.inbox-strip";
+    readonly actionId: "crtr.attach.inbox-strip";
 }, {
     readonly menuId: "crtr.tmux.menu.attach.model-ladder.next";
     readonly actionId: "crtr.attach.model-ladder.next";

package/dist/core/keybindings/attach-control.js

@@ -4,6 +4,7 @@ export const ATTACH_CONTROL_BINDINGS = [
     { menuId: 'crtr.tmux.menu.attach.graph.toggle', actionId: 'crtr.attach.graph.toggle' },
     { menuId: 'crtr.tmux.menu.attach.help.toggle', actionId: 'crtr.attach.help.toggle' },
     { menuId: 'crtr.tmux.menu.attach.inbox.toggle', actionId: 'crtr.attach.inbox.toggle' },
+    { menuId: 'crtr.tmux.menu.attach.inbox-strip', actionId: 'crtr.attach.inbox-strip' },
     { menuId: 'crtr.tmux.menu.attach.model-ladder.next', actionId: 'crtr.attach.model-ladder.next' },
     { menuId: 'crtr.tmux.menu.attach.model-ladder.previous', actionId: 'crtr.attach.model-ladder.previous' },
     { menuId: 'crtr.tmux.menu.attach.command.inspect', actionId: 'crtr.attach.command.inspect' },

package/dist/core/keybindings/catalog.js

@@ -72,6 +72,7 @@ export const BINDING_CATALOG = Object.freeze([
     ...attachEntry('crtr.tmux.menu.attach.graph.toggle', 'crtr.attach.graph.toggle', 'Toggle graph', 'Open or close the graph overlay.', ['g'], ['alt+g']),
     ...attachEntry('crtr.tmux.menu.attach.help.toggle', 'crtr.attach.help.toggle', 'Help', 'Open the attach help overlay.', ['k'], ['alt+shift+k']),
     ...attachEntry('crtr.tmux.menu.attach.inbox.toggle', 'crtr.attach.inbox.toggle', 'Toggle inbox', 'Open or close the human inbox surface in this viewer.', ['i'], []),
+    ...attachEntry('crtr.tmux.menu.attach.inbox-strip', 'crtr.attach.inbox-strip', 'Pending requests', 'Jump to the pending human-request strip at the top of the pane.', ['u'], ['alt+u']),
     ...attachEntry('crtr.tmux.menu.attach.model-ladder.next', 'crtr.attach.model-ladder.next', 'Next model', 'Move to the next model ladder rung.', [']'], ['alt+m']),
     ...attachEntry('crtr.tmux.menu.attach.model-ladder.previous', 'crtr.attach.model-ladder.previous', 'Previous model', 'Move to the previous model ladder rung.', ['['], ['alt+shift+m']),
     ...attachEntry('crtr.tmux.menu.attach.command.inspect', 'crtr.attach.command.inspect', 'Inspect loaded command', 'Open the loaded slash command’s expanded prompt.', ['h'], ['alt+shift+h']),

package/dist/core/profiles/deletion-reservation.d.ts

@@ -2,7 +2,11 @@
  * The caller must release the returned lease after completion or failure. */
 export declare function reserveProfileDeletion(profileId: string): () => void;
 /** The synchronous birth gate. spawnNode calls this immediately before the
- * canvas row is persisted. A reservation rejects a birth that reaches the gate
- * during deletion; the exact manifest read rejects one whose async preflight
- * started before a fast hard deletion and resumed after its lease was released. */
+ * canvas row is persisted, so EVERY birth passes here — the API create, forks,
+ * cron spawns, warm-pool mints, `/new` relaunch, and recycle alike. A
+ * reservation rejects a birth that reaches the gate during deletion; the exact
+ * manifest read rejects one whose async preflight started before a fast hard
+ * deletion and resumed after its lease was released; a paused profile is inert
+ * and creates nothing. `POST /v1/nodes` gates earlier only to phrase the paused
+ * refusal against the operand the caller actually typed. */
 export declare function assertProfileAvailableForBirth(profileId: string | null): void;

package/dist/core/profiles/deletion-reservation.js

@@ -1,5 +1,5 @@
 import { usage } from '../errors.js';
-import { loadExactProfileManifest } from './manifest.js';
+import { assertProfileEntryActive, loadExactProfileManifest } from './manifest.js';
 const deletingProfileIds = new Set();
 /** Reserve one profile identity for its complete daemon-owned deletion lifecycle.
  * The caller must release the returned lease after completion or failure. */
@@ -21,9 +21,13 @@ export function reserveProfileDeletion(profileId) {
     };
 }
 /** The synchronous birth gate. spawnNode calls this immediately before the
- * canvas row is persisted. A reservation rejects a birth that reaches the gate
- * during deletion; the exact manifest read rejects one whose async preflight
- * started before a fast hard deletion and resumed after its lease was released. */
+ * canvas row is persisted, so EVERY birth passes here — the API create, forks,
+ * cron spawns, warm-pool mints, `/new` relaunch, and recycle alike. A
+ * reservation rejects a birth that reaches the gate during deletion; the exact
+ * manifest read rejects one whose async preflight started before a fast hard
+ * deletion and resumed after its lease was released; a paused profile is inert
+ * and creates nothing. `POST /v1/nodes` gates earlier only to phrase the paused
+ * refusal against the operand the caller actually typed. */
 export function assertProfileAvailableForBirth(profileId) {
     if (profileId === null)
         return;
@@ -34,5 +38,5 @@ export function assertProfileAvailableForBirth(profileId) {
             next: 'Choose another profile or wait for this deletion to finish.',
         });
     }
-    loadExactProfileManifest(profileId);
+    assertProfileEntryActive(loadExactProfileManifest(profileId));
 }

package/dist/core/profiles/manifest.d.ts

@@ -39,8 +39,46 @@ export declare function loadProfileManifest(profileIdOrName: string): ProfileEnt
  *  below run inside this. */
 export declare function withProfileManifestLock<T>(profileId: string, fn: () => T): T;
 export declare function ensureRootProfile(): ProfileEntry;
-export declare function createProfile(name: string, projects?: string[]): ProfileEntry;
+/** The env name a metadata entry surfaces as (spawn-env source F). Also the
+ *  uniqueness domain for keys: the fold is lossy (`a-b`, `a_b`, `A_B` →
+ *  `CRTR_PROFILE_META_A_B`), so two stored keys may not share a fold. */
+export declare function metadataEnvName(key: string): string;
+/** Reject anything a valid metadata map may not carry. Takes `unknown`
+ *  because the API route hands over a caller-supplied body slice — the
+ *  TypeScript type on the DTO proves nothing at runtime. */
+export declare function assertProfileMetadata(entries: unknown): asserts entries is Record<string, string>;
+/** Drop entries no valid mutation could have written — a manifest is
+ *  hand-editable, so a projection or merge base must never trust it raw.
+ *  Never throws; on an env-name collision the first entry wins (matching
+ *  injection, where a deterministic winner beats insertion-order luck). */
+export declare function sanitizeProfileMetadata(stored: unknown): Record<string, string>;
+export declare function createProfile(name: string, projects?: string[], opts?: {
+    defaultKind?: string;
+    metadata?: Record<string, string>;
+}): ProfileEntry;
 export declare function updateProfileLastUsed(profileId: string): ProfileEntry;
+/** Paused check for an ALREADY-RESOLVED durable id (a canvas row's `profile_id`,
+ * `CRTR_PROFILE_ID`) — exact-id only, no name matching, so it costs one small
+ * read on the hot delivery paths that call it every poll. Fails OPEN: an id
+ * whose manifest is missing or corrupt is not paused, because treating it as
+ * paused would strand that node's queued inbox forever. */
+export declare function isProfilePaused(profileId: string | null | undefined): boolean;
+/** Refuse a launch under a paused profile, naming the resume command. Shared by
+ * every gate that already holds a loaded manifest. */
+export declare function assertProfileEntryActive(entry: ProfileEntry): void;
+export declare function assertProfileActive(profileId: string | null | undefined): ProfileEntry | null;
+export declare function pauseProfile(profileId: string): ProfileEntry;
+export declare function resumeProfile(profileId: string): ProfileEntry;
+export declare function setProfileDefaultKind(profileId: string, defaultKind: string): ProfileEntry;
+/** Merge `set` entries over the stored map and drop `unset` keys; the
+ *  `metadata` field is omitted entirely when the result is empty. */
+export declare function updateProfileMetadata(profileId: string, set: Record<string, string>, unset?: string[]): ProfileEntry;
+/** A profile's stored metadata for broker-env injection — sanitized entry by
+ *  entry (a manifest is hand-editable, so a bad key/value is dropped rather
+ *  than trusted) and never throwing: a stale/invalid/absent profile id is a
+ *  hot-path no-op, because broker-env resolution must never fail a launch
+ *  over a bad profile id (mirrors `readProfileEnvVars`). */
+export declare function readProfileMetadata(profileId: string | null): Record<string, string>;
 export declare function renameProfile(profileId: string, name: string): ProfileEntry;
 export declare function addProfileProject(profileId: string, dir: string, opts?: {
     home?: boolean;

package/dist/core/profiles/manifest.js

@@ -84,9 +84,9 @@ export function profileMemoryDir(profileId) {
  *  the user started them, not in whatever dir was last added to its purview. */
 function normalizeHome(profileId, manifest) {
     const stored = typeof manifest.home === 'string' && manifest.home !== '' ? manifest.home : null;
-    if (profileId === ROOT_PROFILE_ID)
-        return { ...manifest, home: stored };
-    return { ...manifest, home: stored ?? manifest.projects[0] ?? null };
+    const home = profileId === ROOT_PROFILE_ID ? stored : stored ?? manifest.projects[0] ?? null;
+    const pausedAt = typeof manifest.paused_at === 'string' && manifest.paused_at !== '' ? manifest.paused_at : null;
+    return { ...manifest, home, paused_at: pausedAt };
 }
 function readManifestFile(path, profileId) {
     if (!existsSync(path))
@@ -282,6 +282,7 @@ export function ensureRootProfile() {
             name: ROOT_PROFILE_NAME,
             projects: [],
             home: null,
+            paused_at: null,
             created_at: nowIso(),
             last_used_at: nowIso(),
         };
@@ -290,10 +291,89 @@ export function ensureRootProfile() {
         return { profileId: ROOT_PROFILE_ID, manifest: next };
     });
 }
-export function createProfile(name, projects = []) {
+/** Key shape every stored metadata entry must satisfy — kept env-mappable
+ *  (`CRTR_PROFILE_META_<KEY>`, see `core/runtime/spawn-env.ts`) by
+ *  construction. */
+const METADATA_KEY_SHAPE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/** The env name a metadata entry surfaces as (spawn-env source F). Also the
+ *  uniqueness domain for keys: the fold is lossy (`a-b`, `a_b`, `A_B` →
+ *  `CRTR_PROFILE_META_A_B`), so two stored keys may not share a fold. */
+export function metadataEnvName(key) {
+    return `CRTR_PROFILE_META_${key.toUpperCase().replace(/[^A-Z0-9]+/g, '_')}`;
+}
+/** Reject anything a valid metadata map may not carry. Takes `unknown`
+ *  because the API route hands over a caller-supplied body slice — the
+ *  TypeScript type on the DTO proves nothing at runtime. */
+export function assertProfileMetadata(entries) {
+    if (typeof entries !== 'object' || entries === null || Array.isArray(entries)) {
+        throw usage('metadata must be a map of string keys to string values', {
+            field: 'metadata',
+            next: 'Pass an object, e.g. {"role": "support"}.',
+        });
+    }
+    const claimed = new Map();
+    for (const [key, value] of Object.entries(entries)) {
+        if (!METADATA_KEY_SHAPE.test(key)) {
+            throw usage(`invalid metadata key: ${JSON.stringify(key)}`, {
+                received: key,
+                field: 'metadata',
+                next: 'Keys start with a letter or digit, followed by letters, digits, `_`, or `-`.',
+            });
+        }
+        if (typeof value !== 'string') {
+            throw usage(`metadata value for ${key} must be a string`, {
+                received: typeof value,
+                field: 'metadata',
+                next: 'Every metadata value is an env-var value — pass strings only.',
+            });
+        }
+        if (value.includes('\0')) {
+            throw usage(`metadata value for ${key} contains a NUL byte, which no OS accepts in an environment variable`, {
+                field: 'metadata',
+                next: 'Remove NUL bytes from the value and retry.',
+            });
+        }
+        const envName = metadataEnvName(key);
+        const prior = claimed.get(envName);
+        if (prior !== undefined) {
+            throw usage(`metadata keys ${JSON.stringify(prior)} and ${JSON.stringify(key)} both surface as ${envName}`, {
+                field: 'metadata',
+                next: 'Rename or drop one — keys must stay distinct after uppercasing and `_`-folding.',
+            });
+        }
+        claimed.set(envName, key);
+    }
+}
+/** Drop entries no valid mutation could have written — a manifest is
+ *  hand-editable, so a projection or merge base must never trust it raw.
+ *  Never throws; on an env-name collision the first entry wins (matching
+ *  injection, where a deterministic winner beats insertion-order luck). */
+export function sanitizeProfileMetadata(stored) {
+    if (typeof stored !== 'object' || stored === null || Array.isArray(stored))
+        return {};
+    const out = {};
+    const claimed = new Set();
+    for (const [key, value] of Object.entries(stored)) {
+        if (typeof value !== 'string')
+            continue;
+        if (!METADATA_KEY_SHAPE.test(key))
+            continue;
+        if (value.includes('\0'))
+            continue;
+        const envName = metadataEnvName(key);
+        if (claimed.has(envName))
+            continue;
+        claimed.add(envName);
+        out[key] = value;
+    }
+    return out;
+}
+export function createProfile(name, projects = [], opts = {}) {
     const trimmed = name.trim();
     if (trimmed === '')
         throw usage('profile name must not be empty');
+    if (opts.metadata !== undefined)
+        assertProfileMetadata(opts.metadata);
     const resolvedProjects = dedupeOrdered(projects.map(resolveExistingProjectDir));
     const profileId = generateProfileId(trimmed);
     return withProfileManifestLock(profileId, () => {
@@ -302,6 +382,9 @@ export function createProfile(name, projects = []) {
             name: trimmed,
             projects: resolvedProjects,
             home: resolvedProjects[0] ?? null,
+            paused_at: null,
+            ...(opts.defaultKind !== undefined ? { default_kind: opts.defaultKind } : {}),
+            ...(opts.metadata !== undefined && Object.keys(opts.metadata).length > 0 ? { metadata: { ...opts.metadata } } : {}),
             created_at: nowIso(),
             last_used_at: null,
         };
@@ -335,6 +418,90 @@ function mutateManifest(profileId, mutate) {
 export function updateProfileLastUsed(profileId) {
     return mutateManifest(profileId, (m) => ({ ...m, last_used_at: nowIso() }));
 }
+/** Resolve an existing profile for a launch gate without making stale durable
+ * profile ids a new failure mode on a hot path. */
+function loadProfileManifestOrNull(profileId) {
+    if (profileId === null || profileId === undefined || profileId === '')
+        return null;
+    try {
+        return loadProfileManifest(profileId);
+    }
+    catch {
+        return null;
+    }
+}
+/** Paused check for an ALREADY-RESOLVED durable id (a canvas row's `profile_id`,
+ * `CRTR_PROFILE_ID`) — exact-id only, no name matching, so it costs one small
+ * read on the hot delivery paths that call it every poll. Fails OPEN: an id
+ * whose manifest is missing or corrupt is not paused, because treating it as
+ * paused would strand that node's queued inbox forever. */
+export function isProfilePaused(profileId) {
+    if (profileId === null || profileId === undefined || profileId === '')
+        return false;
+    try {
+        return loadExactProfileManifest(profileId).manifest.paused_at !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/** Refuse a launch under a paused profile, naming the resume command. Shared by
+ * every gate that already holds a loaded manifest. */
+export function assertProfileEntryActive(entry) {
+    if (entry.manifest.paused_at === null)
+        return;
+    throw usage(`profile "${entry.manifest.name}" is paused and cannot start nodes`, {
+        received: entry.profileId,
+        next: `Resume it with \`crtr profile resume ${entry.profileId}\`.`,
+    });
+}
+export function assertProfileActive(profileId) {
+    const entry = loadProfileManifestOrNull(profileId);
+    if (entry === null)
+        return null;
+    assertProfileEntryActive(entry);
+    return entry;
+}
+export function pauseProfile(profileId) {
+    return mutateManifest(profileId, (m) => ({ ...m, paused_at: m.paused_at ?? nowIso() }));
+}
+export function resumeProfile(profileId) {
+    return mutateManifest(profileId, (m) => ({ ...m, paused_at: null }));
+}
+export function setProfileDefaultKind(profileId, defaultKind) {
+    return mutateManifest(profileId, (m) => ({ ...m, default_kind: defaultKind }));
+}
+/** Merge `set` entries over the stored map and drop `unset` keys; the
+ *  `metadata` field is omitted entirely when the result is empty. */
+export function updateProfileMetadata(profileId, set, unset = []) {
+    assertProfileMetadata(set);
+    return mutateManifest(profileId, (m) => {
+        const next = { ...sanitizeProfileMetadata(m.metadata), ...set };
+        for (const key of unset)
+            delete next[key];
+        // Re-assert the merged result: a set key may collide with a STORED key in
+        // the env-name domain (`a-b` over stored `a_b`), which per-argument
+        // validation cannot see.
+        assertProfileMetadata(next);
+        const { metadata: _dropped, ...rest } = m;
+        return { ...rest, ...(Object.keys(next).length > 0 ? { metadata: next } : {}) };
+    });
+}
+/** A profile's stored metadata for broker-env injection — sanitized entry by
+ *  entry (a manifest is hand-editable, so a bad key/value is dropped rather
+ *  than trusted) and never throwing: a stale/invalid/absent profile id is a
+ *  hot-path no-op, because broker-env resolution must never fail a launch
+ *  over a bad profile id (mirrors `readProfileEnvVars`). */
+export function readProfileMetadata(profileId) {
+    if (profileId === null || profileId === '')
+        return {};
+    try {
+        return sanitizeProfileMetadata(loadExactProfileManifest(profileId).manifest.metadata);
+    }
+    catch {
+        return {};
+    }
+}
 export function renameProfile(profileId, name) {
     const trimmed = name.trim();
     if (trimmed === '')

package/dist/core/runtime/boot-root.js

@@ -30,7 +30,7 @@ export async function bootRoot(opts) {
     if (!inTmux()) {
         throw new Error('crtr must be started from inside a tmux session — start tmux first (e.g. `tmux new -s work`), then run `crtr` there.');
     }
-    const kind = opts.kind ?? 'general';
+    const kind = opts.kind;
     // The front door's only source of profile identity — a root has no spawner to
     // inherit from. Runs BEFORE the create call: explicit --profile > MRU profile
     // covering cwd > a synchronous create-or-root-profile prompt (the stable root
@@ -47,12 +47,12 @@ export async function bootRoot(opts) {
     // viewer paints the crouton banner the instant the engine attaches (~1s),
     // which is the real "we're up" signal.
     const detail = await cliClient().createNode({
-        kind,
+        ...(kind !== undefined ? { kind } : {}),
         mode: 'base',
         prompt: opts.prompt,
         profile: profileId,
         cwd: opts.cwd,
-        name: opts.name ?? kind,
+        ...(opts.name !== undefined ? { name: opts.name } : kind !== undefined ? { name: kind } : {}),
         root: true,
         // The front door is exactly the wait a warm spare exists to remove: a bare
         // resident root with no kickoff. A miss costs nothing (cold spawn) and