@crouton-kit/crouter 0.3.41 → 0.3.42

package/dist/clients/attach/view-socket.d.ts

@@ -16,7 +16,8 @@ export type ReadOpRequest = Omit<ListModelsFrame, 'id'> | Omit<ListSessionsFrame
  *  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's own ~30s bound caps an indefinite wait). */
+ *  trying (the supervisor waits at a relaxed cadence for as long as the row
+ *  stays live). */
 export declare function reconnectShouldGiveUp(row: NodeRow | null): boolean;
 export declare class BrokerUnavailableError extends Error {
     readonly nodeId: string;
@@ -45,6 +46,12 @@ export declare class ViewSocketClient extends EventEmitter {
      *  Resolved by the matching `data` frame / rejected by the matching `error`
      *  frame in {@link onData}, the request's timeout, or socket teardown. */
     private pending;
+    /** 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. */
+    private redialFaultRecorded;
     constructor(nodeId: string);
     private recordSocketFault;
     /** Issue a correlated read-op and resolve with the broker's `data` reply (or

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

@@ -38,7 +38,8 @@ const REQUEST_TIMEOUT_MS = 10_000;
  *  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's own ~30s bound caps an indefinite wait). */
+ *  trying (the supervisor waits at a relaxed cadence for as long as the row
+ *  stays live). */
 export function reconnectShouldGiveUp(row) {
     if (row === null)
         return true;
@@ -61,11 +62,22 @@ export class ViewSocketClient extends EventEmitter {
      *  Resolved by the matching `data` frame / rejected by the matching `error`
      *  frame in {@link onData}, the request's timeout, or socket 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) {
         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',
@@ -122,6 +134,7 @@ export class ViewSocketClient extends EventEmitter {
         const socket = createConnection(this.socketPath);
         this.socket = socket;
         socket.on('connect', () => {
+            this.redialFaultRecorded = false;
             clearFault(this.nodeId, { link: 'viewer↔broker' });
             this.emit('connect');
         });
@@ -148,6 +161,7 @@ export class ViewSocketClient extends EventEmitter {
                 if (settled)
                     return;
                 settled = true;
+                this.redialFaultRecorded = false;
                 clearFault(this.nodeId, { link: 'viewer↔broker' });
                 this.emit('connect');
                 resolve();

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

@@ -12,9 +12,13 @@ export declare function scopeRank(scope: MemoryScope): number;
  *  always resolves. `--scope profile` is NEVER a default — it requires a
  *  selected profile, from `profileArg` (an explicit `--profile <id-or-name>`)
  *  or else the process's `CRTR_PROFILE_ID`, resolved through the centralized
- *  `loadProfileManifest` (never a raw path join). Returns the absolute
- *  `<root>/memory` dir to write under. */
-export declare function resolveWriteTarget(scopeArg: string | undefined, profileArg?: string): {
+ *  `loadProfileManifest` (never a raw path join). `dirArg` (an explicit
+ *  `--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. */
+export declare function resolveWriteTarget(scopeArg: string | undefined, profileArg?: string, dirArg?: string): {
     scope: MemoryScope;
     memoryDir: string;
 };

package/dist/commands/memory/shared.js

@@ -3,10 +3,12 @@
 // scope modules and build their documented output objects on top of the small
 // helpers here. Nothing in this file forks on kind or re-implements the
 // schema/gate/resolver — it only composes them.
-import { join } from 'node:path';
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { usage } from '../../core/errors.js';
-import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, } from '../../core/scope.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';
 // The two memory kinds — knowledge (consult: procedural playbooks + factual
 // references merged) vs preference (behave: standing directives). Used as the
@@ -29,9 +31,37 @@ export function scopeRank(scope) {
  *  always resolves. `--scope profile` is NEVER a default — it requires a
  *  selected profile, from `profileArg` (an explicit `--profile <id-or-name>`)
  *  or else the process's `CRTR_PROFILE_ID`, resolved through the centralized
- *  `loadProfileManifest` (never a raw path join). Returns the absolute
- *  `<root>/memory` dir to write under. */
-export function resolveWriteTarget(scopeArg, profileArg) {
+ *  `loadProfileManifest` (never a raw path join). `dirArg` (an explicit
+ *  `--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. */
+export function resolveWriteTarget(scopeArg, profileArg, dirArg) {
+    if (dirArg !== undefined && dirArg !== '') {
+        if (scopeArg !== undefined && scopeArg !== 'project') {
+            throw usage(`--dir targets a project store and cannot combine with --scope ${scopeArg}`);
+        }
+        const abs = resolvePath(dirArg);
+        if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+            throw usage(`--dir does not exist or is not a directory: ${dirArg}`, {
+                received: dirArg,
+                next: 'Pass an existing project directory.',
+            });
+        }
+        let real = abs;
+        try {
+            real = realpathSync(abs);
+        }
+        catch {
+            /* fall back to the resolved path */
+        }
+        // The scaffold (mkdir of `.crouter/memory/`) happens at write time via the
+        // writer's ensureDir; drop the scope cache so this process's later
+        // resolves see the new root.
+        resetScopeCache();
+        return { scope: 'project', memoryDir: join(real, CRTR_DIR_NAME, 'memory') };
+    }
     let scope;
     if (scopeArg === 'user' || scopeArg === 'project' || scopeArg === 'profile') {
         scope = scopeArg;

package/dist/commands/memory/write.js

@@ -13,7 +13,7 @@ export const writeLeaf = defineLeaf({
         guide: 'The body is the easy part; the craft is routing — every frontmatter flag decides who sees this doc, when, and at what context cost. Each rung up is paid by every future agent at every boot or read, forever, so default each rung down.\n\n' +
             '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' +
             '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 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/ 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' +
+            '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' +
             'Find before write. Group related docs with path names (area/topic). Do not store what is already recorded or what only matters to this conversation. Body is for current truth, not history. Provenance is automatic on create and preserved on update. Validate after authoring.',
@@ -27,7 +27,8 @@ export const writeLeaf = defineLeaf({
             { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate — YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
             { kind: 'flag', name: 'applies-to', type: 'string', required: false, constraint: 'Frontmatter applies-to — glob/path scope the document applies to.' },
             { 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: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Target scope. Default: project when inside a project, else user. `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.' },
+            { 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>.' },
         ],
@@ -50,7 +51,8 @@ export const writeLeaf = defineLeaf({
         const scopeArg = input['scope'];
         const profileArg = input['profile'];
         const body = input['body'] ?? '';
-        const { scope, memoryDir } = resolveWriteTarget(scopeArg, profileArg);
+        const dirArg = input['dir'];
+        const { scope, memoryDir } = resolveWriteTarget(scopeArg, profileArg, dirArg);
         const path = memoryFilePath(memoryDir, name);
         const created = !pathExists(path);
         // CREATE requires the read-routing line that becomes the preview — without

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

@@ -1,7 +1,9 @@
 /** Select the profile a node about to boot at `cwd` should run under.
  *
- *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`,
- *     bump `last_used_at`, return the id.
+ *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`. If
+ *     its manifest does not already cover `cwd` and the session is interactive,
+ *     offer to add `cwd` to its purview (default yes). Bump `last_used_at`,
+ *     return the id.
  *  2. Else, among profiles whose project list COVERS `cwd`, pick the
  *     most-recently-used (nulls oldest), bump its `last_used_at`, return it.
  *  3. Else — nothing covers cwd. Interactive session: prompt synchronously to

package/dist/core/profiles/select.js

@@ -5,7 +5,7 @@
 import { existsSync, realpathSync } from 'node:fs';
 import { basename, resolve as resolvePath, sep } from 'node:path';
 import { createInterface } from 'node:readline/promises';
-import { listProfiles, loadProfileManifest, updateProfileLastUsed, createProfile, } from './manifest.js';
+import { listProfiles, loadProfileManifest, updateProfileLastUsed, createProfile, addProfileProject, } from './manifest.js';
 /** Resolve cwd to an absolute, realpath'd form so it compares against the
  *  realpath'd project dirs `createProfile`/`addProfileProject` already store
  *  (manifest.ts resolves every project dir through `realpathSync`). Falls back
@@ -66,6 +66,25 @@ function recoveryMessage(cwd) {
  *  artifact or a queued interaction, not a two-choice gate on the same TTY pi
  *  is about to take over — a raw `readline` question is the actual minimal
  *  fit here. */
+/** Explicit `--profile` names a profile whose manifest does NOT cover cwd.
+ *  Interactive only: offer to widen the profile's purview to include this
+ *  directory (default yes), so the next node started here is covered without a
+ *  separate `crtr profile add-project`. Declining leaves the manifest untouched
+ *  and runs the node under the profile anyway. Same raw-readline rationale as
+ *  `promptCreateOrRoot` — this gates pi's boot on the same TTY. */
+async function promptAddDirToProfile(entry, cwd) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        process.stdout.write(`\nProfile "${entry.manifest.name}" does not cover this directory:\n  ${cwd}\n\n`);
+        const choice = (await rl.question('Add it to the profile? [Y/n]: ')).trim().toLowerCase();
+        if (choice === 'n' || choice === 'no')
+            return;
+        addProfileProject(entry.profileId, cwd);
+    }
+    finally {
+        rl.close();
+    }
+}
 async function promptCreateOrRoot(cwd) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -86,8 +105,10 @@ async function promptCreateOrRoot(cwd) {
 }
 /** Select the profile a node about to boot at `cwd` should run under.
  *
- *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`,
- *     bump `last_used_at`, return the id.
+ *  1. `explicitProfile` present → resolve id/name via `loadProfileManifest`. If
+ *     its manifest does not already cover `cwd` and the session is interactive,
+ *     offer to add `cwd` to its purview (default yes). Bump `last_used_at`,
+ *     return the id.
  *  2. Else, among profiles whose project list COVERS `cwd`, pick the
  *     most-recently-used (nulls oldest), bump its `last_used_at`, return it.
  *  3. Else — nothing covers cwd. Interactive session: prompt synchronously to
@@ -95,12 +116,17 @@ async function promptCreateOrRoot(cwd) {
  *     interactive (no TTY): default to root (null) and print the recovery
  *     instruction to STDERR — never stdout, which the caller may be piping. */
 export async function selectProfileForCwd(cwd, explicitProfile) {
+    const resolvedCwd = resolveCwd(cwd);
     if (explicitProfile !== undefined && explicitProfile !== null && explicitProfile !== '') {
         const entry = loadProfileManifest(explicitProfile);
+        // Selecting a profile from a directory it does not yet cover: offer to
+        // widen its purview (interactive only, default yes) before pi boots.
+        if (!profileCoversCwd(entry, resolvedCwd) && isInteractive()) {
+            await promptAddDirToProfile(entry, resolvedCwd);
+        }
         updateProfileLastUsed(entry.profileId);
         return entry.profileId;
     }
-    const resolvedCwd = resolveCwd(cwd);
     const covering = listProfiles().filter((p) => profileCoversCwd(p, resolvedCwd));
     if (covering.length > 0) {
         const winner = pickMostRecent(covering);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.41",
+  "version": "0.3.42",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",