@crouton-kit/crouter 0.3.61 → 0.3.62

package/dist/clients/attach/view-socket.js

@@ -1,106 +1,99 @@
 // view-socket.ts — the socket client half of `crtr surface attach` (Phase 4, T7).
 //
 // The §0 ONE-WRITER INVARIANT lives in this directory: a viewer has ONLY a
-// socket. ViewSocketClient connects to a node's ALREADY-running headless broker
-// over its unix socket (`nodeDir(id)/view.sock`) and speaks the LOCAL
-// broker-protocol codec (`node:net` + the bounded `FrameDecoder`). It NEVER
-// spawns pi, NEVER opens the session `.jsonl`, NEVER constructs an engine — if
-// the broker is not running, connect fails and `attach-cmd` exits (focus/T9 is
+// Transport (`transport.ts`) to an ALREADY-running headless broker — locally
+// over its unix socket (`SocketTransport`, `nodeDir(id)/view.sock`), or
+// remotely over a relayed WebSocket to the Blaxel preview endpoint
+// (`RelayTransport`, `transport-relay.ts`). ViewSocketClient NEVER spawns pi,
+// NEVER opens the session `.jsonl`, NEVER constructs an engine — if the
+// broker is not running, connect fails and `attach-cmd` exits (focus/T9 is
 // what keeps a broker alive, not attach). It also never uses pi's `RpcClient`
 // (which would spawn its own engine).
 //
+// Everything below is transport-agnostic: request correlation (the pending
+// map), the reconnect give-up predicate, and close handling are the SAME
+// regardless of which Transport is plugged in at construction — only the
+// wire differs. See `transport.ts` for the seam contract.
+//
 // Reconnect: a dropped broker emits `close`; the caller's reconnect supervisor
-// decides whether to re-dial (a yield/revive keeps the SAME `view.sock` path —
-// `redial()` re-establishes the socket on it) or give up ("broker gone"). On a
-// connect-time ECONNREFUSED/ENOENT → a `BrokerUnavailableError` so the FIRST
-// connect exits non-zero with a clear message; the same codes during a redial
-// reject the redial promise as retryable. Decode is bounded by
-// `CLIENT_READ_CAPS`; a broker that somehow sends an oversized frame surfaces as
-// a clean error+exit, not a crash.
+// decides whether to re-dial (a yield/revive keeps the SAME target — a local
+// `view.sock` path, or a remote preview endpoint — `redial()` re-establishes
+// the connection to it) or give up ("broker gone"). A connect-time
+// unavailable-broker signal surfaces as `BrokerUnavailableError` so the FIRST
+// connect exits non-zero with a clear message; the same signal during a
+// redial rejects the redial promise as retryable.
 import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
-import { createConnection } from 'node:net';
-import { viewSocketPath } from '../../core/canvas/paths.js';
-import { classify } from '../../core/fault-classifier.js';
-import { clearFault, recordFault } from '../../core/runtime/fault.js';
-import { CLIENT_READ_CAPS, encodeFrame, FrameDecoder, FrameOverflowError, } from '../../core/runtime/broker-protocol.js';
+import { SocketTransport } from './transport-socket.js';
+export { BrokerUnavailableError } from './transport.js';
+export { SocketTransport } from './transport-socket.js';
+export { RelayTransport } from './transport-relay.js';
 /** How long {@link ViewSocketClient.request} waits for the correlated reply before
  *  rejecting — bounds a pending picker fetch if the broker drops the request
  *  (it should always reply with `data` or a correlated `error`). */
 const REQUEST_TIMEOUT_MS = 10_000;
