@north-light/crouter 0.3.235 → 0.3.237

package/dist/clients/inbox/review/__tests__/editor-roundtrip.test.js

@@ -5,6 +5,8 @@ import { join } from 'node:path';
 import { editBufferInEditor } from '../roundtrip.js';
 const temp = mkdtempSync(join(tmpdir(), 'humanloop-editor-roundtrip-'));
 const priorEditor = process.env.EDITOR;
+const priorVisual = process.env.VISUAL;
+delete process.env.VISUAL;
 try {
     const successfulEditor = join(temp, 'success-editor');
     writeFileSync(successfulEditor, '#!/bin/sh\nprintf "edited\\n" > "$1"\n');
@@ -24,6 +26,10 @@ finally {
         delete process.env.EDITOR;
     else
         process.env.EDITOR = priorEditor;
+    if (priorVisual === undefined)
+        delete process.env.VISUAL;
+    else
+        process.env.VISUAL = priorVisual;
     rmSync(temp, { recursive: true, force: true });
 }
 console.log('editor round-trip tests passed');

package/dist/clients/inbox/review/roundtrip.js

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 /** Run $EDITOR against a temporary buffer. Terminal ownership stays with the host. */
 export function editBufferInEditor(buffer) {
     const tmpFile = join(tmpdir(), `crtr-input-${randomUUID()}.txt`);
-    const editor = process.env.EDITOR || 'vi';
+    const editor = process.env.VISUAL || process.env.EDITOR || 'vi';
     try {
         writeFileSync(tmpFile, buffer);
         // $EDITOR may be a shell fragment such as "code --wait".

package/dist/commands/__tests__/node-new.test.js

@@ -0,0 +1,58 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgv } from '../../core/command.js';
+import { nodeNew } from '../node/create.js';
+function listen(server, path) {
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(path, resolve);
+    });
+}
+function close(server) {
+    return new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+}
+test('node new forwards --resident in the create request', async () => {
+    const previousHome = process.env['CRTR_HOME'];
+    const home = mkdtempSync('/tmp/crtr-node-new-resident-');
+    const socketPath = join(home, 'crtrd.sock');
+    let requestBody;
+    const server = createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => {
+            requestBody = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            const body = JSON.stringify({
+                node_id: 'resident-test',
+                name: 'Review worker',
+                status: 'active',
+                cwd: home,
+            });
+            res.writeHead(201, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) });
+            res.end(body);
+        });
+    });
+    process.env['CRTR_HOME'] = home;
+    try {
+        await listen(server, socketPath);
+        const input = await parseArgv(nodeNew.help.params ?? [], [
+            'Review the worker.',
+            '--root',
+            '--resident',
+            '--name',
+            'Review worker',
+        ]);
+        await nodeNew.run(input);
+        assert.equal(requestBody?.['root_lifecycle'], 'resident');
+    }
+    finally {
+        await close(server);
+        if (previousHome === undefined)
+            delete process.env['CRTR_HOME'];
+        else
+            process.env['CRTR_HOME'] = previousHome;
+        rmSync(home, { recursive: true, force: true });
+    }
+});

package/dist/commands/memory/lint.js

@@ -7,7 +7,7 @@ import { envProfileId } from '../../shared/env.js';
 import { defineLeaf } from '../../core/command.js';
 import { warn } from '../../core/output.js';
 import { ExitCode } from '../../types.js';
-import { lintMemoryStore, lintMemoryTarget, resolvableCanonicalNames, } from '../../core/memory/lint.js';
+import { lintMemoryStore, lintMemoryTarget, lintOrphans, resolvableCanonicalNames, } from '../../core/memory/lint.js';
 import { loadMemoryTargetView } from '../../core/memory-resolver.js';
 import { resolveReadSelector, selectorParam } from './shared.js';
 function findingRow(finding) {
@@ -21,16 +21,16 @@ function findingRow(finding) {
         ...(finding.paths === undefined ? {} : { paths: [...finding.paths] }),
     };
 }
