@north-light/crouter 0.3.154

package/dist/commands/profile/delete.js

@@ -0,0 +1,39 @@
+import { defineLeaf } from '../../core/command.js';
+import { deleteProfile, loadProfileManifest } from '../../core/profiles/manifest.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.',
+    help: {
+        name: 'profile delete',
+        summary: 'remove a profile directory (manifest + memory store) after validating it exists',
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+        ],
+        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.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Recursively removes `<profiles-root>/<profile_id>/` — the manifest and its own memory store. Irreversible. Invalidates the process scope cache.',
+        ],
+    },
+    run: async (input) => {
+        const { profileId, manifest } = loadProfileManifest(input['profile']);
+        deleteProfile(profileId);
+        return {
+            profile_id: profileId,
+            name: manifest.name,
+            deleted: true,
+            follow_up: 'Run `crtr profile list` to see remaining profiles.',
+        };
+    },
+});

package/dist/commands/profile/env.d.ts

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

package/dist/commands/profile/env.js

@@ -0,0 +1,194 @@
+// `crtr profile env` — a profile-scoped store of env vars, injected directly
+// into every broker launched under that profile (`buildBrokerEnv`,
+// `core/runtime/spawn-env.ts`), independent of the daemon's own ambient env
+// or any `.envrc`/`.env` a node's cwd carries. Setting a value here IS the
+// consent to cross the spawn boundary — no matching `spawnEnv.allow` entry is
+// needed. Values are write-only from this surface: `set` and `remove` never
+// echo a value back, and `list` reports names only. See
+// `core/profiles/env-store.ts` for the on-disk (0600) store this wraps.
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { loadProfileManifest } from '../../core/profiles/manifest.js';
+import { validateEnvVarName } from '../../core/configured-clis/registration.js';
+import { listProfileEnvNames, setProfileEnvVar, removeProfileEnvVar } from '../../core/profiles/env-store.js';
+/** Strips exactly one trailing line ending (`\r\n` or `\n`) — the one
+ *  documented byte the piped-value contract trims — and leaves every other
+ *  byte (leading/trailing spaces, tabs, embedded newlines) untouched. A
+ *  single-quoted heredoc (`<<'EOF'`) always appends exactly one such
+ *  terminator; anything beyond that is content the caller wrote on purpose. */
+function stripSingleTrailingLineEnding(raw) {
+    if (raw.endsWith('\r\n'))
+        return raw.slice(0, -2);
+    if (raw.endsWith('\n'))
+        return raw.slice(0, -1);
+    return raw;
+}
+function requireValidName(name) {
+    const check = validateEnvVarName(name);
+    if (!check.isValid) {
+        throw new InputError({
+            error: 'invalid_name',
+            message: `invalid --name: ${check.errors.join('; ')}`,
+            field: 'name',
+            received: name,
+            next: 'Use an env-var-shaped name: starts with a letter or underscore, followed by letters, digits, or underscores.',
+        });
+    }
+}
+const setLeaf = defineLeaf({
+    name: 'set',
+    description: 'store one env var for a profile, value piped on stdin',
+    whenToUse: 'a profile needs a credential or config value injected directly into every broker launched under it \u2014 e.g. a configured CLI\u2019s `auth-env` token. Setting it here crosses the broker spawn boundary with no separate `spawnEnv.allow` entry required; re-running with the same name overwrites the value.',
+    help: {
+        name: 'profile env set',
+        summary: 'write (or overwrite) one env var in a profile\u2019s 0600 env store',
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: true,
+                constraint: 'Env var name. Must start with a letter or underscore, followed by letters, digits, or underscores (e.g. NL_CORE_TOKEN).',
+            },
+            {
+                kind: 'stdin',
+                name: 'value',
+                required: true,
+                constraint: 'The raw value, piped on stdin \u2014 never as an argv value, to keep it out of shell history. Pipe from a single-quoted heredoc (`<<\'EOF\'`) or `echo -n "$VALUE" |` to preserve exact bytes; trailing newline is trimmed.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The env var name written.' },
+            { name: 'created', type: 'boolean', required: true, constraint: 'true when this name was newly added, false when it replaced an existing value.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Writes {name: value} to the profile\u2019s 0600 env.json, replacing any prior value under the same name.',
+            'Every broker launched under this profile from now on injects this value directly into its process env \u2014 independent of the daemon\u2019s ambient env, no `spawnEnv.allow` entry needed. Already-running brokers keep whatever env they launched with; a running node picks up a new/changed value only on its next revive.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        requireValidName(name);
+        const { profileId } = loadProfileManifest(input['profile']);
+        const value = stripSingleTrailingLineEnding(input['value'] ?? '');
+        if (value === '') {
+            throw new InputError({
+                error: 'empty_value',
+                message: 'env var value is empty',
+                field: 'value',
+                next: 'Pipe a non-empty value on stdin.',
+            });
+        }
+        const created = setProfileEnvVar(profileId, name, value);
+        return {
+            profile_id: profileId,
+            name,
+            created,
+            follow_up: `List stored names with \`crtr profile env list ${profileId}\`. A running node under this profile picks up the change on its next revive.`,
+        };
+    },
+});
+const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'inventory a profile\u2019s stored env var NAMES \u2014 never values',
+    whenToUse: 'you want to know which env vars a profile has set, without exposing any value. Values never leave the 0600 store \u2014 there is no leaf that reads one back.',
+    help: {
+        name: 'profile env list',
+        summary: 'the sorted list of env var names stored for a profile',
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'names', type: 'string[]', required: true, constraint: 'Every stored env var name, sorted. Empty when nothing is stored.' },
+            { name: 'count', type: 'int', required: true, constraint: 'names.length.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only \u2014 and value-blind by construction: this leaf never reads the stored values.'],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const names = listProfileEnvNames(profileId);
+        return {
+            profile_id: profileId,
+            names,
+            count: names.length,
+            follow_up: names.length > 0
+                ? `Remove one with \`crtr profile env remove ${profileId} --name <name>\`.`
+                : `Set one with \`crtr profile env set ${profileId} --name <name>\`.`,
+        };
+    },
+});
+const removeLeaf = defineLeaf({
+    name: 'remove',
+    description: 'delete one stored env var from a profile',
+    whenToUse: 'an env var a profile owns is no longer needed \u2014 remove it so future brokers launched under this profile stop receiving it. No-op-shaped success (`removed: false`) if it was never set.',
+    help: {
+        name: 'profile env remove',
+        summary: 'delete one env var from a profile\u2019s 0600 env store',
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: true,
+                constraint: 'Env var name. Must start with a letter or underscore, followed by letters, digits, or underscores (e.g. NL_CORE_TOKEN).',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The env var name targeted.' },
+            { name: 'removed', type: 'boolean', required: true, constraint: 'true when a value existed and was removed; false when nothing was stored under this name.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Deletes {name} from the profile\u2019s 0600 env.json, if present.',
+            'Already-running brokers keep whatever env they launched with; a running node stops receiving this value only on its next revive.',
+        ],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const name = input['name'];
+        requireValidName(name);
+        const removed = removeProfileEnvVar(profileId, name);
+        return {
+            profile_id: profileId,
+            name,
+            removed,
+            follow_up: `List remaining names with \`crtr profile env list ${profileId}\`.`,
+        };
+    },
+});
+export const envBranch = defineBranch({
+    name: 'env',
+    description: 'manage a profile-scoped store of env vars injected into its brokers',
+    whenToUse: 'a profile needs a credential or config value available directly to every broker (and thus every node) launched under it \u2014 e.g. a configured CLI\u2019s `auth-env` token \u2014 without exporting it into the daemon\u2019s own ambient shell or granting a `spawnEnv.allow` passthrough.',
+    help: {
+        name: 'profile env',
+        summary: 'a profile\u2019s own 0600 store of env vars, injected directly into every broker launched under it',
+        model: 'Values are write-only from this surface: `set` stores one (value piped on stdin, never argv), `remove` deletes one, `list` reports NAMES only \u2014 no leaf ever reads a value back. `buildBrokerEnv` (`core/runtime/spawn-env.ts`) reads the store straight off disk at every broker launch and injects each value directly into that broker\u2019s process env, independent of the daemon\u2019s own ambient env or any `.envrc`/`.env` a node\u2019s cwd carries. Setting a value here IS the operator\u2019s consent to cross the spawn boundary \u2014 it needs no matching `spawnEnv.allow` entry. A change only reaches an already-running node on its next revive.',
+    },
+    children: [setLeaf, listLeaf, removeLeaf],
+});