-/** Surfaced when the node has no reachable broker at connect time (no socket
- *  file, or a stale socket with nothing listening). The command catches this to
- *  exit non-zero with a focus/revive hint. */
 /** The reconnect supervisor's give-up predicate (extracted pure so it is
  *  testable without a socket or TUI). After a broker close the viewer KEEPS
- *  re-dialing the same `view.sock` while the node is still alive — a yield
+ *  re-dialing the same target while the node is still alive — a yield
  *  leaves `status='active'` (intent='refresh') and the daemon revives a fresh
  *  broker on the same path. It gives up only when the node is genuinely gone:
  *  a terminal status (done/dead/canceled) or a reaped row (null). `idle` is NOT
  *  terminal — an idle-release node revives on its next inbox wake, so keep
  *  trying (the supervisor waits at a relaxed cadence for as long as the row
- *  stays live). */
+ *  stays live). Local canvas rows only — a remote target has no local row, so
+ *  callers driving a remote attach must not consult this (see attach-cmd.ts). */
 export function reconnectShouldGiveUp(row) {
     if (row === null)
         return true;
     return row.status === 'done' || row.status === 'dead' || row.status === 'canceled';
 }
-export class BrokerUnavailableError extends Error {
-    nodeId;
-    constructor(nodeId) {
-        super(`node ${nodeId} has no running broker — focus or revive it first`);
-        this.nodeId = nodeId;
-        this.name = 'BrokerUnavailableError';
-    }
-}
 export class ViewSocketClient extends EventEmitter {
     nodeId;
-    socket;
-    decoder = new FrameDecoder(CLIENT_READ_CAPS);
+    transport;
     closeEmitted = false;
+    /** Tracks live connect↔close state so {@link request} can fail fast on a
+     *  dead/absent connection rather than parking a promise the reply will
+     *  never reach (transport-agnostic mirror of the old socket.destroyed
+     *  check). A post-close request lands here too — {@link rejectAllPending}
+     *  already ran by the time this flips false. */
+    connected = false;
+    /** The last transport-level error message, so a close can reject any
+     *  in-flight requests with the precise reason (e.g. an oversized-frame
+     *  overflow) instead of a generic one. Cleared on every fresh connect. */
+    lastTransportError;
     /** In-flight correlated read-ops, keyed by the `id` minted in {@link request}.
      *  Resolved by the matching `data` frame / rejected by the matching `error`
-     *  frame in {@link onData}, the request's timeout, or socket teardown. */
+     *  frame in {@link onFrame}, the request's timeout, or transport teardown. */
     pending = new Map();
-    /** One redial fault line per reconnect EPISODE, not per attempt: the
-     *  supervisor redials for as long as the node can come back (a dormant node
-     *  may be gone for hours), so a per-attempt record would grow fault.log
-     *  without bound. Set on the first failed redial, reset on any successful
-     *  connect. */
-    redialFaultRecorded = false;
-    constructor(nodeId) {
+    /** `transport` defaults to a {@link SocketTransport} against this node's
+     *  local `view.sock` — today's behavior, unchanged. Pass a
+     *  {@link RelayTransport} to attach a remote node instead; every method
+     *  below behaves identically either way. */
+    constructor(nodeId, transport) {
         super();
         this.nodeId = nodeId;
-    }
-    recordSocketFault(op, err) {
-        if (op === 'redial') {
-            if (this.redialFaultRecorded)
-                return;
-            this.redialFaultRecorded = true;
-        }
-        const classified = classify('viewer↔broker', err);
-        recordFault(this.nodeId, {
-            link: 'viewer↔broker',
-            op,
-            kind: classified.kind,
-            retry: op === 'redial'
-                ? { disposition: 'auto', by: 'client' }
-                : { disposition: 'manual' },
-            message: err instanceof Error ? err.message : String(err),
+        this.transport = transport ?? new SocketTransport(nodeId);
+        this.transport.on('connect', () => {
+            this.closeEmitted = false;
+            this.connected = true;
+            this.lastTransportError = undefined;
+            this.emit('connect');
+        });
+        this.transport.on('frame', (frame) => this.onFrame(frame));
+        this.transport.on('error', (err) => {
+            this.lastTransportError = err.message;
+            this.emitError(err);
         });
+        this.transport.on('close', () => this.onClose());
     }
     /** Issue a correlated read-op and resolve with the broker's `data` reply (or
-     *  reject on the correlated `error`, a timeout, or socket teardown). Mints the
-     *  `id`, sends `{...frame, id}`, and parks a resolver consumed by {@link onData}.
-     *  The reply is narrowed by the caller on its `kind`. */
+     *  reject on the correlated `error`, a timeout, or transport teardown). Mints
+     *  the `id`, sends `{...frame, id}`, and parks a resolver consumed by
+     *  {@link onFrame}. The reply is narrowed by the caller on its `kind`. */
     request(frame) {
         const id = randomUUID();
         return new Promise((resolve, reject) => {
-            // Fail fast on a dead/absent socket rather than parking a promise that the
-            // reply will never reach (it would otherwise hang the full timeout). A
-            // post-`close` request lands here too — `rejectAllPending` already ran.
-            const sock = this.socket;
-            if (sock === undefined || sock.destroyed) {
+            if (!this.connected) {
                 reject(new Error(`cannot issue '${frame.type}': no live broker connection`));
                 return;
             }
@@ -114,8 +107,8 @@ export class ViewSocketClient extends EventEmitter {
             this.send({ ...frame, id });
         });
     }
-    /** Reject + clear every in-flight request (socket gone / decode error) so a
-     *  picker fetch never hangs past the connection it rode on. */
+    /** Reject + clear every in-flight request (connection gone / decode error)
+     *  so a picker fetch never hangs past the connection it rode on. */
     rejectAllPending(reason) {
         for (const { reject, timer } of this.pending.values()) {
             clearTimeout(timer);
@@ -123,157 +116,61 @@ export class ViewSocketClient extends EventEmitter {
         }
         this.pending.clear();
     }
-    /** The broker binds `viewSocketPath(id)` — resolve it the same way. */
-    get socketPath() {
-        return viewSocketPath(this.nodeId);
-    }
-    /** Open the connection. Wire up listeners; emits `connect` on success or
-     *  `error` (a {@link BrokerUnavailableError} for ECONNREFUSED/ENOENT) on
-     *  failure. Idempotent guard is the caller's job — call once. */
+    /** Open the connection. Emits `connect` on success or `error` (a
+     *  {@link BrokerUnavailableError} when the target has no reachable broker)
+     *  on failure. Idempotent guard is the caller's job — call once. */
     connect() {
-        const socket = createConnection(this.socketPath);
-        this.socket = socket;
-        socket.on('connect', () => {
-            this.redialFaultRecorded = false;
-            clearFault(this.nodeId, { link: 'viewer↔broker' });
-            this.emit('connect');
-        });
-        socket.on('data', (chunk) => this.onData(chunk));
-        socket.on('error', (err) => this.onError(err, 'connect'));
-        socket.on('close', () => this.onClose());
+        this.transport.connect();
     }
-    /** Re-establish the socket after a broker exit (a yield→revive cycle), on the
-     *  SAME stable `view.sock` path. Installs a FRESH FrameDecoder (a half-frame
-     *  from the dead stream must not corrupt the new one) and resets the close
-     *  guard, then re-dials. Resolves on `connect` (caller re-sends `hello`);
-     *  rejects on the dial's `error` (ECONNREFUSED while the new broker is
-     *  mid-boot, or ENOENT before it re-binds the socket) — both retryable. A
-     *  post-connect error flows through the normal `onError`→`close` path. */
+    /** Re-establish the connection after a broker exit (a yield→revive cycle),
+     *  to the SAME target. Resolves on `connect` (caller re-sends `hello`);
+     *  rejects on a retryable dial failure. */
     redial() {
-        this.destroy();
-        this.decoder = new FrameDecoder(CLIENT_READ_CAPS);
-        this.closeEmitted = false;
-        return new Promise((resolve, reject) => {
-            const socket = createConnection(this.socketPath);
-            this.socket = socket;
-            let settled = false;
-            socket.on('connect', () => {
-                if (settled)
-                    return;
-                settled = true;
-                this.redialFaultRecorded = false;
-                clearFault(this.nodeId, { link: 'viewer↔broker' });
-                this.emit('connect');
-                resolve();
-            });
-            socket.on('data', (chunk) => this.onData(chunk));
-            socket.on('error', (err) => {
-                if (settled) {
-                    this.onError(err, 'redial');
-                    return;
-                }
-                settled = true;
-                this.recordSocketFault('redial', err);
-                try {
-                    socket.destroy();
-                }
-                catch {
-                    /* ignore */
-                }
-                reject(err);
-            });
-            socket.on('close', () => this.onClose());
-        });
+        return this.transport.redial();
     }
-    /** Encode + write one client→broker frame. No-op on a dead/absent socket
-     *  (a `close` event drives teardown); never throws. */
+    /** Encode + send one client→broker frame. No-op on a dead/absent
+     *  connection; never throws. */
     send(frame) {
-        const sock = this.socket;
-        if (sock === undefined || sock.destroyed)
-            return;
-        try {
-            sock.write(encodeFrame(frame));
-        }
-        catch {
-            /* dead socket — 'close' will fire and drive teardown */
-        }
+        this.transport.send(frame);
     }
-    /** Detach: destroy the socket. `close` fires → the caller tears down. */
+    /** Detach: tear down the transport. `close` fires → the caller tears down. */
     close() {
-        this.destroy();
+        this.transport.destroy();
     }
-    onData(chunk) {
-        let frames;
-        try {
-            frames = this.decoder.push(chunk);
-        }
-        catch (err) {
-            // A broker that somehow emits an oversized frame (or a corrupt stream):
-            // clean error + drop, never a crash.
-            const msg = err instanceof FrameOverflowError
-                ? `broker sent an oversized frame (${err.message}) — disconnecting`
-                : `failed to decode a broker frame: ${String(err)}`;
-            this.rejectAllPending(msg);
-            this.emitError(new Error(msg));
-            this.destroy();
-            return;
-        }
-        for (const raw of frames) {
-            const frame = raw;
-            // Correlated replies (read-ops + dequeue) are consumed by the pending-by-id
-            // resolver, NOT re-emitted as a generic 'frame' (the attach frame router
-            // would otherwise treat a `data` frame as an AgentSessionEvent). A `data`
-            // frame is ALWAYS a reply, so it is swallowed unconditionally — even a late
-            // post-timeout one (no pending entry) is dropped, never leaked to the
-            // router. An `error` is correlated only when its `id` matches an in-flight
-            // request; an uncorrelated error still flows through.
-            if (frame.type === 'data') {
-                const entry = typeof frame.id === 'string' ? this.pending.get(frame.id) : undefined;
-                if (entry) {
-                    this.pending.delete(frame.id);
-                    clearTimeout(entry.timer);
-                    entry.resolve(frame);
-                }
-                continue;
-            }
-            if (frame.type === 'error' && typeof frame.id === 'string' && this.pending.has(frame.id)) {
-                const entry = this.pending.get(frame.id);
+    onFrame(frame) {
+        // Correlated replies (read-ops + dequeue) are consumed by the pending-by-id
+        // resolver, NOT re-emitted as a generic 'frame' (the attach frame router
+        // would otherwise treat a `data` frame as an AgentSessionEvent). A `data`
+        // frame is ALWAYS a reply, so it is swallowed unconditionally — even a late
+        // post-timeout one (no pending entry) is dropped, never leaked to the
+        // router. An `error` is correlated only when its `id` matches an in-flight
+        // request; an uncorrelated error still flows through.
+        if (frame.type === 'data') {
+            const entry = typeof frame.id === 'string' ? this.pending.get(frame.id) : undefined;
+            if (entry) {
                 this.pending.delete(frame.id);
                 clearTimeout(entry.timer);
-                entry.reject(new Error(frame.message || `request failed: ${frame.code}`));
-                continue;
+                entry.resolve(frame);
             }
-            this.emit('frame', frame);
-        }
-    }
-    onError(err, op) {
-        this.recordSocketFault(op, err);
-        if (err.code === 'ECONNREFUSED' || err.code === 'ENOENT') {
-            this.emitError(new BrokerUnavailableError(this.nodeId));
+            return;
         }
-        else {
-            this.emitError(new Error(`view socket error: ${err.message}`));
+        if (frame.type === 'error' && typeof frame.id === 'string' && this.pending.has(frame.id)) {
+            const entry = this.pending.get(frame.id);
+            this.pending.delete(frame.id);
+            clearTimeout(entry.timer);
+            entry.reject(new Error(frame.message || `request failed: ${frame.code}`));
+            return;
         }
-        // 'close' typically follows 'error'; teardown converges there.
+        this.emit('frame', frame);
     }
     onClose() {
         if (this.closeEmitted)
             return;
         this.closeEmitted = true;
-        this.rejectAllPending('broker connection closed');
+        this.connected = false;
+        this.rejectAllPending(this.lastTransportError ?? 'broker connection closed');
         this.emit('close');
     }
-    destroy() {
-        const sock = this.socket;
-        if (sock !== undefined && !sock.destroyed) {
-            try {
-                sock.destroy();
-            }
-            catch {
-                /* ignore */
-            }
-        }
-    }
     /** Emit `error` only when a listener exists — a bare EventEmitter `error`
      *  with no listener throws, and this client must never throw uncaught. */
     emitError(err) {

package/dist/commands/memory/delete.js

@@ -22,17 +22,17 @@ function pruneEmptyParents(filePath, nameSegments) {
 export const deleteLeaf = defineLeaf({
     name: 'delete',
     description: 'delete a memory document by name',
-    whenToUse: 'a stored document is wrong, obsolete, or superseded and should be removed — the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the name exactly as `read` does (project stack > profile > user precedence, leaf-name fallback) and removes that file: if you can read it, you can delete it. Refuses docs you do not own — builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`) — and refuses an ambiguous leaf name rather than guessing which doc to destroy; pass the full `area/topic` name or `--scope` to pin one.',
+    whenToUse: 'a stored document is wrong, obsolete, or superseded and should be removed — the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the name exactly as `read` does (node > project stack > profile > user precedence, leaf-name fallback) and removes that file: if you can read it, you can delete it. Refuses docs you do not own — builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`) — and refuses an ambiguous leaf name rather than guessing which doc to destroy; pass the full `area/topic` name or `--scope` to pin one.',
     help: {
         name: 'memory delete',
         summary: 'resolve a path-derived name and remove that document from its scope store',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it: precedence project stack > profile > user, with leaf-name fallback. A leaf that maps to genuinely different docs across scopes is rejected as ambiguous — pass the full name or --scope to disambiguate. May be scope-prefixed (`user/topic`) to pin the store directly.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it: precedence node > project stack > profile > user, with leaf-name fallback. A leaf that maps to genuinely different docs across scopes is rejected as ambiguous — pass the full name or --scope to disambiguate. May be scope-prefixed (`user/topic`) to pin the store directly.' },
             { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope before deleting. Use it to disambiguate a leaf name present at multiple scopes, or to assert which store you mean. builtin is not a choice — builtin docs ship with the package and cannot be deleted.' },
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Path-derived name of the deleted document.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was deleted from: user, project, or profile.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was deleted from: node, user, project, or profile.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the file that was removed.' },
             { name: 'deleted', type: 'boolean', required: true, constraint: 'Always true on success — the file was removed. A missing document fails with not_found instead.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next command — browse what remains.' },

package/dist/commands/memory/origin.js

@@ -11,7 +11,7 @@ export const originLeaf = defineLeaf({
         name: 'memory origin',
         summary: 'resolve a doc name to its creation provenance and deref the originating node',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes: project > user > builtin.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes: node > project > profile > user > builtin.' },
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },

package/dist/commands/memory/read.js

@@ -8,19 +8,19 @@ import { MEMORY_KINDS } from './shared.js';
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
-    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (project stack > profile > user > builtin), with leaf-name fallback. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
+    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Resolves the path-derived name across scopes by precedence (node > project stack > profile > user > builtin), with leaf-name fallback. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
     help: {
         name: 'memory read',
         summary: 'resolve a path-derived name to its document body, frontmatter stripped unless --frontmatter',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes by precedence: project stack > profile > user > builtin, with leaf-name fallback.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes by precedence: node > project stack > profile > user > builtin, with leaf-name fallback.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Narrows resolution when the name is ambiguous across kinds.' },
             { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes the YAML frontmatter in the returned body. Off by default — only the body is returned.' },
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Resolved kind: knowledge or preference.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: project, profile, user, or builtin.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was resolved from: node, project, profile, user, or builtin.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk — edit this file directly to tweak the doc in place.' },
             { name: 'content', type: 'string', required: true, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Hints at variant flags or next commands.' },

package/dist/commands/memory/shared.d.ts

@@ -1,10 +1,10 @@
 import type { MemoryScope } from '../../core/memory-resolver.js';
 export declare const MEMORY_KINDS: readonly ["knowledge", "preference"];
 export declare const VISIBILITY_RUNGS: readonly ["none", "name", "preview", "content"];
-export declare const MEMORY_SCOPES: readonly ["user", "project", "profile"];
-/** Scope sort weight matching resolution precedence (project stack > profile >
- *  user > builtin). Used by `list` for its "scope then kind then name"
- *  ordering. */
+export declare const MEMORY_SCOPES: readonly ["user", "project", "profile", "node"];
+/** Scope sort weight matching resolution precedence (node > project stack >
+ *  profile > user > builtin). Used by `list` for its "scope then kind then
+ *  name" ordering. */
 export declare function scopeRank(scope: MemoryScope): number;
 /** Resolve the write target scope + its memory dir. Default: project when a
  *  project scope exists for the cwd, else user. An explicit `--scope project`
@@ -16,8 +16,10 @@ export declare function scopeRank(scope: MemoryScope): number;
  *  `--dir <path>`) pins the EXACT project directory, cwd-free: the target is
  *  `<dir>/.crouter/memory/`, scaffolded if absent, never the cwd-ancestor walk
  *  — the way a profiled agent writes into any project in its purview, and the
- *  only way to target a dir shadowed by an ancestor store. Returns the
- *  absolute `<root>/memory` dir to write under. */
+ *  only way to target a dir shadowed by an ancestor store. `--scope node`
+ *  targets the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) and
+ *  requires a running node. Returns the absolute `<root>/memory` dir to write
+ *  under. */
 export declare function resolveWriteTarget(scopeArg: string | undefined, profileArg?: string, dirArg?: string): {
     scope: MemoryScope;
     memoryDir: string;

package/dist/commands/memory/shared.js

@@ -10,6 +10,7 @@ import { usage } from '../../core/errors.js';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, resetScopeCache, } from '../../core/scope.js';
 import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
+import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
 // The two memory kinds — knowledge (consult: procedural playbooks + factual
 // references merged) vs preference (behave: standing directives). Used as the
 // `--kind` enum choices everywhere.
@@ -18,12 +19,13 @@ export const MEMORY_KINDS = ['knowledge', 'preference'];
 // content). Shared by --system-prompt-visibility and --file-read-visibility.
 export const VISIBILITY_RUNGS = ['none', 'name', 'preview', 'content'];
 // Scope choices for filtering / targeting (builtin is read-only, not writable).
-export const MEMORY_SCOPES = ['user', 'project', 'profile'];
-/** Scope sort weight matching resolution precedence (project stack > profile >
- *  user > builtin). Used by `list` for its "scope then kind then name"
- *  ordering. */
+// `node` is the this-node store, writable only inside a running node.
+export const MEMORY_SCOPES = ['user', 'project', 'profile', 'node'];
+/** Scope sort weight matching resolution precedence (node > project stack >
+ *  profile > user > builtin). Used by `list` for its "scope then kind then
+ *  name" ordering. */
 export function scopeRank(scope) {
-    return scope === 'project' ? 0 : scope === 'profile' ? 1 : scope === 'user' ? 2 : 3;
+    return scope === 'node' ? -1 : scope === 'project' ? 0 : scope === 'profile' ? 1 : scope === 'user' ? 2 : 3;
 }
 /** Resolve the write target scope + its memory dir. Default: project when a
  *  project scope exists for the cwd, else user. An explicit `--scope project`
@@ -35,8 +37,10 @@ export function scopeRank(scope) {
  *  `--dir <path>`) pins the EXACT project directory, cwd-free: the target is
  *  `<dir>/.crouter/memory/`, scaffolded if absent, never the cwd-ancestor walk
  *  — the way a profiled agent writes into any project in its purview, and the
- *  only way to target a dir shadowed by an ancestor store. Returns the
- *  absolute `<root>/memory` dir to write under. */
+ *  only way to target a dir shadowed by an ancestor store. `--scope node`
+ *  targets the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) and
+ *  requires a running node. Returns the absolute `<root>/memory` dir to write
+ *  under. */
 export function resolveWriteTarget(scopeArg, profileArg, dirArg) {
     if (dirArg !== undefined && dirArg !== '') {
         if (scopeArg !== undefined && scopeArg !== 'project') {
@@ -63,15 +67,25 @@ export function resolveWriteTarget(scopeArg, profileArg, dirArg) {
         return { scope: 'project', memoryDir: join(real, CRTR_DIR_NAME, 'memory') };
     }
     let scope;
-    if (scopeArg === 'user' || scopeArg === 'project' || scopeArg === 'profile') {
+    if (scopeArg === 'user' || scopeArg === 'project' || scopeArg === 'profile' || scopeArg === 'node') {
         scope = scopeArg;
     }
     else if (scopeArg !== undefined) {
-        throw usage(`invalid --scope: ${scopeArg} (expected user|project|profile)`);
+        throw usage(`invalid --scope: ${scopeArg} (expected user|project|profile|node)`);
     }
     else {
         scope = projectScopeRoot() !== null ? 'project' : 'user';
     }
+    if (scope === 'node') {
+        // The this-node store: `nodes/<CRTR_NODE_ID>/context/memory/`. Available
+        // only inside a running node; the same dir render.ts's nodeLocalDocs loads
+        // at boot, so a doc written here rides into this node's knowledge block.
+        const nodeId = process.env['CRTR_NODE_ID'] || '';
+        if (nodeId === '') {
+            throw usage('node scope requires a running node (CRTR_NODE_ID unset); rerun inside a node');
+        }
+        return { scope: 'node', memoryDir: nodeMemoryDir(nodeId) };
+    }
     if (scope === 'profile') {
         const profileIdOrName = profileArg && profileArg !== '' ? profileArg : process.env['CRTR_PROFILE_ID'] || '';
         if (profileIdOrName === '') {

package/dist/commands/memory/write.js

@@ -14,7 +14,7 @@ export const writeLeaf = defineLeaf({
             'Pick the kind. knowledge is consulted for facts or procedures; preference directs behavior. The kind choice is about how the doc is used, not about how long it is.\n\n' +
             'Store reusable current truth, not session notes. Useful memories are non-obvious procedures, gotchas, durable preferences, cross-repo conventions, and amendments to plans/specs that future agents must honor. Put plan/spec amendments under path names like `projects/<topic>/...`; add `projects/<topic>/INDEX.md` with `name` visibility so the topic is discoverable without loading the whole body. Do not store chat summaries, implementation history, or facts already recorded in the repo.\n\n' +
             'Set both visibility rungs explicitly on create. There is no kind default. `none`, `name`, `preview`, and `content` move from least to most loaded: `none` keeps the doc out of auto-load and on-read surfaces, `name` is the bare doc tag only, `preview` is the name + envelope + routing line (`when-and-why-to-read`), and `content` inlines the whole body when the body is short enough to justify it. Each axis is independent; usually one carries a real rung and the other is `none`. When a doc is short enough to state in a single sentence — a one-line preference, or a knowledge fact that fits in a sentence — skip `preview` and use `name` or `content` directly: the routing line would run longer than the doc itself, so a `preview` rung just adds words. Sentence-length `content` docs are not just acceptable, they are correct. Never pad a memory to be more verbose than the rule or fact it carries.\n\n' +
-            'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
+            'Choose the scope. `project` is for facts any agent in one repo needs. `user` is for person-wide facts and preferences that should follow the user everywhere. `profile` is for the profile’s bundle of dirs: cross-repo conventions, how the pieces relate, or the user’s stance toward that body of work. `node` is the narrowest — the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), scratch memory only this running node sees; it rides straight into this node’s knowledge block and dies with the node. When unsure, choose the narrowest scope that will still reach the next agent who needs it.\n\n' +
             'Choose the hook — boot vs file-read. Behavior and how-to procedure surface at boot. Knowledge about code belongs next to the code: put the file in that directory’s .crouter/memory/ (`--dir <project-dir>` targets it exactly, from anywhere) and it fires positionally when files there are read, costing nothing at boot. A knowledge doc about a person or process has no code directory to anchor to, so on-read triggering is meaningless — route it through boot instead and set the boot rung to `preview` when you want the routing line to surface.\n\n' +
             'Write the routing line (--when-and-why-to-read) first, before storing anything: "When <circumstance>, this <kind> should be read because <payoff>." The test is whether a stranger mid-task can decide from that one line alone whether to spend the read. If you cannot name the concrete situation that triggers it, you do not yet understand the memory — ask the user one sharp question instead of improvising. Never paraphrase the advice in the routing line; keep it about when to read and why the read is worth it.\n\n' +
             'Gate and read-when share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.\n\n' +
@@ -32,7 +32,7 @@ export const writeLeaf = defineLeaf({
             { kind: 'flag', name: 'read-when', type: 'string', required: false, constraint: 'Frontmatter read-when — YAML/JSON object predicate over a read file’s own frontmatter using the same field/matcher vocabulary described in the guide.' },
             { 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 `:`) — the doc body becomes the command’s injected prompt. Default false: most docs are consulted, not invoked.' },
             { kind: 'flag', name: 'rationale', type: 'string', required: false, constraint: 'Frontmatter rationale — the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only in the raw file or `memory read --frontmatter`. Omitting this flag on an update PRESERVES an existing rationale unchanged.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project directory. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project directory. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile. `node` writes to the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) — the nearest scope, seen only by this running node, requires a node context.' },
             { kind: 'flag', name: 'dir', type: 'string', required: false, constraint: 'Exact project directory to write under — targets `<dir>/.crouter/memory/` regardless of cwd or ancestor stores, scaffolding `.crouter/` there if absent. THE way to place a doc in a specific project’s store (e.g. another project in your profile’s purview) without cd’ing there, and the only way to target a dir shadowed by an ancestor store. Implies --scope project; rejects --scope user/profile.' },
             { kind: 'flag', name: 'profile', type: 'string', required: false, constraint: 'Profile id or name to write under, for --scope profile. Default: the process CRTR_PROFILE_ID (the node\u2019s selected profile). Resolved through the same profile lookup as `crtr profile show`; ignored for any other --scope.' },
             { kind: 'stdin', name: 'body', required: true, constraint: 'Document body (markdown, no frontmatter). Piped on stdin, or passed as the bare positional after <name>.' },
@@ -40,7 +40,7 @@ export const writeLeaf = defineLeaf({
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'The path-derived document name written.' },
             { name: 'kind', type: 'string', required: true, constraint: 'Kind recorded in frontmatter.' },
-            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user, project, or profile.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was written to: user, project, profile, or node.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the written document — edit this file directly for later body tweaks instead of re-running write.' },
             { name: 'created', type: 'boolean', required: true, constraint: 'true when a new document was created, false when an existing one was updated in place.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back or list the inventory.' },