-/** The canonical names a `--dir` store's own links and routes must resolve in:
- *  the target view an agent standing in that project sees. Never the store in
- *  isolation — a project doc legitimately links a user or builtin doc. */
-function resolvableNamesForStore(store) {
-    const view = loadMemoryTargetView({
+/** The target view an agent standing in a `--dir` store's project sees. Both a
+ *  project doc's links/routes and its reachability are resolved against this,
+ *  never the store in isolation — a project doc legitimately links a user or
+ *  builtin doc, and is legitimately reached from one. */
+function targetViewForStore(store) {
+    return loadMemoryTargetView({
         cwd: store.ownerDir ?? store.storeRoot,
         profileId: envProfileId() || null,
         nodeId: null,
     }, { quiet: true, includeDescendants: true });
-    return resolvableCanonicalNames(view.docs);
 }
 export const lintLeaf = defineLeaf({
     name: 'lint',
@@ -48,7 +48,7 @@ export const lintLeaf = defineLeaf({
             { name: 'stores', type: 'number', required: true, constraint: 'Physical memory stores linted.' },
             { name: 'profile_projects', type: 'number', required: false, constraint: 'Projects the selected profile manages that were checked for a workspace front door — zero under a scope filter excluding project stores. Absent under --dir.' },
             { name: 'findings', type: 'object[]', required: true, constraint: 'One row per ERROR: {rule, path, message, name?, scope?, store_root?, paths?}. `rule` names the violated rule (yaml, schema, extension, length, store-namespace, namespace-placement, root-name, root-index-unaddressable, local-name, canonical-collision, dangling-link, memory-read-route, front-door, owner-path-collision). `paths` carries every file sharing a collided identity, read winner first. Empty when green.' },
-            { name: 'warnings', type: 'object[]', required: true, constraint: 'Same row shape, non-fatal authoring smells: short-preview, broad-memory-read, nested-store-boot, an advisory missing front door, a wildcard memory-read glob matching nothing.' },
+            { name: 'warnings', type: 'object[]', required: true, constraint: 'Same row shape, non-fatal authoring smells: short-preview, broad-memory-read, nested-store-boot, an advisory missing front door, a wildcard memory-read glob matching nothing, and orphan (a doc no reachability path routes an agent to — unfiltered target/--dir view only, never under --scope).' },
             { name: 'notices', type: 'object[]', required: true, constraint: 'Same row shape, inspection data rather than faults: cross-store-candidates (one canonical name held by several stores, winner first) and reference-check-deferred.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next command.' },
         ],
@@ -60,14 +60,23 @@ export const lintLeaf = defineLeaf({
             scope: input['scope'],
             dir: input['dir'],
         });
-        const result = selector.store !== null
-            ? lintMemoryStore(selector.store, {
-                resolvable: resolvableNamesForStore(selector.store),
+        let result;
+        if (selector.store !== null) {
+            const view = targetViewForStore(selector.store);
+            const base = lintMemoryStore(selector.store, {
+                resolvable: resolvableCanonicalNames(view.docs),
                 // Asked about directly, not as a profile-managed project: a missing
                 // front door is a gap to report, not a failed gate.
                 frontDoor: 'advisory',
-            })
-            : lintMemoryTarget({ ...(selector.scope === undefined ? {} : { scope: selector.scope }) });
+            });
+            // Reachability is a whole-view property, so orphans are computed over the
+            // project's target view but flagged only for this store's own docs.
+            const orphans = lintOrphans(view.docs, { flagStoreRoot: selector.store.storeRoot });
+            result = { ...base, findings: [...base.findings, ...orphans], warnings: [...base.warnings, ...orphans] };
+        }
+        else {
+            result = lintMemoryTarget({ ...(selector.scope === undefined ? {} : { scope: selector.scope }) });
+        }
         const errors = result.errors.map(findingRow);
         const warnings = result.warnings.map(findingRow);
         const notices = result.notices.map(findingRow);

package/dist/commands/memory/shared.js

@@ -778,7 +778,7 @@ export const FRONTMATTER_OVERLAY_PARAMS = {
     'unlisted': { kind: 'flag', name: 'unlisted', type: 'bool', required: false, default: false, constraint: 'Suppress this doc from directory listings. Suppression only — explicit reads, [[links]], and surfaces entries still work.' },
     'surface': { kind: 'flag', name: 'surface', type: 'string', required: false, repeatable: true, constraint: 'One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?, gate?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command|pre-command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command/pre-command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. Optional entry `gate` is a node-config predicate using the same vocabulary as the document gate; its event constraints and gate both match before it participates. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to this doc’s routing anchor — its own canonical name when the doc is its directory’s document (`<dir>/INDEX.md`), otherwise the canonical directory it sits in. Participating entries fold to their highest `at`; there is no cross-entry deny precedence.' },
     'gate': { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate \u2014 YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
-    'lint-ignore': { kind: 'flag', name: 'lint-ignore', type: 'enum', choices: [...SUPPRESSIBLE_RULES], required: false, repeatable: true, constraint: 'Suppress one authoring lint rule for this document. Repeat for a list; valid rules: length, broad-memory-read.' },
+    'lint-ignore': { kind: 'flag', name: 'lint-ignore', type: 'enum', choices: [...SUPPRESSIBLE_RULES], required: false, repeatable: true, constraint: 'Suppress one authoring lint rule for this document. Repeat for a list; valid rules: length, broad-memory-read, orphan.' },
     'slash': { kind: 'flag', name: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) \u2014 the doc body becomes the command\u2019s injected prompt. Default false: most docs are consulted, not invoked.' },
 };
 /** One overlay flag, with leaf-specific prose appended to the shared

package/dist/commands/node/create.d.ts

@@ -18,6 +18,6 @@ export declare function assertKind(kind: string): void;
  *  sub-kind (universally available) earns a place in this list. A direct launch
  *  by full sub-kind string is always valid regardless (visibility-only
  *  filtering) — discover the roster for a specific kind via
- *  `crtr sys prompt-review --list --kind <kind>`. */
+ *  `crtr sys context prompt-review --list --kind <kind>`. */
 export declare function kindsStateBlock(): string;
 export declare const nodeNew: import("../../core/command.js").LeafDef;

package/dist/commands/node/create.js

@@ -51,7 +51,7 @@ export function assertKind(kind) {
  *  sub-kind (universally available) earns a place in this list. A direct launch
  *  by full sub-kind string is always valid regardless (visibility-only
  *  filtering) — discover the roster for a specific kind via
- *  `crtr sys prompt-review --list --kind <kind>`. */
+ *  `crtr sys context prompt-review --list --kind <kind>`. */
 export function kindsStateBlock() {
     const registry = readMergedLaunchConfig().kinds;
     const kinds = Object.keys(registry)
@@ -81,6 +81,7 @@ function nodeNewParams() {
         { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node.' },
         { kind: 'flag', name: 'node-id', type: 'string', required: false, constraint: 'Exact id for the new node; lowercase letters, digits, and hyphens only, at most 128 characters. Rejected if already present.' },
         { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an independent resident root with no parent or subscription. Mutually exclusive with --worktree.' },
+        { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'Birth the node as resident: it parks and stays wakeable without being forced to submit a final. Applies to managed children and roots; roots default to resident.' },
         { kind: 'flag', name: 'worktree', type: 'string', required: false, constraint: 'Local base branch for a crouter-managed worktree for this child. Mutually exclusive with --root.' },
         { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'Fork the new node from an existing node id, absolute session path, or partial pi session uuid.' },
         {
@@ -179,6 +180,7 @@ async function runNodeCreation(input) {
     const name = input['name'];
     const parent = input['parent'];
     const root = input['root'] === true;
+    const resident = input['resident'] === true;
     const worktreeBaseRaw = input['worktree'];
     if (worktreeBaseRaw !== undefined && worktreeBaseRaw.trim() === '') {
         throw new InputError({ error: 'worktree_base_required', message: '--worktree requires a base branch', field: 'worktree', next: 'Pass an existing local branch that landing can fast-forward.' });
@@ -221,6 +223,7 @@ async function runNodeCreation(input) {
         ...(name !== undefined ? { name } : {}),
         prompt,
         ...(root ? { root: true } : { parent: parentId ?? null }),
+        ...(resident ? { root_lifecycle: 'resident' } : {}),
         ...(worktreeBase !== undefined ? { worktree: worktreeBase } : {}),
         ...(forkFrom !== undefined ? { fork_from: forkFrom } : {}),
         ...(modelSpec !== undefined ? { model: modelSpec } : {}),

package/dist/commands/node/lifecycle.js

@@ -246,8 +246,8 @@ export const nodePromote = defineLeaf({
         name: 'node promote',
         summary: 'promote yourself to an orchestrator when worthwhile parallel delegation should make coordination your primary job; task duration, sequential phases, or one helper do not qualify. Mode only — lifecycle stays as-is unless you pass --resident',
         params: [
-            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here. For an exact composed persona list, use `crtr sys prompt-review --list --kind <kind>` with the target kind. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
-            { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'ALSO flip lifecycle→resident: make the node interactable — it is never forced to submit a final, stays wakeable while attached or awaiting something live, and completes after the unattended grace otherwise. Omit to stay terminal/orchestrator (delegates + holds a roadmap, but still owes a final up the spine and reaps when done).' },
+            { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: 'Specialize as this kind of orchestrator. The <kinds> list below names every top-level installable kind and when to use each; a registered sub-kind is valid too by exact path but not listed here. For an exact composed persona list, use `crtr sys context prompt-review --list --kind <kind>` with the target kind. Defaults to your current kind. Promoting from a generic kind? CHOOSE a concrete one — it sets the orchestrator persona you revive into.' },
+            { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'ALSO flip lifecycle→resident: make the node interactable — it is never forced to submit a final, and unattended grace parks it after a summary turn instead, leaving it revivable fresh against its goal and roadmap. Omit to stay terminal/orchestrator (delegates + holds a roadmap, but still owes a final up the spine and reaps when done).' },
             { kind: 'flag', name: 'model', type: 'enum', choices: ['ultra', 'strong'], required: false, constraint: 'Change the model you run on, by capability tier: `ultra` (frontier — reserve for high-taste judgment or enormous work: speccing, planning something large, e2e-testing something hard to test) or `strong` (opus — regular dev work). Omit to keep your current model. An orchestrator steering work is never weaker than opus, so these are the only two choices; the change is durable across future revives.' },
             { kind: 'flag', name: 'node', type: 'string', required: false, constraint: 'Node to promote. Defaults to the caller (CRTR_NODE_ID).' },
         ],

package/dist/commands/node-worktree.js

@@ -1,7 +1,4 @@
-// `crtr node worktree` — the node-owned managed-worktree lifecycle. Birth is
-// `node new --worktree <base>`; this branch holds the single close
-// verb, symmetric with birth, so a git worktree's whole lifecycle sits under
-// `node`.
+// `crtr node worktree` manages node-owned managed worktrees.
 import { envNodeId } from '../shared/env.js';
 import { defineBranch, defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
@@ -39,6 +36,39 @@ function mapWorktreeApiError(err) {
     }
     throw err;
 }
+const worktreeAbandon = defineLeaf({
+    name: 'abandon',
+    description: 'remove a node worktree and preserve any branch work',
+    whenToUse: 'a canceled, dead, or otherwise finished node holds work you will not land now: remove its checkout without reviving it, retain its branch work, and release its worktree ownership so finalization or deletion can continue',
+    help: {
+        name: 'node worktree abandon',
+        summary: 'remove a node-managed checkout, retain its work, and commit dirty changes first',
+        params: [
+            { kind: 'positional', name: 'node', required: true, constraint: 'Node id whose open managed worktree to abandon.' },
+        ],
+        output: [
+            { name: 'node_id', type: 'string', required: true, constraint: 'The node whose worktree was abandoned.' },
+            { name: 'branch', type: 'string', required: true, constraint: 'The branch that retains abandoned work, or the deleted empty branch.' },
+            { name: 'tip_sha', type: 'string', required: true, constraint: 'The preserved work tip, or the deleted empty branch tip.' },
+            { name: 'worktree_path', type: 'string', required: true, constraint: 'The removed managed checkout path.' },
+            { name: 'branch_deleted', type: 'boolean', required: true, constraint: 'Whether the empty branch was deleted; false means the branch retains work or cleanup needs manual completion.' },
+        ],
+        outputKind: 'object',
+        effects: ['Removes the checkout. A clean zero-commit worktree deletes its empty branch. Otherwise commits all worktree state to the branch, retains that branch, records abandoned provenance, and repoints the node cwd to the repository root without changing lifecycle status.'],
+    },
+    run: async (input) => {
+        const nodeId = input['node'];
+        try {
+            return { ...(await cliClient().abandonWorktree(nodeId, { by: envNodeId() ?? 'human' })) };
+        }
+        catch (err) {
+            mapWorktreeApiError(err);
+        }
+    },
+    render: (r) => r['branch_deleted'] === true
+        ? `Managed empty worktree abandoned — checkout and empty branch ${String(r['branch'])} removed.`
+        : `Managed worktree abandoned — checkout removed; branch ${String(r['branch'])} kept at ${String(r['tip_sha'])}.`,
+});
 const worktreeClose = defineLeaf({
     name: 'close',
     description: 'land and close the current node-managed worktree',
@@ -93,11 +123,12 @@ const worktreeClose = defineLeaf({
 });
 export const nodeWorktreeBranch = defineBranch({
     name: 'worktree',
-    description: 'manage a node-owned git worktree — close the one born by `node new --worktree <base>`',
-    whenToUse: 'you are inside a node that was spawned with `node new --worktree <base>` and are ready to land it: rebase it onto its recorded local base branch, fast-forward that base onto it, and close the worktree with cleanup deferred until the node exits. Symmetric with `node new --worktree <base>`, which births it',
+    description: 'manage a node-owned git worktree — land it or explicitly abandon it',
+    whenToUse: 'you need to dispose of a managed checkout: close lands the current node’s work onto its base; abandon removes any node’s checkout while retaining its work on the branch',
     help: {
         name: 'node worktree',
-        summary: 'manage a node-owned git worktree — birth is `node new --worktree <base>`; this branch closes it',
+        summary: 'manage a node-owned git worktree — land it, or explicitly abandon its checkout while retaining work',
+        model: 'Close merges work into its recorded base. Abandon removes the checkout without changing lifecycle state; it retains work on the branch and deletes only a clean zero-commit branch.',
     },
-    children: [worktreeClose],
+    children: [worktreeClose, worktreeAbandon],
 });

package/dist/commands/revive.js

@@ -62,6 +62,7 @@ export const reviveLeaf = defineLeaf({
             { name: 'candidates', type: 'string', required: false, constraint: 'Preview: the node ids that WOULD be revived (newline-joined). Empty when none are disconnected.' },
             { name: 'revived', type: 'string', required: false, constraint: 'Sweep: the node ids whose broker engine was relaunched (newline-joined).' },
             { name: 'failed', type: 'string', required: false, constraint: 'Sweep: node ids whose relaunch threw, with the error (newline-joined). Absent when none failed.' },
+            { name: 'frozen', type: 'string', required: false, constraint: 'Sweep: node ids the live-broker cap turned away (newline-joined). Not failures — the daemon launches each as a slot frees. Absent when none were frozen.' },
         ],
         outputKind: 'object',
         effects: [
@@ -164,9 +165,17 @@ async function runReviveAll(input) {
     };
     if (res.failed.length > 0) {
         out['failed'] = res.failed.map((f) => `${f.node_id}: ${f.error}`).join('\n');
+    }
+    if (res.frozen.length > 0) {
+        out['frozen'] = res.frozen.join('\n');
+    }
+    const total = res.revived.length + res.failed.length + res.frozen.length;
+    if (total > res.revived.length) {
         out['message'] =
-            `Revived ${res.revived.length} of ${res.revived.length + res.failed.length} disconnected node(s); ` +
-                `${res.failed.length} failed to relaunch (see failed).`;
+            `Revived ${res.revived.length} of ${total} disconnected node(s) (RESUME)` +
+                (res.failed.length > 0 ? `; ${res.failed.length} failed to relaunch (see failed)` : '') +
+                (res.frozen.length > 0 ? `; ${res.frozen.length} frozen at the broker cap and launched as slots free (see frozen)` : '') +
+                '.';
     }
     return out;
 }

package/dist/commands/sys/context/admin/actions.d.ts

@@ -0,0 +1,48 @@
+import type { DeliveryRecord } from '../../../../core/substrate/plan.js';
+import type { Rung, SurfaceEntry } from '../../../../core/substrate/schema.js';
+export interface ActionOutcome {
+    ok: boolean;
+    message: string;
+    /** Canonical name the document answers to after the action — the new name
+     *  after a move. Absent when the action changed no document. */
+    name?: string;
+}
+/** The notice a mutating action shows instead of writing, or null when the
+ *  record is writable. The dossier marks a refusing record read-only so the
+ *  refusal is never a surprise. */
+export declare function readOnlyReason(record: DeliveryRecord, profileId: string | null): string | null;
+/** Replace one document's whole surfaces list — refused when the list on disk
+ *  holds more than the parsed list can carry back. */
+export declare function writeSurfaces(record: DeliveryRecord, profileId: string | null, surfaces: SurfaceEntry[], success: string): Promise<ActionOutcome>;
+/** The body exactly as it sits after the frontmatter fence, which is what the
+ *  revision path saves back. The PARSED body eats the blank line the fence opens
+ *  with, so seeding an editor from it would rewrite every doc it touched. */
+export declare function readBody(record: DeliveryRecord): string;
+/** Replace one document's whole body. */
+export declare function writeBody(record: DeliveryRecord, profileId: string | null, body: string): Promise<ActionOutcome>;
+/** Set or clear the document-level gate. An empty predicate clears it. */
+export declare function writeGate(record: DeliveryRecord, profileId: string | null, gate: string): Promise<ActionOutcome>;
+export declare function toggleFlag(record: DeliveryRecord, profileId: string | null, field: 'unlisted' | 'slash'): Promise<ActionOutcome>;
+export declare function writeRoutingLine(record: DeliveryRecord, profileId: string | null, line: string): Promise<ActionOutcome>;
+export declare function writeShortForm(record: DeliveryRecord, profileId: string | null, text: string): Promise<ActionOutcome>;
+/** Rename or relocate a document inside its own store. */
+export declare function moveDoc(record: DeliveryRecord, profileId: string | null, to: string): Promise<ActionOutcome>;
+/** The profile project entry whose ceiling reaches a document's store, or null
+ *  when the store carries the neutral ceiling because no entry covers it.
+ *
+ *  Mirrors `resolveProjectScopeRoots`: pointers are walked in manifest order
+ *  and the FIRST entry whose ancestor walk reaches the store's SCOPE root — the
+ *  `.crouter/` dir one level above the `memory/` store — owns the ceiling, so
+ *  cycling any other entry would move a number the store never reads. */
+export declare function capOwnerFor(record: DeliveryRecord, profileId: string | null): {
+    path: string;
+    memory: Rung;
+} | null;
+export interface CapChange {
+    path: string;
+    memory: Rung;
+}
+/** Move a project relationship's automatic-delivery ceiling. */
+export declare function writeCap(profileId: string, path: string, memory: Rung): ActionOutcome & {
+    change?: CapChange;
+};

package/dist/commands/sys/context/admin/actions.js

@@ -0,0 +1,246 @@
+// Every write `crtr sys context admin` can make. Document changes go through
+// the same `memory edit` / `memory move` leaves the CLI runs, always with
+// rationale `editor`; a project relationship's memory ceiling goes through the
+// profile manifest the profiles settings panel writes. Nothing here touches a
+// memory file directly.
+import { dirname } from 'node:path';
+import { editLeaf } from '../../../memory/edit.js';
+import { literalBodySegment } from '../../../memory/shared.js';
+import { moveLeaf } from '../../../memory/move.js';
+import { addProfileProject, loadProfileManifest } from '../../../../core/profiles/manifest.js';
+import { findProjectScopeRoots } from '../../../../core/scope.js';
+import { readText, realpathOrSelf } from '../../../../core/fs-utils.js';
+import { parseSubstrateFrontmatter } from '../../../../core/substrate/schema.js';
+import { surfaceEntryToFlag } from './model.js';
+const RATIONALE = 'editor';
+/** Which store a mutation must land in, or why the page cannot name one.
+ *
+ *  The memory leaves resolve a bare name against the AMBIENT target — this
+ *  process's cwd, profile and node — while the page plans against a dialled
+ *  snapshot that may name a different one. Every mutation therefore carries an
+ *  explicit selector for the store the record was actually read from. A record
+ *  no selector reaches is READ-ONLY here rather than sent without one: the leaf
+ *  would resolve the bare name ambiently and rewrite whatever wins it — a
+ *  same-named override at a writable scope — and report that as success. */
+function storeAddress(record, profileId) {
+    if (record.doc.plugin !== undefined) {
+        return {
+            refusal: `${record.name} belongs to the plugin “${record.doc.plugin}” and is read-only here — override it with \`crtr memory write ${record.name}\`.`,
+        };
+    }
+    if (record.scope === 'builtin') {
+        return {
+            refusal: `${record.name} is a builtin document and is read-only here — override it with \`crtr memory write ${record.name}\`.`,
+        };
+    }
+    if (record.scope === 'project') {
+        const ownerDir = record.source.store.ownerDir;
+        return ownerDir === undefined
+            ? { refusal: `${record.name} resolves from a project store with no owning directory, which this page cannot address — edit it with \`crtr memory edit ${record.name} --dir <dir>\`.` }
+            : { selector: { dir: ownerDir } };
+    }
+    if (record.scope === 'profile') {
+        return { selector: profileId === null ? { scope: 'profile' } : { scope: 'profile', profile: profileId } };
+    }
+    if (record.scope === 'user' || record.scope === 'node')
+        return { selector: { scope: record.scope } };
+    return { refusal: `${record.name} resolves from the ${record.scope} scope, which this page cannot address.` };
+}
+/** The notice a mutating action shows instead of writing, or null when the
+ *  record is writable. The dossier marks a refusing record read-only so the
+ *  refusal is never a surprise. */
+export function readOnlyReason(record, profileId) {
+    const address = storeAddress(record, profileId);
+    return 'refusal' in address ? address.refusal : null;
+}
+function failure(error) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+}
+async function runEdit(record, profileId, request, success) {
+    const address = storeAddress(record, profileId);
+    if ('refusal' in address)
+        return { ok: false, message: address.refusal };
+    const surfaces = request.surfaces;
+    const unset = [...(request.unset ?? [])];
+    if (surfaces !== undefined && surfaces.length === 0 && !unset.includes('surfaces'))
+        unset.push('surfaces');
+    try {
+        await editLeaf.run({
+            name: record.name,
+            rationale: RATIONALE,
+            ...address.selector,
+            ...(surfaces !== undefined && surfaces.length > 0 ? { surface: surfaces.map(surfaceEntryToFlag) } : {}),
+            ...(request.body === undefined ? {} : { body: request.body }),
+            ...(request.gate === undefined ? {} : { gate: request.gate }),
+            ...(request.unlisted === undefined ? {} : { unlisted: true }),
+            ...(request.slash === undefined ? {} : { slash: true }),
+            ...(request.whenAndWhyToRead === undefined ? {} : { whenAndWhyToRead: request.whenAndWhyToRead }),
+            ...(request.shortForm === undefined ? {} : { shortForm: request.shortForm }),
+            ...(unset.length > 0 ? { unset } : {}),
+        });
+        return { ok: true, message: success, name: record.name };
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+/** Replace one document's whole surfaces list — refused when the list on disk
+ *  holds more than the parsed list can carry back. */
+export function writeSurfaces(record, profileId, surfaces, success) {
+    const refusal = readOnlyReason(record, profileId) ?? unwritableSurfaces(record);
+    if (refusal !== null)
+        return Promise.resolve({ ok: false, message: refusal });
+    return runEdit(record, profileId, { surfaces }, success);
+}
+/** Why the authored `surfaces` list cannot survive a write, or null when it can.
+ *
+ *  A surface write REPLACES the whole list with the parsed entries, and the
+ *  runtime parser is tolerant: it drops an entry it cannot read and strips a key
+ *  it does not know. Writing that list back would delete authored content the
+ *  page never showed, so an unrepresentable list refuses the edit instead —
+ *  `memory edit --surface` admits only entries the strict coercion accepts, so
+ *  carrying the original through verbatim is not available either. */
+function unwritableSurfaces(record) {
+    const raw = record.source.frontmatter?.['surfaces'];
+    if (raw === undefined || raw === null)
+        return null;
+    const fix = `a write replaces the whole list, so fix ${record.storePath} first`;
+    if (!Array.isArray(raw)) {
+        return `The \`surfaces\` field of ${record.name} is not a list of entries — ${fix}.`;
+    }
+    for (const [index, entry] of raw.entries()) {
+        const loss = entryLoss(record.kind, entry);
+        if (loss !== null)
+            return `Entry ${index + 1} of ${record.name} ${loss} — ${fix}.`;
+    }
+    return null;
+}
+/** The frontmatter key behind each field a parsed entry carries back. */
+const ENTRY_FIELDS = {
+    on: 'on',
+    at: 'at',
+    match: 'match',
+    'match-frontmatter': 'matchFrontmatter',
+    gate: 'gate',
+};
+function entryLoss(kind, raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+        return 'is not an entry object';
+    const rec = raw;
+    const parsed = parseSubstrateFrontmatter({ kind, surfaces: [rec] })?.surfaces[0];
+    if (parsed === undefined)
+        return `(on ${JSON.stringify(rec['on'] ?? null)}) is malformed and the parser drops it`;
+    for (const key of Object.keys(rec)) {
+        if (rec[key] === undefined)
+            continue;
+        const field = ENTRY_FIELDS[key];
+        if (field === undefined)
+            return `carries an unknown key \`${key}\``;
+        if (parsed[field] === undefined)
+            return `carries a \`${key}\` the parser drops`;
+    }
+    return null;
+}
+/** The body exactly as it sits after the frontmatter fence, which is what the
+ *  revision path saves back. The PARSED body eats the blank line the fence opens
+ *  with, so seeding an editor from it would rewrite every doc it touched. */
+export function readBody(record) {
+    const segment = literalBodySegment(readText(record.storePath));
+    return segment.startsWith('\n') ? segment.slice(1) : segment;
+}
+/** Replace one document's whole body. */
+export function writeBody(record, profileId, body) {
+    if (body.trim() === '') {
+        return Promise.resolve({
+            ok: false,
+            message: `An empty body is not an edit \u2014 remove ${record.name} with \`crtr memory delete\` instead.`,
+        });
+    }
+    return runEdit(record, profileId, { body }, `Rewrote the body of ${record.name}.`);
+}
+/** Set or clear the document-level gate. An empty predicate clears it. */
+export function writeGate(record, profileId, gate) {
+    const trimmed = gate.trim();
+    return trimmed === ''
+        ? runEdit(record, profileId, { unset: ['gate'] }, `Cleared the gate on ${record.name}.`)
+        : runEdit(record, profileId, { gate: trimmed }, `Gated ${record.name} on ${trimmed}.`);
+}
+export function toggleFlag(record, profileId, field) {
+    const on = field === 'unlisted' ? record.doc.unlisted : record.doc.slash;
+    if (on)
+        return runEdit(record, profileId, { unset: [field] }, `${record.name} is no longer ${field}.`);
+    const set = field === 'unlisted' ? { unlisted: true } : { slash: true };
+    return runEdit(record, profileId, set, `${record.name} is now ${field}.`);
+}
+export function writeRoutingLine(record, profileId, line) {
+    const trimmed = line.trim();
+    if (trimmed === '') {
+        return Promise.resolve({ ok: false, message: 'A routing line cannot be empty — it is the document\u2019s contract.' });
+    }
+    return runEdit(record, profileId, { whenAndWhyToRead: trimmed }, `Rewrote the routing line on ${record.name}.`);
+}
+export function writeShortForm(record, profileId, text) {
+    const trimmed = text.trim();
+    return trimmed === ''
+        ? runEdit(record, profileId, { unset: ['short-form'] }, `Cleared the short form on ${record.name}.`)
+        : runEdit(record, profileId, { shortForm: trimmed }, `Rewrote the short form on ${record.name}.`);
+}
+/** Rename or relocate a document inside its own store. */
+export async function moveDoc(record, profileId, to) {
+    const trimmed = to.trim();
+    if (trimmed === '')
+        return { ok: false, message: 'Type the new canonical name.' };
+    const address = storeAddress(record, profileId);
+    if ('refusal' in address)
+        return { ok: false, message: address.refusal };
+    try {
+        const result = (await moveLeaf.run({
+            name: record.name,
+            to: trimmed,
+            ...address.selector,
+        }));
+        const name = typeof result?.['name'] === 'string' ? result['name'] : trimmed;
+        return { ok: true, message: `${record.name} now answers to ${name}.`, name };
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+/** The profile project entry whose ceiling reaches a document's store, or null
+ *  when the store carries the neutral ceiling because no entry covers it.
+ *
+ *  Mirrors `resolveProjectScopeRoots`: pointers are walked in manifest order
+ *  and the FIRST entry whose ancestor walk reaches the store's SCOPE root — the
+ *  `.crouter/` dir one level above the `memory/` store — owns the ceiling, so
+ *  cycling any other entry would move a number the store never reads. */
+export function capOwnerFor(record, profileId) {
+    if (profileId === null || record.scope !== 'project')
+        return null;
+    // Realpathed on both sides: a manifest path is stored already resolved while
+    // a store root is derived from the dialled cwd, so a symlinked ancestor would
+    // otherwise read as no entry governing the store.
+    const scopeRoot = realpathOrSelf(dirname(record.source.store.storeRoot));
+    let manifest;
+    try {
+        manifest = loadProfileManifest(profileId).manifest;
+    }
+    catch {
+        return null;
+    }
+    for (const project of manifest.projects) {
+        if (findProjectScopeRoots(project.path, null).some((root) => realpathOrSelf(root) === scopeRoot)) {
+            return { path: project.path, memory: project.memory };
+        }
+    }
+    return null;
+}
+/** Move a project relationship's automatic-delivery ceiling. */
+export function writeCap(profileId, path, memory) {
+    try {
+        addProfileProject(profileId, path, { memory });
+        return { ok: true, message: `${path} discloses up to "${memory}".`, change: { path, memory } };
+    }
+    catch (error) {
+        return failure(error);
+    }
+}