package/dist/commands/profile/list.d.ts

@@ -0,0 +1 @@
+export declare const listLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/list.js

@@ -0,0 +1,35 @@
+import { defineLeaf } from '../../core/command.js';
+import { emitLine } from '../../core/io.js';
+import { listProfiles } from '../../core/profiles/manifest.js';
+export const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'inventory every profile',
+    whenToUse: 'browse every profile that exists — one line each with its id, name, project count, and last-used time. Reach for `profile show` once you have picked one, for its full project list.',
+    help: {
+        name: 'profile list',
+        summary: 'every profile as JSONL, one line each, sorted by name then profile_id',
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
+            { name: 'projects_count', type: 'int', required: true, constraint: 'Number of project directories on the manifest.' },
+            { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
+        ],
+        outputKind: 'jsonl',
+        effects: ['None. Read-only.'],
+    },
+    run: async () => {
+        const all = listProfiles().sort((a, b) => {
+            const nc = a.manifest.name.localeCompare(b.manifest.name);
+            return nc !== 0 ? nc : a.profileId.localeCompare(b.profileId);
+        });
+        for (const { profileId, manifest } of all) {
+            emitLine({
+                profile_id: profileId,
+                name: manifest.name,
+                projects_count: manifest.projects.length,
+                last_used_at: manifest.last_used_at,
+            });
+        }
+        emitLine({ follow_up: 'Show one in full with `crtr profile show <profile>`.' });
+    },
+});

