@crouter/api 0.3.387 → 0.3.389

package/dist/core/profiles/manifest.js

@@ -0,0 +1,529 @@
+// Profile definitions live in scoped state; memory and environment have separate roots.
+import { randomUUID } from 'node:crypto';
+import { existsSync, realpathSync, rmSync, statSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+import { SCHEMA_VERSION } from '../../types.js';
+import { profileSpace } from '../layout.js';
+import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
+import { userScopeRoot } from '../scope.js';
+import { ensureDir, nowIso } from '../fs-utils.js';
+import { deleteStoredProfile, getStoredProfile, insertStoredProfile, listStoredProfiles, pausedProfileIds, profilePaused, updateStoredProfile } from '../scoped-state/profiles.js';
+import { usage, notFound, ambiguous, general } from '../errors.js';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
+import { fuzzyMatchProfile } from './fuzzy-match.js';
+// A generated id and its stored app determine the memory and environment paths.
+/** `<slug>-<shortid>`: slug is lower-case, non-alphanumeric collapsed to `-`,
+ *  trimmed to 40 chars (defaulting to `profile`); shortid is 8 lowercase hex
+ *  chars. The char class alone rules out `/`, `\`, `.`, and `..` segments —
+ *  this is the "generated id shape" check every exact-id lookup requires. */
+const ID_SHAPE = /^[a-z0-9]+(?:-[a-z0-9]+)*-[0-9a-f]{8}$/;
+export const ROOT_PROFILE_ID = 'root-00000000';
+const ROOT_PROFILE_NAME = 'root';
+function profileApp(manifest) { return manifest.grantee ?? 'app:terminal'; }
+function scaffoldProfile(profileId, manifest) {
+    ensureDir(profileSpace(profileApp(manifest), profileId).memory);
+}
+function assertSafeProfileId(profileId) {
+    if (!ID_SHAPE.test(profileId)) {
+        throw usage(`invalid profile id: ${profileId}`, {
+            received: profileId,
+            next: 'Profile ids look like <slug>-<8-hex-chars> (as printed by `crtr profile new`). Pass an exact id or a profile name, not a raw path.',
+        });
+    }
+}
+export function profileMemoryDir(profileId) {
+    assertSafeProfileId(profileId);
+    const stored = getStoredProfile(userScopeRoot(), profileId);
+    if (stored === null)
+        throw notFound(`profile not found: ${profileId}`, { received: profileId });
+    return profileSpace(profileApp(stored.manifest), profileId).memory;
+}
+// Profile operands resolve against the scoped-state rows.
+export function assertProfileProjects(entries) {
+    if (!Array.isArray(entries))
+        throw usage('projects must be an array of {path} objects', { received: typeof entries, field: 'projects', next: 'Pass entries like {"path": "/abs/dir"}.' });
+    for (const entry of entries) {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry))
+            throw usage(`invalid project entry: ${JSON.stringify(entry)}`, { field: 'projects', next: 'Every project is an object like {"path": "/abs/dir"}.' });
+        const { path } = entry;
+        if (typeof path !== 'string' || path.trim() === '')
+            throw usage(`project entry has no path: ${JSON.stringify(entry)}`, { field: 'projects', next: 'Give every project entry a non-empty directory path.' });
+    }
+}
+export function assertDeliveryLimits(value) {
+    const levels = PROFILE_PROJECT_MEMORY_VALUES.join(', ');
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw usage('delivery_limits must be an object mapping owner handles to a level', { received: typeof value, field: 'delivery_limits', next: `Pass e.g. {"crouter": "preview"} — each level is one of: ${levels}.` });
+    for (const [handle, level] of Object.entries(value)) {
+        if (handle.trim() === '')
+            throw usage('delivery_limits has an empty owner handle', { field: 'delivery_limits', next: 'Key each limit by an owner handle such as a repo handle or `user`, or exactly by `<type>:<handle>` such as `repo:crouter`.' });
+        if (typeof level !== 'string' || !PROFILE_PROJECT_MEMORY_VALUES.includes(level))
+            throw usage(`invalid delivery limit for ${handle}: ${JSON.stringify(level)}`, { received: String(level), field: 'delivery_limits', next: `Set ${handle} to one of: ${levels}.` });
+    }
+}
+function enumerateProfiles() { return { entries: listStoredProfiles(userScopeRoot()), unreadableIds: [] }; }
+export function listProfiles() { return enumerateProfiles().entries; }
+export function lookupProfile(profileIdOrName) { const entries = listProfiles(); const exact = findExactProfile(entries, profileIdOrName, entryCandidate); return exact ? { kind: 'resolved', entry: exact } : { kind: 'absent' }; }
+// Three resolvers, in descending tolerance. `resolveProfileOperand` is what a
+// command leaf calls for a value the USER TYPED: exact id, exact name, then a
+// fuzzy fallback. `loadProfileManifest` is the strict middle — exact id or
+// exact name, no guessing — and is what every runtime consumer holding a
+// stored `profile_id` or `CRTR_PROFILE_ID` calls. `loadExactProfileManifest`
+// skips name matching entirely, for persistence gates already holding a
+// resolved durable identity. Exact-id lookup validates the generated id.
+/** Read one exact profile id without falling back to manifest-name matching.
+ * Used at persistence gates that already hold a resolved durable identity. */
+export function loadExactProfileManifest(profileId) {
+    assertSafeProfileId(profileId);
+    const stored = getStoredProfile(userScopeRoot(), profileId);
+    if (stored !== null)
+        return stored;
+    throw notFound(`profile not found: ${profileId}`, { received: profileId, next: 'Run `crtr profile list` to see available profiles.' });
+}
+const entryCandidate = (p) => ({ profileId: p.profileId, name: p.manifest.name });
+function findExactProfile(all, profileIdOrName, key) {
+    if (ID_SHAPE.test(profileIdOrName)) {
+        const byId = all.find((p) => key(p).profileId === profileIdOrName);
+        if (byId !== undefined)
+            return byId;
+    }
+    const byName = all.filter((p) => key(p).name === profileIdOrName);
+    if (byName.length === 1)
+        return byName[0];
+    if (byName.length > 1) {
+        const ids = byName.map((p) => key(p).profileId);
+        throw ambiguous(`profile name "${profileIdOrName}" matches ${ids.length} profiles: ${ids.join(', ')}`, {
+            received: profileIdOrName,
+            candidates: ids,
+            next: `Re-run with one exact profile id: ${ids.join(', ')}.`,
+        });
+    }
+    return null;
+}
+/** Name the actual value set in the failure: a caller that guessed an id or a
+ *  stale name can correct itself from this error alone, without a lookup hop. */
+function profileNotFound(all, profileIdOrName, key) {
+    const available = all.map((p) => `${key(p).profileId} (${key(p).name})`);
+    return notFound(`profile not found: ${profileIdOrName}`, {
+        received: profileIdOrName,
+        available,
+        next: available.length > 0
+            ? `Re-run with one of the profiles on this host: ${available.join(', ')} — or create one with \`crtr profile new --name <name>\`.`
+            : 'No profiles exist on this host yet — create one with `crtr profile new --name <name>`.',
+    });
+}
+export function loadProfileManifest(profileIdOrName) {
+    const lookup = lookupProfile(profileIdOrName);
+    if (lookup.kind === 'resolved')
+        return lookup.entry;
+    // Unreadable and absent both answer not-found here: this is the tolerant
+    // resolver every runtime consumer already handles that way. A caller that
+    // must NOT substitute another identity calls `lookupProfile` directly.
+    throw profileNotFound(listProfiles(), profileIdOrName, entryCandidate);
+}
+/** Resolve a profile the USER TYPED — a `--profile` flag or a `<profile>`
+ *  operand. Exact id or name wins outright; only when nothing matches exactly
+ *  does this fall back to fuzzy matching on name and id slug, so a typed
+ *  `crout`, `Crouter`, or `cruoter` reaches the `crouter` profile instead of
+ *  failing with a list the user has to read and retype. A fuzzy hit is
+ *  announced on STDERR (never stdout, which callers pipe) so the user always
+ *  knows which profile actually ran.
+ *
+ *  NEVER call this with a STORED `profile_id` (a node's `meta.profile_id`,
+ *  `CRTR_PROFILE_ID`, a pinned default). A durable id that no longer resolves
+ *  means the profile was deleted — the correct answer there is the not-found
+ *  those callers already handle, not the nearest surviving profile. Use
+ *  `loadProfileManifest` (or `loadExactProfileManifest`) for those. */
+export function resolveProfileOperand(operand) {
+    return matchProfileOperand(listProfiles(), operand, entryCandidate);
+}
+/** `resolveProfileOperand` over any candidate list — the CLI passes the
+ *  profiles the daemon lists for its caller. */
+export function matchProfileOperand(all, operand, key) {
+    const exact = findExactProfile(all, operand, key);
+    if (exact !== null)
+        return exact;
+    const { match, tied } = fuzzyMatchProfile(operand, all.map(key));
+    if (match !== null) {
+        const picked = all.find((p) => key(p).profileId === match.profileId);
+        console.error(`crtr: no profile named "${operand}" — using the closest match: ${key(picked).name} (${key(picked).profileId})`);
+        return picked;
+    }
+    if (tied.length > 1) {
+        const ids = tied.map((c) => `${c.profileId} (${c.name})`);
+        throw ambiguous(`"${operand}" is equally close to ${tied.length} profiles: ${ids.join(', ')}`, {
+            received: operand,
+            candidates: tied.map((c) => c.profileId),
+            next: `Re-run with one exact profile id or name: ${ids.join(', ')}.`,
+        });
+    }
+    throw profileNotFound(all, operand, key);
+}
+function locksDir() { return join(userScopeRoot(), 'profile-locks'); }
+/** Hold the per-profile manifest lock for the duration of `fn`. ALL manifest
+ *  mutations (create/rename/add-project/remove-project/delete/last-used)
+ *  below run inside this. */
+export function withProfileManifestLock(profileId, fn) {
+    assertSafeProfileId(profileId);
+    ensureDir(locksDir());
+    return withExclusiveDirectoryLock(join(locksDir(), `${profileId}.lock`), fn, {
+        timeoutError: () => general(`timed out waiting for the profile lock: ${profileId}`, {
+            next: 'Retry — another `crtr profile` command may be running concurrently on this profile.',
+        }),
+    });
+}
+// Project dirs — resolved to absolute real paths, must exist + be a directory
+// on add/create, deduped by real path, stored in manifest order.
+function resolveExistingProjectDir(dir) {
+    const abs = resolvePath(dir);
+    if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+        throw usage(`project directory does not exist or is not a directory: ${dir}`, {
+            received: dir,
+            next: 'Pass an existing directory path.',
+        });
+    }
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/** First-wins by resolved path, manifest order preserved. */
+function dedupeProjects(entries) {
+    const seen = new Set();
+    const out = [];
+    for (const entry of entries) {
+        if (seen.has(entry.path))
+            continue;
+        seen.add(entry.path);
+        out.push(entry);
+    }
+    return out;
+}
+function slugify(name) {
+    let slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    if (slug.length > 40)
+        slug = slug.slice(0, 40).replace(/-+$/g, '');
+    return slug.length > 0 ? slug : 'profile';
+}
+function generateProfileId(name) {
+    const slug = slugify(name);
+    for (let attempt = 0; attempt < 20; attempt++) {
+        const shortId = randomUUID().replace(/-/g, '').slice(0, 8);
+        const candidate = `${slug}-${shortId}`;
+        if (getStoredProfile(userScopeRoot(), candidate) === null)
+            return candidate;
+    }
+    throw general(`failed to generate a unique profile id for "${name}" after 20 attempts`);
+}
+// Mutations — all under withProfileManifestLock, all atomic writes.
+export function ensureRootProfile() {
+    return withProfileManifestLock(ROOT_PROFILE_ID, () => {
+        const existing = getStoredProfile(userScopeRoot(), ROOT_PROFILE_ID);
+        if (existing !== null) {
+            scaffoldProfile(ROOT_PROFILE_ID, existing.manifest);
+            return existing;
+        }
+        const next = {
+            schema_version: SCHEMA_VERSION,
+            name: ROOT_PROFILE_NAME,
+            projects: [],
+            grantee: 'app:terminal',
+            paused_at: null,
+            created_at: nowIso(),
+            last_used_at: nowIso(),
+        };
+        scaffoldProfile(ROOT_PROFILE_ID, next);
+        insertStoredProfile(userScopeRoot(), { profileId: ROOT_PROFILE_ID, manifest: next });
+        return { profileId: ROOT_PROFILE_ID, manifest: next };
+    });
+}
+/** 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);
+    assertProfileProjects(projects);
+    const resolvedProjects = dedupeProjects(projects.map((p) => ({ path: resolveExistingProjectDir(p.path) })));
+    const profileId = generateProfileId(trimmed);
+    return withProfileManifestLock(profileId, () => {
+        const manifest = {
+            schema_version: SCHEMA_VERSION,
+            name: trimmed,
+            projects: resolvedProjects,
+            paused_at: null,
+            ...(opts.grantee === undefined ? {} : { grantee: opts.grantee }),
+            ...(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,
+        };
+        scaffoldProfile(profileId, manifest);
+        insertStoredProfile(userScopeRoot(), { profileId, manifest });
+        return { profileId, manifest };
+    });
+}
+export function ensureAppProfile(grantee) {
+    if (!grantee.startsWith('app:') || grantee.length <= 4)
+        throw usage('an app grantee is required');
+    const name = `app-${grantee.slice(4)}`;
+    const existing = listProfiles().filter((entry) => entry.manifest.name === name && entry.manifest.grantee === grantee);
+    if (existing.length > 1)
+        throw new Error(`duplicate default profile for ${grantee}`);
+    if (existing[0])
+        return existing[0];
+    return createProfile(name, [], { grantee });
+}
+function requireExistingProfile(profileId) {
+    assertSafeProfileId(profileId);
+    if (getStoredProfile(userScopeRoot(), profileId) === null)
+        throw notFound(`profile not found: ${profileId}`, { received: profileId, next: 'Run `crtr profile list` to see available profiles.' });
+}
+function mutateManifest(profileId, mutate) {
+    requireExistingProfile(profileId);
+    return withProfileManifestLock(profileId, () => {
+        const result = updateStoredProfile(userScopeRoot(), profileId, mutate);
+        if (result === null)
+            throw notFound(`profile not found: ${profileId}`, { received: profileId });
+        return result;
+    });
+}
+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 {
+        assertSafeProfileId(profileId);
+        return profilePaused(userScopeRoot(), profileId);
+    }
+    catch {
+        return false;
+    }
+}
+/** One set-based pause read for canvas-wide projections. */
+export function pausedCanvasProfiles() {
+    return pausedProfileIds(userScopeRoot());
+}
+/** 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) {
+    let pausedAt = null;
+    const entry = mutateManifest(profileId, (m) => {
+        pausedAt = m.paused_at;
+        return { ...m, paused_at: null };
+    });
+    return { ...entry, pausedAt };
+}
+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 {};
+    }
+}
+/** Change the manifest `name` only. Callers that own the canvas (the daemon's
+ *  `PATCH /v1/profiles/:name`) must also rename the profile's canvas handle —
+ *  use `renameProfileAndHandle` there; the CLI and panels go through that route. */
+export function renameProfile(profileId, name) {
+    const trimmed = name.trim();
+    if (trimmed === '')
+        throw usage('profile name must not be empty');
+    const result = mutateManifest(profileId, (m) => ({ ...m, name: trimmed }));
+    return result;
+}
+/** A new path appends; a path already listed keeps its position. */
+export function addProfileProject(profileId, dir) {
+    assertProfileProjects([{ path: dir }]);
+    const resolved = resolveExistingProjectDir(dir);
+    const result = mutateManifest(profileId, (m) => ({ ...m, projects: dedupeProjects([...m.projects, { path: resolved }]) }));
+    return result;
+}
+/** Set one owner's automatic delivery limit. `content` is the uncapped level,
+ *  so it removes the owner's entry instead of storing it. */
+export function setProfileDeliveryLimit(profileId, owner, level) {
+    assertDeliveryLimits({ [owner]: level });
+    return mutateManifest(profileId, (m) => {
+        const { [owner]: _previous, ...rest } = m.delivery_limits ?? {};
+        const limits = level === 'content' ? rest : { ...rest, [owner]: level };
+        const { delivery_limits: _old, ...base } = m;
+        return Object.keys(limits).length === 0 ? base : { ...base, delivery_limits: limits };
+    });
+}
+export function removeProfileProject(profileId, dir) {
+    // Lenient resolution: a project dir may have been deleted since it was
+    // added, so removal must not require it to still exist on disk. Compare
+    // against both its real path (if still resolvable) and its plain resolved
+    // path (how it would have been stored had it never been a symlink).
+    const abs = resolvePath(dir);
+    let real = abs;
+    try {
+        real = realpathSync(abs);
+    }
+    catch {
+        /* dir no longer exists — fall back to comparing by its resolved path */
+    }
+    const result = mutateManifest(profileId, (m) => {
+        const filtered = m.projects.filter((p) => p.path !== real && p.path !== abs);
+        if (filtered.length === m.projects.length) {
+            throw notFound(`project not found on profile: ${dir}`, {
+                received: dir,
+                next: `Current projects: ${m.projects.length > 0 ? m.projects.map((p) => p.path).join(', ') : '(none)'}.`,
+            });
+        }
+        return { ...m, projects: filtered };
+    });
+    return result;
+}
+export function deleteProfile(profileId) {
+    requireExistingProfile(profileId);
+    withProfileManifestLock(profileId, () => {
+        const space = profileSpace(profileApp(loadExactProfileManifest(profileId).manifest), profileId);
+        if (!deleteStoredProfile(userScopeRoot(), profileId))
+            throw notFound(`profile not found: ${profileId}`, { received: profileId });
+        rmSync(space.memory, { recursive: true, force: true });
+        rmSync(space.env, { force: true });
+    });
+}

