@north-light/crouter 0.3.175 → 0.3.176

package/dist/commands/node/create.js

@@ -71,7 +71,7 @@ function nodeNewParams() {
         { kind: 'stdin', name: 'prompt', required: false, constraint: 'First user message. Required unless --no-kickoff is given.' },
         { kind: 'flag', name: 'kind', type: 'string', required: false, default: 'general', constraint: 'Persona kind. The <kinds> list below names every top-level installable kind.' },
         { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for hands-on work; orchestrator when the unit itself needs decomposition across children.' },
-        { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Directory the node is pinned to. Defaults to the caller cwd.' },
+        { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Pin the node to this directory. Defaults to the spawner\u2019s directory for a managed child, and to the profile home for a root (`crtr profile show <profile>`).' },
         { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name. Defaults to the kind.' },
         { 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.' },
@@ -106,7 +106,7 @@ async function runNodeCreation(input) {
     }
     const kind = input['kind'] ?? 'general';
     const mode = (input['mode'] ?? 'base');
-    const cwd = input['cwd'] ?? process.cwd();
+    const pinCwd = input['cwd']?.trim();
     const name = input['name'];
     const parent = input['parent'];
     const root = input['root'] === true;
@@ -140,7 +140,11 @@ async function runNodeCreation(input) {
     const detail = await cliClient().createNode({
         kind,
         mode,
-        cwd,
+        // The caller's directory is the profile-SELECTION context; where the node
+        // actually lands is resolved server-side (pin > spawner's cwd > profile
+        // home). Only `--cwd` pins.
+        cwd: process.cwd(),
+        ...(pinCwd !== undefined && pinCwd !== '' ? { pin_cwd: pinCwd } : {}),
         ...(name !== undefined ? { name } : {}),
         prompt,
         ...(root ? { root: true } : { parent: parentId ?? null }),

package/dist/commands/profile/list.js

@@ -4,7 +4,7 @@ import { listProfiles } from '../../core/profiles/manifest.js';
 export const listLeaf = defineLeaf({
     name: 'list',
     description: 'inventory every profile',
-    whenToUse: 'browse every profile that exists — one line each with its id, name, project count, and last-used time. Reach for `profile show` once you have picked one, for its full project list.',
+    whenToUse: 'browse every profile that exists — one line each with its id, name, project count, home directory, and last-used time. Reach for `profile show` once you have picked one, for its full project list.',
     help: {
         name: 'profile list',
         summary: 'every profile as JSONL, one line each, sorted by name then profile_id',
@@ -12,6 +12,7 @@ export const listLeaf = defineLeaf({
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
             { name: 'projects_count', type: 'int', required: true, constraint: 'Number of project directories on the manifest.' },
+            { name: 'home', type: 'string | null', required: true, constraint: 'Directory the profile\u2019s nodes are pinned to, or null when it owns no projects.' },
             { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
         ],
         outputKind: 'jsonl',
@@ -27,6 +28,7 @@ export const listLeaf = defineLeaf({
                 profile_id: profileId,
                 name: manifest.name,
                 projects_count: manifest.projects.length,
+                home: manifest.home,
                 last_used_at: manifest.last_used_at,
             });
         }

package/dist/commands/profile/new.js

@@ -28,7 +28,7 @@ export const newLeaf = defineLeaf({
                 name: 'project',
                 type: 'path',
                 required: false,
-                constraint: 'One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Singular — add more with `crtr profile project add` after creation.',
+                constraint: "One initial project directory. Must already exist and be a directory; resolved to its absolute real path before storing. Also becomes the profile's home — where its nodes are pinned. Singular — add more with `crtr profile project add` after creation.",
             },
         ],
         output: [
@@ -36,6 +36,7 @@ export const newLeaf = defineLeaf({
             { name: 'name', type: 'string', required: true, constraint: 'The manifest name as given.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the profile directory.' },
             { name: 'projects', type: 'string[]', required: true, constraint: 'Resolved absolute project directories, in manifest order. Empty when --project was omitted.' },
+            { name: 'home', type: 'string | null', required: true, constraint: 'Directory the profile\u2019s nodes are pinned to — the initial project, or null when none was given.' },
             { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
@@ -56,6 +57,7 @@ export const newLeaf = defineLeaf({
                 name: manifest.name,
                 path: profileRoot(profileId),
                 projects: manifest.projects,
+                home: manifest.home,
                 created_at: manifest.created_at,
                 follow_up: `Root profile ensured. Spawn nodes under it with \`--profile ${profileId}\`, or widen its purview with \`crtr profile project add ${profileId} --dir <path>\`.`,
             };
@@ -68,6 +70,7 @@ export const newLeaf = defineLeaf({
             name: manifest.name,
             path: profileRoot(profileId),
             projects: manifest.projects,
+            home: manifest.home,
             created_at: manifest.created_at,
             follow_up: `Show it with \`crtr profile show ${profileId}\`, add another project with \`crtr profile project add ${profileId} --dir <path>\`, or list every profile with \`crtr profile list\`.`,
         };

package/dist/commands/profile/project.js

@@ -1,13 +1,14 @@
 // `crtr profile project` — the project-purview sub-noun of `profile`. A
-// profile's `projects` list is what it can SEE (memory + config resolution).
-// These two verbs widen or narrow that list after creation; `crtr profile
-// show` reads it back.
+// profile's `projects` list is what it can SEE (memory + config resolution),
+// and its `home` — one of those dirs — is where its nodes actually run. These
+// two verbs widen or narrow that list after creation and re-point the home;
+// `crtr profile show` reads both back.
 import { defineLeaf, defineBranch } from '../../core/command.js';
 import { addProfileProject, removeProfileProject, loadProfileManifest } from '../../core/profiles/manifest.js';
 const addLeaf = defineLeaf({
     name: 'add',
     description: "add a project directory to a profile's purview",
-    whenToUse: "a profile needs to see (memory + config from) another project directory — extend its purview after creation, including mid-session from a node already running under that profile.",
+    whenToUse: "a profile needs to see (memory + config from) another project directory — extend its purview after creation, including mid-session from a node already running under that profile. Also the way to re-point the profile's home, with --home.",
     help: {
         name: 'profile project add',
         summary: "append a project directory to a profile's manifest, deduped by real path",
@@ -25,21 +26,32 @@ const addLeaf = defineLeaf({
                 required: true,
                 constraint: 'Directory to add. Must exist and be a directory; resolved to its absolute real path before storing. A path already on the manifest is a no-op, not an error.',
             },
+            {
+                kind: 'flag',
+                name: 'home',
+                type: 'bool',
+                required: false,
+                constraint: "Also make this directory the profile's home — where every node under it is pinned unless the create passes an explicit --cwd. Defaults to the first project dir; pass this on an already-listed dir to re-point it.",
+            },
         ],
         output: [
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'projects', type: 'string[]', required: true, constraint: 'The updated, deduped project list in manifest order.' },
+            { name: 'home', type: 'string | null', required: true, constraint: "The profile's home directory after the change." },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
         outputKind: 'object',
-        effects: ["Appends to the profile manifest's `projects` array. Invalidates the process scope cache."],
+        effects: ["Appends to the profile manifest's `projects` array, and rewrites `home` when --home is given. Invalidates the process scope cache."],
     },
     run: async (input) => {
         const { profileId } = loadProfileManifest(input['profile']);
-        const { manifest } = addProfileProject(profileId, input['dir']);
+        const { manifest } = addProfileProject(profileId, input['dir'], {
+            home: input['home'] === true,
+        });
         return {
             profile_id: profileId,
             projects: manifest.projects,
+            home: manifest.home,
             follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
         };
     },
@@ -63,16 +75,17 @@ const removeLeaf = defineLeaf({
                 name: 'dir',
                 type: 'path',
                 required: true,
-                constraint: 'Directory to remove, matched by its resolved real path against the manifest. Does not require the directory to still exist on disk.',
+                constraint: 'Directory to remove, matched by its resolved real path against the manifest. Does not require the directory to still exist on disk. Removing the home dir re-points the home at the first remaining project.',
             },
         ],
         output: [
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'projects', type: 'string[]', required: true, constraint: 'The updated project list in manifest order.' },
+            { name: 'home', type: 'string | null', required: true, constraint: "The profile's home directory after the change." },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
         ],
         outputKind: 'object',
-        effects: ["Removes an entry from the profile manifest's `projects` array. Invalidates the process scope cache."],
+        effects: ["Removes an entry from the profile manifest's `projects` array, re-pointing `home` when that entry was it. Invalidates the process scope cache."],
     },
     run: async (input) => {
         const { profileId } = loadProfileManifest(input['profile']);
@@ -80,6 +93,7 @@ const removeLeaf = defineLeaf({
         return {
             profile_id: profileId,
             projects: manifest.projects,
+            home: manifest.home,
             follow_up: `Show the full manifest with \`crtr profile show ${profileId}\`.`,
         };
     },
@@ -91,7 +105,7 @@ export const projectBranch = defineBranch({
     help: {
         name: 'profile project',
         summary: "manage a profile's project purview — the directories it resolves memory and config from",
-        model: "A profile's `projects` list is the set of directories it inherits memory and config from. `add` widens that purview by one directory (deduped by real path); `remove` narrows it. Read the current list with `crtr profile show`. Purview is independent of a per-cwd default pin (`crtr profile default`) — widening purview never changes which profile a directory defaults to.",
+        model: "A profile's `projects` list is the set of directories it inherits memory and config from, and its `home` — the first project unless `add --home` says otherwise — is the directory its nodes are pinned to. `add` widens that purview by one directory (deduped by real path) and optionally re-points the home; `remove` narrows it, re-pointing the home when it removed it. Read both back with `crtr profile show`. Purview is independent of a per-cwd default pin (`crtr profile default`) — widening purview never changes which profile a directory defaults to.",
     },
     children: [addLeaf, removeLeaf],
 });

package/dist/commands/profile/show.js

@@ -6,7 +6,7 @@ import { CONFIG_FILE } from '../../types.js';
 export const showLeaf = defineLeaf({
     name: 'show',
     description: "one profile's manifest in full",
-    whenToUse: "you need a profile's full project list, id, and timestamps — after `profile list` narrows to a name, or to inspect what a node's bearings named as its profile.",
+    whenToUse: "you need a profile's full project list, home directory, id, and timestamps — after `profile list` narrows to a name, to find where its nodes will run, or to inspect what a node's bearings named as its profile.",
     help: {
         name: 'profile show',
         summary: "print one profile's manifest plus its on-disk path and config.json location",
@@ -22,6 +22,7 @@ export const showLeaf = defineLeaf({
             { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
             { name: 'name', type: 'string', required: true, constraint: 'Manifest name.' },
             { name: 'projects', type: 'string[]', required: true, constraint: 'Absolute project directories, in manifest order.' },
+            { name: 'home', type: 'string | null', required: true, constraint: 'The directory every node under this profile is pinned to unless its create passes an explicit --cwd. Defaults to the first project; re-point it with `profile project add --home`. Null when the profile owns no projects (the root profile), in which case nodes fall back to the creating directory.' },
             { name: 'created_at', type: 'string', required: true, constraint: 'ISO 8601 creation timestamp.' },
             { name: 'last_used_at', type: 'string | null', required: true, constraint: 'ISO 8601 timestamp of the most recent selection, or null if never selected.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the profile directory.' },
@@ -39,6 +40,7 @@ export const showLeaf = defineLeaf({
             profile_id: profileId,
             name: manifest.name,
             projects: manifest.projects,
+            home: manifest.home,
             created_at: manifest.created_at,
             last_used_at: manifest.last_used_at,
             path: profileRoot(profileId),

package/dist/commands/profile.js

@@ -23,14 +23,14 @@ export function registerProfile() {
     return defineBranch({
         name: 'profile',
         rootEntry: {
-            concept: 'an agent identity defined at the user root — a manifest naming project directories plus its own memory store',
+            concept: 'an agent identity defined at the user root — a manifest naming project directories and the home its nodes run in, plus its own memory store',
             desc: 'create, inspect, and manage profiles',
             useWhen: 'creating a new agent identity, inspecting or listing existing ones, changing a profile\u2019s project purview, pinning which profile a directory defaults to at startup, or managing a profile\u2019s stored env vars. Selecting a profile for a one-off run (`--profile`) lives elsewhere.',
         },
         help: {
             name: 'profile',
             summary: 'create, inspect, and manage profiles \u2014 agent identities with their own project purview and memory store',
-            model: '`new` creates one from a name (+ at most one initial `--project`). `list` inventories every profile as JSONL. `show` prints one manifest in full. `rename` changes only the manifest name \u2014 the profile_id is stable across a rename. `delete` removes a profile\u2019s directory (manifest + its own memory store) entirely and does not touch the project directories it pointed at. `project` widens/narrows a profile\u2019s project purview (the dirs it resolves memory + config from). `default` pins which profile a directory defaults to at startup so the chooser stops asking \u2014 directory-scoped, independent of purview. `env` manages a profile-scoped 0600 store of env vars injected directly into every broker launched under that profile \u2014 set on stdin, list names only (never values), or remove one; no `spawnEnv.allow` entry needed. Every manifest verb but `new`/`list` takes <profile> as an exact id or a unique manifest name; an ambiguous name fails listing every matching id.',
+            model: 'A profile owns a `home` — the first of its project dirs unless `project add --home` re-points it — and every node created under the profile is pinned there, so cwd selects the profile and the profile then supplies where its nodes run. Only `node new --cwd` (or inheriting a spawner already elsewhere, notably inside a managed worktree) overrides that; the root profile has no home, so nodes under it stay in the directory that created them. `new` creates one from a name (+ at most one initial `--project`, which becomes its home). `list` inventories every profile as JSONL. `show` prints one manifest in full. `rename` changes only the manifest name \u2014 the profile_id is stable across a rename. `delete` removes a profile\u2019s directory (manifest + its own memory store) entirely and does not touch the project directories it pointed at. `project` widens/narrows a profile\u2019s project purview (the dirs it resolves memory + config from). `default` pins which profile a directory defaults to at startup so the chooser stops asking \u2014 directory-scoped, independent of purview. `env` manages a profile-scoped 0600 store of env vars injected directly into every broker launched under that profile \u2014 set on stdin, list names only (never values), or remove one; no `spawnEnv.allow` entry needed. Every manifest verb but `new`/`list` takes <profile> as an exact id or a unique manifest name; an ambiguous name fails listing every matching id.',
         },
         children: [newLeaf, listLeaf, showLeaf, renameLeaf, deleteLeaf, projectBranch, defaultBranch, envBranch],
     });

package/dist/commands/sys/logs.js

@@ -3,7 +3,7 @@ import { isSafeNodeId } from '../../core/canvas/paths.js';
 import { usage } from '../../core/errors.js';
 import { validateOperationId } from '../../core/events/operation-id.js';
 import { readLogSnapshot } from '../../core/events/read.js';
-import { emitLine, isJsonOutput } from '../../core/io.js';
+import { emitLine, isJsonOutput, recordPreviewLine } from '../../core/io.js';
 const ISO_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/u;
 const MAX_PATTERN_BYTES = 4_096;
 function invalidFlag(flag, received, expected) {
@@ -116,8 +116,10 @@ export const sysLogsLeaf = defineLeaf({
             if (item.kind === 'event') {
                 if (json)
                     emitLine({ ...item.envelope });
-                else
+                else {
+                    recordPreviewLine({ ...item.envelope });
                     process.stdout.write(`${renderEvent(item.envelope)}\n`);
+                }
             }
             else if (!json) {
                 process.stdout.write(`RAW ${item.source} ${new Date(item.effectiveTsMs).toISOString()} ${JSON.stringify(item.content)}\n`);

package/dist/core/__tests__/branded-host-concurrency.test.js

@@ -35,7 +35,7 @@ test('concurrent processes reconcile one coherent branded host tuple', async ()
     assert.ok(deadOwner !== undefined);
     const abandonedLock = join(home, '.crouter', 'host.lock');
     mkdirSync(abandonedLock);
-    writeFileSync(join(abandonedLock, 'owner.json'), JSON.stringify({ pid: deadOwner, token: 'abandoned' }));
+    writeFileSync(join(abandonedLock, `owner.${deadOwner}.abandoned`), '');
     try {
         const moduleUrl = pathToFileURL(join(process.cwd(), 'src/core/runtime/branded-host.ts')).href;
         const results = await Promise.all(Array.from({ length: 4 }, () => reconcileInChild(home, moduleUrl)));

package/dist/core/__tests__/on-read-crouter-home-fence.test.js

@@ -13,7 +13,7 @@ import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
 import { resetScopeCache } from '../scope.js';
 import { spawnNode } from '../runtime/nodes.js';
-import { renderOnReadDocs } from '../substrate/on-read.js';
+import { renderOnReadDocs } from '../substrate/on-read-node.js';
 let canvasHome;
 let fakeHome;
 let prevHomeEnv;

package/dist/core/__tests__/on-read-dedup-resume.test.js

@@ -13,7 +13,7 @@ import { join } from 'node:path';
 import { closeDb } from '../canvas/db.js';
 import { resetScopeCache } from '../scope.js';
 import { spawnNode } from '../runtime/nodes.js';
-import { renderOnReadDocs } from '../substrate/on-read.js';
+import { renderOnReadDocs } from '../substrate/on-read-node.js';
 import { loadInjectedDocs, saveInjectedDocs, clearInjectedDocs, } from '../substrate/injected-store.js';
 const FIXTURE_BODY = 'Fixture body that must surface exactly once.';
 let home;

package/dist/core/canvas/extensions.d.ts

@@ -1,4 +1,4 @@
-export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve"];
+export declare const CANVAS_EXTENSION_NAMES: readonly ["canvas-inbox-watcher", "canvas-review-boundary", "canvas-stophook", "canvas-recap", "canvas-goal-capture", "canvas-passive-context", "canvas-context-intro", "canvas-tool-guide", "canvas-doc-substrate", "canvas-structured-output", "canvas-bash-valve", "canvas-preview-result"];
 /** Structural shipped-hook identity: a canvas-hook stem directly under a
  * `pi-extensions` directory. A user's own extension elsewhere may share the
  * stem and is not shipped. */

package/dist/core/canvas/extensions.js

@@ -7,9 +7,15 @@ export const CANVAS_EXTENSION_NAMES = [
     'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
     'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
     'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
-    'canvas-bash-valve',
+    'canvas-bash-valve', 'canvas-preview-result',
 ];
 const HISTORICAL_CANVAS_EXTENSION_PREFIXES = [
+    [
+        'canvas-inbox-watcher', 'canvas-review-boundary', 'canvas-stophook', 'canvas-recap',
+        'canvas-goal-capture', 'canvas-passive-context', 'canvas-context-intro',
+        'canvas-tool-guide', 'canvas-doc-substrate', 'canvas-structured-output',
+        'canvas-bash-valve',
+    ],
     [
         'canvas-inbox-watcher', 'canvas-stophook', 'canvas-recap',
         'canvas-goal-capture', 'canvas-passive-context', 'canvas-review-boundary',

package/dist/core/command-plugins/transport/http-invoke.js

@@ -17,7 +17,7 @@ import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
 import { validateDeclaredResult } from './exec-invoke.js';
 import { CrtrError } from '../../errors.js';
-import { diag, writeStdout } from '../../io.js';
+import { diag, recordPreviewError, recordPreviewJsonLine, writeStdout } from '../../io.js';
 import { ExitCode } from '../../../types.js';
 // ---------------------------------------------------------------------------
 // Constants
@@ -420,6 +420,7 @@ async function requestStreaming(spec, plan) {
                 if (line.trim() === '')
                     continue; // drop blank records
                 framesEmitted = true;
+                recordPreviewJsonLine(line);
                 const ok = await writeStdout(line + '\n');
                 if (!ok) {
                     // Consumer closed the pipe (EPIPE) — stop cleanly, nothing to report.
@@ -434,6 +435,7 @@ async function requestStreaming(spec, plan) {
         // backend sent no trailing delimiter, so none is added).
         if (partial.trim() !== '') {
             framesEmitted = true;
+            recordPreviewJsonLine(partial);
             await writeStdout(partial);
         }
         return; // clean EOF → SUCCESS
@@ -444,7 +446,13 @@ async function requestStreaming(spec, plan) {
         if (framesEmitted) {
             // After a frame has been emitted: one concise stderr diagnostic + NETWORK
             // exit, and DO NOT throw (that would append an <error> to stdout).
-            diag(`crtr: ${label(spec)}: stream interrupted (${detail})`);
+            const message = `${label(spec)}: stream interrupted (${detail})`;
+            diag(`crtr: ${message}`);
+            recordPreviewError({
+                error: 'stream_interrupted',
+                message,
+                next: 'Retry the command to begin a fresh stream.',
+            });
             process.exitCode = ExitCode.NETWORK;
             return;
         }

package/dist/core/command.js

@@ -5,7 +5,7 @@
 // A plain array walk + a small flag parser is ~120 lines and has no surprising
 // edge cases.
 import { renderRoot, renderBranch, renderLeafArgv } from './help.js';
-import { readStdinRaw, peekStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
+import { beginPreview, publishPreviewResult, readStdinRaw, peekStdinRaw, emit, handle, setJsonOutput, isJsonOutput } from './io.js';
 import { renderResult } from './render.js';
 import { CrtrError } from './errors.js';
 import { operationIdContext } from './events/operation-id.js';
@@ -614,6 +614,7 @@ export async function runCli(root, argv) {
         // below: `node` is now a reassignable `let` (the §5.1 retry re-walks it),
         // which TS re-widens to the node union across an `await`.
         const leaf = node;
+        beginPreview(path.join(' '));
         const params = leaf.help.params !== undefined ? leaf.help.params : [];
         let providedParams = new Set();
         let contextFilePaths = new Map();
@@ -628,6 +629,7 @@ export async function runCli(root, argv) {
         });
         const context = { providedParams, contextFilePaths };
         const result = await operationIdContext.fresh(() => leaf.run(input, context));
+        publishPreviewResult(result);
         if (result !== undefined && result !== null) {
             if (isJsonOutput()) {
                 emit(result);

package/dist/core/config.js

@@ -1,4 +1,3 @@
-import { mkdirSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { CONFIG_FILE, STATE_FILE, CONDENSED_HISTORY_MODES, MOUSE_MODE_DEFAULTS, DEFAULT_WHIP_MESSAGES, defaultScopeConfig, defaultScopeState, defaultModelLaddersConfig, defaultKindsConfig, defaultRemoteCanvasConfig } from '../types.js';
@@ -7,6 +6,7 @@ import { emitEvent } from './events/emit.js';
 import { atomicWriteJson, readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot, findProjectScopeRoots } from './scope.js';
 import { profileRoot } from './profiles/manifest.js';
+import { withExclusiveDirectoryLock } from './exclusive-lock.js';
 import { SCOPE_CONFIG_KEYS } from './user-settings.js';
 import { normalizeWorkingGerunds } from '../shared/working-activity.js';
 function configPathFor(root) {
@@ -54,34 +54,11 @@ export function readState(scope) {
         activeCanvas: existing.activeCanvas ?? null,
     };
 }
-const CONFIG_LOCK_TIMEOUT_MS = 5000;
-const CONFIG_LOCK_POLL_MS = 25;
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
 function withConfigPathLock(path, run) {
     ensureDir(dirname(path));
-    const lockPath = `${path}.lock`;
-    const deadline = Date.now() + CONFIG_LOCK_TIMEOUT_MS;
-    for (;;) {
-        try {
-            mkdirSync(lockPath);
-            break;
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
-            if (Date.now() > deadline)
-                throw new Error(`timed out waiting for config lock: ${path}`);
-            sleepSync(CONFIG_LOCK_POLL_MS);
-        }
-    }
-    try {
-        return run(path);
-    }
-    finally {
-        rmSync(lockPath, { recursive: true, force: true });
-    }
+    return withExclusiveDirectoryLock(`${path}.lock`, () => run(path), {
+        timeoutError: () => new Error(`timed out waiting for config lock: ${path}`),
+    });
 }
 function withConfigLock(scope, run) {
     const root = requireScopeRoot(scope);

package/dist/core/exclusive-lock.d.ts

@@ -0,0 +1,14 @@
+export interface ExclusiveLockOptions {
+    /** Grace before a lock that names no owner at all is cleared. */
+    staleMs?: number;
+    timeoutMs?: number;
+    /** The error thrown when the wait runs out, so callers keep their own remediation. */
+    timeoutError?: () => Error;
+}
+/**
+ * Run a short filesystem transition under a token-checked, crash-reclaimable
+ * directory lock. A holder that dies releases immediately — the next contender
+ * sees a dead pid in the marker name — while a live holder is never stolen from,
+ * however long its operation runs.
+ */
+export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: ExclusiveLockOptions): T;

package/dist/core/exclusive-lock.js

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readdirSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+const MARKER_PREFIX = 'owner.';
+const POLL_MS = 10;
+const DEFAULT_STALE_MS = 30_000;
+const DEFAULT_TIMEOUT_MS = 5_000;
+function pause(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+function markerPath(path, token) { return `${path}/${MARKER_PREFIX}${token}`; }
+function observedMarkerToken(path) {
+    try {
+        return readdirSync(path).find((entry) => entry.startsWith(MARKER_PREFIX))?.slice(MARKER_PREFIX.length) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The token opens with the owner's pid, so liveness reads off the name. */
+function ownerIsAlive(token) {
+    const pid = Number(token.split('.', 1)[0]);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function isEmptyDirectory(path) {
+    try {
+        return readdirSync(path).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function ageMs(path) {
+    try {
+        return Date.now() - statSync(path).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+// Reclamation is bound to the exact instance it observed: it unlinks ONLY that
+// token's marker, then removes the now-empty directory with an empty-guarded
+// rmdir. A successor holds a different random token — a different marker name —
+// so a lagging reclaimer that saw the old dead lock can never strip a live
+// successor: its unlink targets a name that no longer exists.
+function reclaimIfOwnerGone(path, staleMs) {
+    const token = observedMarkerToken(path);
+    if (token !== null) {
+        if (ownerIsAlive(token))
+            return;
+        try {
+            unlinkSync(markerPath(path, token));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    else {
+        // Nothing names an owner. A live holder always has its marker, so this is a
+        // crash between mkdir and the marker write, or a lock left in some older
+        // shape; age is the only evidence, and an empty-guarded rmdir still cannot
+        // take a successor that has since claimed the name.
+        if (ageMs(path) <= staleMs)
+            return;
+        if (!isEmptyDirectory(path)) {
+            rmSync(path, { recursive: true, force: true });
+            return;
+        }
+    }
+    try {
+        rmdirSync(path);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'ENOENT' && code !== 'ENOTEMPTY' && code !== 'EEXIST')
+            throw error;
+    }
+}
+function tryAcquire(path, staleMs) {
+    const token = `${process.pid}.${randomUUID()}`;
+    try {
+        mkdirSync(path, { mode: 0o700 });
+        writeFileSync(markerPath(path, token), '', { flag: 'wx', mode: 0o600 });
+        return { path, token };
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        reclaimIfOwnerGone(path, staleMs);
+        return null;
+    }
+}
+/**
+ * Run a short filesystem transition under a token-checked, crash-reclaimable
+ * directory lock. A holder that dies releases immediately — the next contender
+ * sees a dead pid in the marker name — while a live holder is never stolen from,
+ * however long its operation runs.
+ */
+export function withExclusiveDirectoryLock(path, operation, options = {}) {
+    const staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let lock = tryAcquire(path, staleMs);
+    while (lock === null) {
+        if (Date.now() >= deadline) {
+            throw options.timeoutError?.() ?? new Error(`timed out waiting for the exclusive lock: ${path}`);
+        }
+        pause(POLL_MS);
+        lock = tryAcquire(path, staleMs);
+    }
+    try {
+        return operation();
+    }
+    finally {
+        if (existsSync(markerPath(lock.path, lock.token)))
+            rmSync(lock.path, { recursive: true, force: true });
+    }
+}

package/dist/core/human/claim.js

@@ -1,7 +1,8 @@
 import { existsSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
-import { claimPath, deckPath, readJson, responsePath, reviewPath, withExclusiveDirectoryLock } from './convention.js';
+import { claimPath, deckPath, readJson, responsePath, reviewPath } from './convention.js';
+import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 const REMOTE_STALE_MS = 30_000;
 function parseClaim(raw) {
     if (typeof raw !== 'object' || raw === null)

package/dist/core/human/convention.d.ts

@@ -15,16 +15,6 @@ export declare function atomicWriteJson(path: string, value: unknown): void;
 /** Publish one immutable JSON record without replacing an existing winner. */
 export declare function publishJsonExclusive(path: string, value: unknown): boolean;
 export declare function readJson<T>(path: string): T | null;
-/** Runs a short filesystem transition under a token-checked, crash-reclaimable directory lock. */
-export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: {
-    staleMs?: number;
-    timeoutMs?: number;
-}): T;
-/** Async counterpart heartbeats while its operation runs, so a valid long handler is never stolen. */
-export declare function withExclusiveDirectoryLockAsync<T>(path: string, operation: () => Promise<T>, options?: {
-    staleMs?: number;
-    timeoutMs?: number;
-}): Promise<T>;
 export declare function writeResponse(dir: string, responses: InteractionResponse[], completedAt: string, deck?: Deck): string;
 export declare function writeProgress(dir: string, responses: InteractionResponse[]): void;
 export declare function clearProgress(dir: string): void;