package/dist/commands/profile/new.d.ts

@@ -0,0 +1 @@
+export declare const newLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/new.js

@@ -0,0 +1,75 @@
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { createProfile, ensureRootProfile, profileRoot } from '../../core/profiles/manifest.js';
+export const newLeaf = defineLeaf({
+    name: 'new',
+    description: 'create a new profile',
+    whenToUse: 'you are establishing a new agent identity — a stable id, a display name, and its own memory store. Pass at most one initial project directory here (the parser has no repeatable-flag support); use `profile project add` afterward for every additional one. Use `--root` (no name) to provision the canonical stable root profile — the default identity a home falls back to — idempotently, without spawning a node.',
+    help: {
+        name: 'profile new',
+        summary: 'create a profile: `<profiles-root>/<slug>-<id>/` with a manifest + its own `memory/` store',
+        params: [
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: false,
+                constraint: 'Display name for the profile. Also slugified into the stable profile id — the id never changes on later rename. Required unless `--root` is given; mutually exclusive with `--root`.',
+            },
+            {
+                kind: 'flag',
+                name: 'root',
+                type: 'bool',
+                required: false,
+                constraint: 'Provision the canonical stable root profile (fixed id `root-00000000`, name `root`) — the fallback default identity for a home — instead of a fresh named one. Idempotent: re-running returns the existing root. Node-free (no `node new --root` needed). Mutually exclusive with `--name`/`--project`.',
+            },
+            {
+                kind: 'flag',
+                name: 'project',
+                type: 'path',
+                required: false,
+                constraint: 'One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Singular — add more with `crtr profile project add` after creation.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id (`<slug>-<shortid>`). Pass this, or the name, to every other `profile` verb and to `--profile` elsewhere.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The manifest name as given.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the profile directory.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'Resolved absolute project directories, in manifest order. Empty when --project was omitted.' },
+            { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Creates `<profile-dir>/profile.json` and `<profile-dir>/memory/` (the fixed root dir when `--root`).'],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        const project = input['project'];
+        const root = input['root'] === true;
+        if (root) {
+            if (name !== undefined || project !== undefined) {
+                throw usage('`--root` provisions the canonical stable root profile and takes no `--name`/`--project`.');
+            }
+            const { profileId, manifest } = ensureRootProfile();
+            return {
+                profile_id: profileId,
+                name: manifest.name,
+                path: profileRoot(profileId),
+                projects: manifest.projects,
+                created_at: manifest.created_at,
+                follow_up: `Root profile ensured. Spawn nodes under it with \`--profile ${profileId}\`, or widen its purview with \`crtr profile project add ${profileId} --dir <path>\`.`,
+            };
+        }
+        if (name === undefined)
+            throw usage('provide `--name <name>` to create a profile, or `--root` to provision the stable root profile.');
+        const { profileId, manifest } = createProfile(name, project !== undefined ? [project] : []);
+        return {
+            profile_id: profileId,
+            name: manifest.name,
+            path: profileRoot(profileId),
+            projects: manifest.projects,
+            created_at: manifest.created_at,
+            follow_up: `Show it with \`crtr profile show ${profileId}\`, add another project with \`crtr profile project add ${profileId} --dir <path>\`, or list every profile with \`crtr profile list\`.`,
+        };
+    },
+});

package/dist/commands/profile/project.d.ts

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

package/dist/commands/profile/project.js

@@ -0,0 +1,97 @@
+// `crtr profile project` — the project-purview sub-noun of `profile`. A
+// profile's `projects` list is what it can SEE (memory + config resolution).
+// These two verbs widen or narrow that list after creation; `crtr profile
+// show` reads it back.
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { addProfileProject, removeProfileProject, loadProfileManifest } from '../../core/profiles/manifest.js';
+const addLeaf = defineLeaf({
+    name: 'add',
+    description: "add a project directory to a profile's purview",
+    whenToUse: "a profile needs to see (memory + config from) another project directory — extend its purview after creation, including mid-session from a node already running under that profile.",
+    help: {
+        name: 'profile project add',
+        summary: "append a project directory to a profile's manifest, deduped by real path",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+            {
+                kind: 'flag',
+                name: 'dir',
+                type: 'path',
+                required: true,
+                constraint: 'Directory to add. Must exist and be a directory; resolved to its absolute real path before storing. A path already on the manifest is a no-op, not an error.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'The updated, deduped project list in manifest order.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ["Appends to the profile manifest's `projects` array. Invalidates the process scope cache."],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const { manifest } = addProfileProject(profileId, input['dir']);
+        return {
+            profile_id: profileId,
+            projects: manifest.projects,
+            follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
+        };
+    },
+});
+const removeLeaf = defineLeaf({
+    name: 'remove',
+    description: "remove a project directory from a profile's purview",
+    whenToUse: "a profile no longer needs purview over one of its listed project directories — narrow it back. Works even if the directory itself was since deleted.",
+    help: {
+        name: 'profile project remove',
+        summary: "remove a project directory from a profile's manifest",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name.',
+            },
+            {
+                kind: 'flag',
+                name: 'dir',
+                type: 'path',
+                required: true,
+                constraint: 'Directory to remove, matched by its resolved real path against the manifest. Does not require the directory to still exist on disk.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'The updated project list in manifest order.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ["Removes an entry from the profile manifest's `projects` array. Invalidates the process scope cache."],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const { manifest } = removeProfileProject(profileId, input['dir']);
+        return {
+            profile_id: profileId,
+            projects: manifest.projects,
+            follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
+        };
+    },
+});
+export const projectBranch = defineBranch({
+    name: 'project',
+    description: "widen or narrow a profile's project purview",
+    whenToUse: "changing which project directories a profile can see (its memory + config resolution) after creation — add or remove one.",
+    help: {
+        name: 'profile project',
+        summary: "manage a profile's project purview — the directories it resolves memory and config from",
+        model: "A profile's `projects` list is the set of directories it inherits memory and config from. `add` widens that purview by one directory (deduped by real path); `remove` narrows it. Read the current list with `crtr profile show`. Purview is independent of a per-cwd default pin (`crtr profile default`) — widening purview never changes which profile a directory defaults to.",
+    },
+    children: [addLeaf, removeLeaf],
+});

package/dist/commands/profile/rename.d.ts

@@ -0,0 +1 @@
+export declare const renameLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/rename.js

@@ -0,0 +1,42 @@
+import { defineLeaf } from '../../core/command.js';
+import { loadProfileManifest, renameProfile } from '../../core/profiles/manifest.js';
+export const renameLeaf = defineLeaf({
+    name: 'rename',
+    description: "change a profile's display name",
+    whenToUse: "you want to change a profile's display name — the gateable `profile` subject value and the name shown in bearings/listings. The profile id (its directory) never changes.",
+    help: {
+        name: 'profile rename',
+        summary: "change a profile's manifest `name` only — the profile_id is stable and never changes",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name (the CURRENT name, before this rename).',
+            },
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: true,
+                constraint: 'New display name.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id — unchanged by this leaf.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The new manifest name.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ["Changes the profile manifest's `name` field. Invalidates the process scope cache."],
+    },
+    run: async (input) => {
+        const { profileId } = loadProfileManifest(input['profile']);
+        const { manifest } = renameProfile(profileId, input['name']);
+        return {
+            profile_id: profileId,
+            name: manifest.name,
+            follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
+        };
+    },
+});

package/dist/commands/profile/show.d.ts

@@ -0,0 +1 @@
+export declare const showLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/show.js

@@ -0,0 +1,50 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { loadProfileManifest, profileRoot } from '../../core/profiles/manifest.js';
+import { CONFIG_FILE } from '../../types.js';
+export const showLeaf = defineLeaf({
+    name: 'show',
+    description: "one profile's manifest in full",
+    whenToUse: "you need a profile's full project list, id, and timestamps — after `profile list` narrows to a name, or to inspect what a node's bearings named as its profile.",
+    help: {
+        name: 'profile show',
+        summary: "print one profile's manifest plus its on-disk path and config.json location",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name. An ambiguous name fails listing every matching id.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
+            { name: 'projects', type: 'string[]', required: true, constraint: 'Absolute project directories, in manifest order.' },
+            { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
+            { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the profile directory.' },
+            { name: 'config_path', type: 'string', required: true, constraint: 'Absolute path to the profile\'s config.json (hand-edited the same way as user/project config.json — no profile-specific editor verb exists).' },
+            { name: 'config_exists', type: 'boolean', required: true, constraint: 'Whether config.json exists at that path yet.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only.'],
+    },
+    run: async (input) => {
+        const { profileId, manifest } = loadProfileManifest(input['profile']);
+        const configPath = join(profileRoot(profileId), CONFIG_FILE);
+        return {
+            profile_id: profileId,
+            name: manifest.name,
+            projects: manifest.projects,
+            created_at: manifest.created_at,
+            last_used_at: manifest.last_used_at,
+            path: profileRoot(profileId),
+            config_path: configPath,
+            config_exists: existsSync(configPath),
+            follow_up: `Add a project with \`crtr profile project add ${profileId} --dir <path>\`, or rename with \`crtr profile rename ${profileId} --name <name>\`.`,
+        };
+    },
+});

package/dist/commands/profile.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerProfile(): BranchDef;

package/dist/commands/profile.js

@@ -0,0 +1,37 @@
+// `crtr profile` subtree — the profile store (spec §2.1/§2.5): agent
+// identities defined at the user root, each owning a manifest naming project
+// directories plus its own memory store.
+//
+// Five flat manifest verbs (new/list/show/rename/delete) plus three sub-nouns:
+// `project` (the profile's project purview), `default` (the per-cwd default
+// pin), and `env` (a profile-scoped store of env vars injected directly into
+// its brokers). Eight children — past the 5-7 soft cap, but `env` is a
+// coherent, self-contained sub-noun with no overlap against the existing six,
+// so it stays flat rather than inventing a deeper nest for one addition.
+// Every manifest verb but `new`/`list` takes <profile> as an exact id OR a
+// unique manifest name.
+import { defineBranch } from '../core/command.js';
+import { newLeaf } from './profile/new.js';
+import { listLeaf } from './profile/list.js';
+import { showLeaf } from './profile/show.js';
+import { renameLeaf } from './profile/rename.js';
+import { deleteLeaf } from './profile/delete.js';
+import { projectBranch } from './profile/project.js';
+import { defaultBranch } from './profile/default.js';
+import { envBranch } from './profile/env.js';
+export function registerProfile() {
+    return defineBranch({
+        name: 'profile',
+        rootEntry: {
+            concept: 'an agent identity defined at the user root — a manifest naming project directories plus its own memory store',
+            desc: 'create, inspect, and manage profiles',
+            useWhen: 'creating a new agent identity, inspecting or listing existing ones, changing a profile\u2019s project purview, pinning which profile a directory defaults to at startup, or managing a profile\u2019s stored env vars. Selecting a profile for a one-off run (`--profile`) lives elsewhere.',
+        },
+        help: {
+            name: 'profile',
+            summary: 'create, inspect, and manage profiles \u2014 agent identities with their own project purview and memory store',
+            model: '`new` creates one from a name (+ at most one initial `--project`). `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.',
+        },
+        children: [newLeaf, listLeaf, showLeaf, renameLeaf, deleteLeaf, projectBranch, defaultBranch, envBranch],
+    });
+}

package/dist/commands/push.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerPush(): BranchDef;