package/dist/core/rate-limit-scope.d.ts

@@ -0,0 +1,25 @@
+export type ModelCooldownFamily = 'opus' | 'sonnet';
+export type RateLimitScope = {
+    kind: 'account';
+} | {
+    kind: 'model';
+    family: ModelCooldownFamily;
+};
+export interface RateLimitObservation {
+    scope: RateLimitScope;
+    /** `anthropic-ratelimit-unified-representative-claim`, when present. */
+    claim?: string;
+    /** Epoch ms the representative claim resets, from `-unified-reset` on a rejected response. */
+    resetAt?: number;
+    /** The rate-limit headers of the response (no auth material), lower-cased names. */
+    headers: Record<string, string>;
+}
+type HeaderSource = Headers | Record<string, string> | undefined;
+/** The cooldown family a model id belongs to, or undefined when only account-wide cooldowns apply to it. */
+export declare function modelCooldownFamily(modelId: string | undefined): ModelCooldownFamily | undefined;
+/** Only the rate-limit headers of a response: safe to log and store on a fault. */
+export declare function rateLimitHeaders(headers: HeaderSource): Record<string, string>;
+/** Classify a 429's headers for the model that was requested. */
+export declare function classifyRateLimit(headers: HeaderSource, modelId: string | undefined, now?: number): RateLimitObservation;
+export declare function describeRateLimitScope(scope: RateLimitScope): string;
+export {};

package/dist/core/rate-limit-scope.js

@@ -0,0 +1,64 @@
+// rate-limit-scope.ts — what a subscription 429 actually cooled: the whole
+// account, or one model family on it.
+//
+// Anthropic subscription responses carry `anthropic-ratelimit-unified-*`
+// headers. `-status` is `allowed` | `allowed_warning` | `rejected`;
+// `-representative-claim` names the binding window (`five_hour`, `seven_day`,
+// `seven_day_opus`, `seven_day_sonnet`, `seven_day_overage_included`,
+// `overage`, …); `-reset` is the epoch second it frees up. The grammar is read
+// from Claude Code's client, not from published docs, so the classifier fails
+// safe: only a rejected response whose claim is a per-model weekly window that
+// matches the requested model's family is model-scoped. Anything else —
+// unknown claims, missing status, a claim for a different family, other
+// providers — cools the whole account exactly as before.
+const MODEL_CLAIMS = { seven_day_opus: 'opus', seven_day_sonnet: 'sonnet' };
+const MAX_HEADERS = 48;
+const MAX_VALUE = 256;
+/** The cooldown family a model id belongs to, or undefined when only account-wide cooldowns apply to it. */
+export function modelCooldownFamily(modelId) {
+    if (!modelId)
+        return undefined;
+    if (/opus/i.test(modelId))
+        return 'opus';
+    if (/sonnet/i.test(modelId))
+        return 'sonnet';
+    return undefined;
+}
+function entries(headers) {
+    if (!headers)
+        return [];
+    if (typeof Headers !== 'undefined' && headers instanceof Headers)
+        return [...headers.entries()];
+    return Object.entries(headers).filter((pair) => typeof pair[1] === 'string');
+}
+function isRateLimitHeader(name) {
+    return name.startsWith('anthropic-ratelimit-') || name.startsWith('x-ratelimit-') || name === 'retry-after' || name === 'retry-after-ms';
+}
+/** Only the rate-limit headers of a response: safe to log and store on a fault. */
+export function rateLimitHeaders(headers) {
+    const out = {};
+    for (const [rawName, value] of entries(headers)) {
+        const name = rawName.toLowerCase();
+        if (!isRateLimitHeader(name))
+            continue;
+        if (Object.keys(out).length >= MAX_HEADERS)
+            break;
+        out[name] = value.slice(0, MAX_VALUE);
+    }
+    return out;
+}
+/** Classify a 429's headers for the model that was requested. */
+export function classifyRateLimit(headers, modelId, now = Date.now()) {
+    const recorded = rateLimitHeaders(headers);
+    const claim = recorded['anthropic-ratelimit-unified-representative-claim']?.trim() || undefined;
+    const rejected = recorded['anthropic-ratelimit-unified-status']?.trim() === 'rejected';
+    const resetSeconds = Number(recorded['anthropic-ratelimit-unified-reset']);
+    const resetAt = rejected && Number.isFinite(resetSeconds) && resetSeconds > 0 && resetSeconds * 1000 > now ? resetSeconds * 1000 : undefined;
+    const claimed = claim === undefined ? undefined : MODEL_CLAIMS[claim];
+    const family = modelCooldownFamily(modelId);
+    const scope = rejected && claimed !== undefined && claimed === family ? { kind: 'model', family: claimed } : { kind: 'account' };
+    return { scope, ...(claim !== undefined ? { claim } : {}), ...(resetAt !== undefined ? { resetAt } : {}), headers: recorded };
+}
+export function describeRateLimitScope(scope) {
+    return scope.kind === 'account' ? 'account' : `model:${scope.family}`;
+}

package/dist/core/render.d.ts

@@ -0,0 +1,12 @@
+import type { LeafHelp } from './help.js';
+import type { ErrorPayload } from './io.js';
+/** Schema-driven fallback: turn a result object into agent-ready plain markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
+ *  fields render as paragraphs, and arrays become a count lead-in plus a table
+ *  or bullets. No root tag — the result is read as a continuation of the prompt. */
+export declare function renderResult(result: Record<string, unknown>, help: LeafHelp): string;
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export declare function renderError(p: ErrorPayload): string;