@north-light/crouter 0.3.232 → 0.3.234

package/dist/core/preview-result-path.js

@@ -7,6 +7,7 @@
 // into the command text — the executed script has to stay exactly what the
 // agent wrote, because `cmd.sh`, job inspection, and the doc substrate's
 // `command` surfaces all read that text as the agent's own words.
+import { envNodeId } from '../shared/env.js';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 export const PREVIEW_RESULT_PATH_ENV = 'CRTR_PREVIEW_RESULT_PATH';
@@ -16,7 +17,7 @@ export const PREVIEW_RESULT_PATH_ENV = 'CRTR_PREVIEW_RESULT_PATH';
  *  Node id and pid are equal across both sides of the transport (they run in
  *  the same broker process) without either side sharing state. */
 function brokerToken() {
-    return `${encodeURIComponent(process.env['CRTR_NODE_ID'] ?? 'no-node')}-${process.pid}`;
+    return `${encodeURIComponent(envNodeId() ?? 'no-node')}-${process.pid}`;
 }
 /** Deterministic from the tool call id, so the spawning side and the result
  *  side derive the same path without sharing state. */

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

@@ -24,12 +24,44 @@ export interface ProfileEntry {
     profileId: string;
     manifest: ProfileManifest;
 }
-/** Every profile with a readable manifest, in directory-listing order.
- *  Enumerates ONLY immediate children of `profilesRoot()` — never recurses,
- *  never trusts a caller-supplied id. A dir whose name doesn't match the
- *  generated id shape, or whose `profile.json` is missing/corrupt, is skipped
- *  rather than crashing the whole listing. */
+export interface ProfileEnumeration {
+    /** Every profile with a readable manifest, in directory-listing order. */
+    entries: ProfileEntry[];
+    /** Ids whose directory is present under the profiles root but whose manifest
+     *  did not read — corrupt JSON, a pre-object project shape, an unreadable or
+     *  missing `profile.json`. These are NOT deleted profiles, and a caller that
+     *  cannot tell the two apart silently substitutes another identity. */
+    unreadableIds: string[];
+}
+/** Every profile with a readable manifest, in directory-listing order. A
+ *  profile whose manifest is missing or corrupt is skipped rather than
+ *  crashing the whole listing — `lookupProfile` is how a caller that must not
+ *  confuse "skipped" with "gone" asks. */
 export declare function listProfiles(): ProfileEntry[];
+/** What a stored profile id resolves to — including the case every
+ *  null-returning resolver here erases: the profile is THERE and could not be
+ *  read. A caller that treats that as "deleted" substitutes another identity
+ *  (root) for the one its work was pinned to. */
+export type ProfileLookup = {
+    kind: 'resolved';
+    entry: ProfileEntry;
+}
+/** Nothing on this host answers to the id or name — a deleted profile. */
+ | {
+    kind: 'absent';
+}
+/** The id's directory is present; its manifest did not read. */
+ | {
+    kind: 'unreadable';
+    profileId: string;
+    manifestPath: string;
+};
+/** Exact resolution (generated id, else a unique manifest `name`) that reports
+ *  WHY it failed. Only an ID can come back `unreadable`: a name lives inside
+ *  the manifest that could not be read, so an unreadable profile has no name to
+ *  match on. Throws on an ambiguous name, exactly as `loadProfileManifest`
+ *  does. */
+export declare function lookupProfile(profileIdOrName: string): ProfileLookup;
 /** Read one exact profile id without falling back to manifest-name matching.
  * Used at persistence gates that already hold a resolved durable identity. */
 export declare function loadExactProfileManifest(profileId: string): ProfileEntry;

package/dist/core/profiles/manifest.js

@@ -15,10 +15,8 @@ import { ensureDir, nowIso } from '../fs-utils.js';
 import { usage, notFound, ambiguous, general } from '../errors.js';
 import { withExclusiveDirectoryLock } from '../exclusive-lock.js';
 import { fuzzyMatchProfile } from './fuzzy-match.js';
-// ---------------------------------------------------------------------------
 // Path safety — the only code in the tree that builds a path under the
 // profiles root. Every other module reaches profile paths through this file.
-// ---------------------------------------------------------------------------
 /** `<slug>-<shortid>`: slug is lower-case, non-alphanumeric collapsed to `-`,
  *  trimmed to 40 chars (defaulting to `profile`); shortid is 8 lowercase hex
  *  chars. The char class alone rules out `/`, `\`, `.`, and `..` segments —
@@ -71,11 +69,9 @@ export function profileManifestPath(profileId) {
 export function profileMemoryDir(profileId) {
     return join(profileRoot(profileId), 'memory');
 }
-// ---------------------------------------------------------------------------
 // Enumeration + resolution — the ONLY functions that turn a CLI operand into
 // a profile id. Both walk immediate children of the canonical root; neither
 // ever joins an unvalidated operand into a path.
-// ---------------------------------------------------------------------------
 /** A profile's `home` DEFAULTS to its first project dir. Normalizing here (the
  *  single read path) rather than at write time means a manifest written before
  *  homes existed, and one whose explicit home was later removed from purview,
@@ -175,16 +171,15 @@ export function profileHome(profileId) {
         return null;
     }
 }
-/** Every profile with a readable manifest, in directory-listing order.
- *  Enumerates ONLY immediate children of `profilesRoot()` — never recurses,
- *  never trusts a caller-supplied id. A dir whose name doesn't match the
- *  generated id shape, or whose `profile.json` is missing/corrupt, is skipped
- *  rather than crashing the whole listing. */
-export function listProfiles() {
+/** The one walk of the profiles root: immediate children only — never
+ *  recurses, never trusts a caller-supplied id. A dir whose name doesn't match
+ *  the generated id shape is not a profile at all and is ignored. */
+function enumerateProfiles() {
     const root = profilesRoot();
     if (!existsSync(root))
-        return [];
-    const out = [];
+        return { entries: [], unreadableIds: [] };
+    const entries = [];
+    const unreadableIds = [];
     for (const dirent of readdirSync(root, { withFileTypes: true })) {
         if (!dirent.isDirectory())
             continue;
@@ -193,10 +188,37 @@ export function listProfiles() {
             continue;
         const manifest = readManifestFile(join(root, profileId, 'profile.json'), profileId);
         if (manifest === null)
-            continue;
-        out.push({ profileId, manifest });
+            unreadableIds.push(profileId);
+        else
+            entries.push({ profileId, manifest });
     }
-    return out;
+    return { entries, unreadableIds };
+}
+/** Every profile with a readable manifest, in directory-listing order. A
+ *  profile whose manifest is missing or corrupt is skipped rather than
+ *  crashing the whole listing — `lookupProfile` is how a caller that must not
+ *  confuse "skipped" with "gone" asks. */
+export function listProfiles() {
+    return enumerateProfiles().entries;
+}
+/** Exact resolution (generated id, else a unique manifest `name`) that reports
+ *  WHY it failed. Only an ID can come back `unreadable`: a name lives inside
+ *  the manifest that could not be read, so an unreadable profile has no name to
+ *  match on. Throws on an ambiguous name, exactly as `loadProfileManifest`
+ *  does. */
+export function lookupProfile(profileIdOrName) {
+    const { entries, unreadableIds } = enumerateProfiles();
+    const exact = findExactProfile(entries, profileIdOrName);
+    if (exact !== null)
+        return { kind: 'resolved', entry: exact };
+    if (unreadableIds.includes(profileIdOrName)) {
+        return {
+            kind: 'unreadable',
+            profileId: profileIdOrName,
+            manifestPath: join(profilesRoot(), profileIdOrName, 'profile.json'),
+        };
+    }
+    return { kind: 'absent' };
 }
 // Three resolvers, in descending tolerance. `resolveProfileOperand` is what a
 // command leaf calls for a value the USER TYPED: exact id, exact name, then a
@@ -255,11 +277,13 @@ function profileNotFound(all, profileIdOrName) {
     });
 }
 export function loadProfileManifest(profileIdOrName) {
-    const all = listProfiles();
-    const exact = findExactProfile(all, profileIdOrName);
-    if (exact !== null)
-        return exact;
-    throw profileNotFound(all, profileIdOrName);
+    const lookup = lookupProfile(profileIdOrName);
+    if (lookup.kind === 'resolved')
+        return lookup.entry;
+    // Unreadable and absent both answer not-found here: this is the tolerant
+    // resolver every runtime consumer already handles that way. A caller that
+    // must NOT substitute another identity calls `lookupProfile` directly.
+    throw profileNotFound(listProfiles(), profileIdOrName);
 }
 /** Resolve a profile the USER TYPED — a `--profile` flag or a `<profile>`
  *  operand. Exact id or name wins outright; only when nothing matches exactly
@@ -316,10 +340,8 @@ function writeManifestAtomic(path, manifest) {
     writeFileSync(tmp, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
     renameSync(tmp, path);
 }
-// ---------------------------------------------------------------------------
 // Project dirs — resolved to absolute real paths, must exist + be a directory
 // on add/create, deduped by real path, stored in manifest order.
-// ---------------------------------------------------------------------------
 function resolveExistingProjectDir(dir) {
     const abs = resolvePath(dir);
     if (!existsSync(abs) || !statSync(abs).isDirectory()) {
@@ -364,11 +386,9 @@ function generateProfileId(name) {
     }
     throw general(`failed to generate a unique profile id for "${name}" after 20 attempts`);
 }
-// ---------------------------------------------------------------------------
 // Mutations — all under withProfileManifestLock, all atomic writes, all call
 // resetScopeCache() when they can change project dirs or the profile name
 // (never for a bare last-used-at touch).
-// ---------------------------------------------------------------------------
 export function ensureRootProfile() {
     return withProfileManifestLock(ROOT_PROFILE_ID, () => {
         const manifestPath = profileManifestPath(ROOT_PROFILE_ID);

package/dist/core/profiles/select.js

@@ -120,7 +120,6 @@ export function selectProfileForCwdReadOnly(cwd) {
 function isInteractive() {
     return Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
 }
-// ---------------------------------------------------------------------------
 // Pre-boot prompt presentation. These prompts print to the raw controlling
 // terminal BEFORE pi takes it over (not the attach viewer), so styling is
 // plain ANSI via the house `stdoutColor` helper (NO_COLOR / non-TTY aware) and
@@ -129,7 +128,6 @@ function isInteractive() {
 // dim subtitle, then accent-keyed option rows. We deliberately do NOT echo the
 // user's own cwd back at them (they know where they are) — the only paths
 // worth showing are OTHER dirs: which project root a covering profile owns.
-// ---------------------------------------------------------------------------
 const dim = stdoutColor.dim;
 const bold = stdoutColor.bold;
 const accent = stdoutColor.cyan;
@@ -310,7 +308,6 @@ function runMenu(bindings, title, subtitle, rows, opts = {}) {
         draw();
     });
 }
-// ---------------------------------------------------------------------------
 // The profile manager. `v` on either selection gate opens the Profiles page of
 // `crtr sys settings` in a tmux popup: this menu is a CHOOSER filtered to cwd,
 // while that page is the whole map — every profile, every directory each one
@@ -318,7 +315,6 @@ function runMenu(bindings, title, subtitle, rows, opts = {}) {
 // torn down (runMenu cleans up before resolving an action), and the caller then
 // re-runs the whole selector, so a directory just adopted or a default just
 // pinned decides the menu you come back to.
-// ---------------------------------------------------------------------------
 /** Open the profiles page in a tmux popup and block until it closes. False when
  *  there is no tmux to host it — possible only on the `crtr node new` path, as
  *  the front door requires tmux before it ever selects — after printing the

package/dist/core/review/signal.js

@@ -1,31 +1,12 @@
-import { basename, dirname, join } from 'node:path';
-import { mkdirSync, watch, writeFileSync } from 'node:fs';
-import { crtrHome } from '../canvas/paths.js';
+import { activityPath, signalActivity, watchActivity } from '../activity-signal.js';
 /** Signal one durable review mutation to every open viewer without watching every review directory. */
 export function reviewActivityPath() {
-    return join(crtrHome(), 'signals', 'review-activity');
+    return activityPath('review-activity');
 }
 /** Signal one review mutation (comment create/edit/resolve/delete/reanchor/delivery) to every open review surface. */
 export function signalReviewActivity() {
-    try {
-        mkdirSync(dirname(reviewActivityPath()), { recursive: true, mode: 0o700 });
-        writeFileSync(reviewActivityPath(), `${Date.now()}\n`, { mode: 0o600 });
-    }
-    catch {
-        // A later review read is still authoritative.
-    }
+    signalActivity('review-activity');
 }
 export function watchReviewActivity(onChange) {
-    const activityPath = reviewActivityPath();
-    try {
-        mkdirSync(dirname(activityPath), { recursive: true, mode: 0o700 });
-        const watcher = watch(dirname(activityPath), (_event, filename) => {
-            if (String(filename) === basename(activityPath))
-                onChange();
-        });
-        return () => watcher.close();
-    }
-    catch {
-        return () => { };
-    }
+    return watchActivity('review-activity', onChange);
 }

package/dist/core/review/ticket-filter.d.ts

@@ -1,13 +1,13 @@
 /**
  * Terminal-review ticket visibility filter.
- * Hides canonical review tickets by state; passes pre-cutover tickets unchanged.
+ * Hides review tickets by canonical state.
  * This module never imports canvas DB directly; daemon call sites apply the filter.
  */
 import type { TicketSummary } from '../human/types.js';
 /**
  * Determines if a review ticket should be visible based on its canonical review state.
- * A review ticket is hidden when a matching canonical row exists and its state is
- * 'binding', 'approved', or 'canceled'. Pre-cutover tickets (no canonical row) remain visible.
+ * Only an open row is visible: 'binding', 'approved', and 'canceled' are hidden, and so is a
+ * ticket with no row at all — a row is committed before its ticket is ever published.
  */
 export declare function isReviewTicketVisible(bridgeNodeId: string): boolean;
 /**

package/dist/core/review/ticket-filter.js

@@ -1,21 +1,16 @@
 /**
  * Terminal-review ticket visibility filter.
- * Hides canonical review tickets by state; passes pre-cutover tickets unchanged.
+ * Hides review tickets by canonical state.
  * This module never imports canvas DB directly; daemon call sites apply the filter.
  */
 import { getReviewByBridge } from './store.js';
 /**
  * Determines if a review ticket should be visible based on its canonical review state.
- * A review ticket is hidden when a matching canonical row exists and its state is
- * 'binding', 'approved', or 'canceled'. Pre-cutover tickets (no canonical row) remain visible.
+ * Only an open row is visible: 'binding', 'approved', and 'canceled' are hidden, and so is a
+ * ticket with no row at all — a row is committed before its ticket is ever published.
  */
 export function isReviewTicketVisible(bridgeNodeId) {
-    const review = getReviewByBridge(bridgeNodeId);
-    // Pre-cutover ticket with no record: visible
-    if (review === null)
-        return true;
-    // Canonical review exists: hide terminal states, show open
-    return review.state === 'open';
+    return getReviewByBridge(bridgeNodeId)?.state === 'open';
 }
 /**
  * Filters a ticket summary array to remove hidden terminal-review tickets.

package/dist/core/runtime/__tests__/engine-route.test.js

@@ -9,7 +9,7 @@
 // session). An idle follow_up must run as a prompt.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { resolveEngineRoute } from '../broker/frame-dispatch.js';
+import { resolveEngineRoute } from '../broker/engine-routing.js';
 const IMAGES = [{ type: 'image', data: 'aGk=', mimeType: 'image/png' }];
 test('m-C: follow_up on an IDLE session escalates to prompt (no streamingBehavior)', () => {
     const route = resolveEngineRoute({ type: 'follow_up' }, false);

package/dist/core/runtime/__tests__/spawn-env.test.js

@@ -102,12 +102,10 @@ test('B: configured model-provider keys cross by exact name', () => {
     assert.equal(env.ANTHROPIC_API_KEY, 'fake-anthropic');
     assert.equal(env.OPENAI_API_KEY, 'fake-openai');
 });
-// ---------------------------------------------------------------------------
 // A2 — proxy userinfo guard (Major 1 fix): must reject username-only,
 // password-only, and scheme-less userinfo, for BOTH uppercase and lowercase
 // var names; must keep a plain proxy URL, for both cases; NO_PROXY always
 // keeps.
-// ---------------------------------------------------------------------------
 test('A2: a credentialed proxy URL is dropped, a plain one crosses (uppercase)', () => {
     const env = base(LEAK_CLASS_HOST_ENV);
     assert.equal(env.HTTP_PROXY, undefined, 'userinfo-bearing proxy must not cross');
@@ -142,10 +140,8 @@ test('A2: a non-http(s) scheme or hostless value is dropped, never admitted', ()
     const env = base({ HTTP_PROXY: 'not a url at all' });
     assert.equal(env.HTTP_PROXY, undefined);
 });
-// ---------------------------------------------------------------------------
 // buildBrokerEnv: overlay + drop the leak class through the real process.env
 // path.
-// ---------------------------------------------------------------------------
 test('buildBrokerEnv overlays inv.env + FRONT_DOOR_ENV on top of the sanitized base, and drops the leak class', () => {
     const inv = {
         argv: [],
@@ -170,9 +166,7 @@ test('buildBrokerEnv overlays inv.env + FRONT_DOOR_ENV on top of the sanitized b
         delete process.env.GIT_ASKPASS;
     }
 });
-// ---------------------------------------------------------------------------
 // C — explicit spawnEnv.allow escape hatch: literal names + globs.
-// ---------------------------------------------------------------------------
 test('C: an explicit spawnEnv.allow literal name admits a var that would otherwise be dropped', () => {
     mkdirSync(join(isolatedHome, '.crouter'), { recursive: true });
     writeFileSync(join(isolatedHome, '.crouter', 'config.json'), JSON.stringify({ spawnEnv: { allow: ['GOOGLE_GENERATIVE_AI_API_KEY'] } }));
@@ -198,10 +192,8 @@ test('C (glob, Minor fix): a bare "*" (inherit-all) is rejected loud at config r
     resetScopeCache();
     assert.throws(() => readMergedLaunchConfig(isolatedCwd, null), /matches every env var name/, 'a bare "*" must fail loud at config read, per cto-rejects-fallback-hedges — never silently literal, never silently dropped');
 });
-// ---------------------------------------------------------------------------
 // Major 2 fix — spawnEnv.allow resolves from the TARGET's own cwd/profile,
 // never the calling/launcher process's ambient scope.
-// ---------------------------------------------------------------------------
 test('target-scope: spawnEnv.allow is read from the TARGET cwd, not process.cwd() (the ambient/launcher cwd)', () => {
     const launcherCwd = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-spawn-env-launcher-')));
     const targetCwd = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-spawn-env-target-')));

package/dist/core/runtime/bearings-render.d.ts

@@ -0,0 +1,56 @@
+import { type NamedNode } from '../canvas/labels.js';
+export declare function escapeAttribute(value: string): string;
+/** The `<project_context>` block — the `<environment>` snapshot only: a
+ *  host/runtime line (platform, hostname, node version, tmux-or-not — the
+ *  headless engine's own process env, which its bash tools inherit), the cwd
+ *  dir listing, and git status/worktrees. Project guidance lives in the
+ *  document substrate, so this wrapper stays environment-only. It always emits
+ *  because the environment snapshot is always present. */
+export declare function buildProjectContextBlock(cwd: string): string;
+/** The context-directory note — names the path INLINE (no XML attribute, so it
+ *  never scopes a sibling block) and frames the dir as durable, shared scratch.
+ *  Present for every node, rendered as the `## Your context directory`
+ *  subsection of <crtr-bearings>. */
+export declare function contextDirNote(nodeId: string): string;
+/** The profile-purview note — rendered ONLY when the profile resolves to a
+ *  manifest that names at least one project dir. Phrased as PURVIEW, not a cwd
+ *  replacement: the node's cwd is still its one working dir (bash/edits run
+ *  there), the profile just widens what it may ALSO read/act on. Omitted
+ *  entirely for a profile with no project purview (including the stable root
+ *  profile) or a deleted/unreadable manifest — never throws. This absolute-path
+ *  disclosure is intentional (spec-approved): the agent must know its full
+ *  purview, not a redacted count. */
+export declare function profileNote(cwd: string, profileId: string | null | undefined): string;
+/** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
+ *  so its context dir is also where a future cycle of itself resumes the work.
+ *  Used inside the bearings block AND in the promotion guidance dump, so a
+ *  promoted node gets the same note a born-orchestrator gets. */
+export declare function orchestratorContextNote(nodeId: string): string;
+export interface RelativeLabelNode extends NamedNode {
+    node_id: string;
+    kind: string;
+    status: string;
+    name: string;
+    description?: string;
+    icon?: string;
+}
+/** One relative's line in the map: `<id> — <kind> · <status>`, plus the node's
+ *  task description when it carries one (orientation: what that relative is for). */
+export declare function relativeLabel(node: RelativeLabelNode): string;
+/** The graph mini-map: the ancestry trunk (root first), then this node marked
+ *  `● you`, then its immediate children. Returns '' for a lone root with no
+ *  children (nothing to map). */
+export declare function renderGraphMap(nodeId: string, kind: string, mode: string, trunk: readonly RelativeLabelNode[], children: readonly RelativeLabelNode[]): string;
+/** The identity assertion injected at session start. A fork names its source
+ *  while treating the copied first-person narrative as reference. The caller
+ *  resolves `sourceLabel`: the bare `forkFrom` id when the source lookup
+ *  fails/is unsafe, else `${forkFrom} ("${fullName(src)}")`. */
+export declare function buildIdentityAssertion(nodeId: string, kind: string, mode: string, forkFrom: string | null | undefined, sourceLabel: string): string;
+export interface ManagedWorktreeLike {
+    state: string;
+    path: string;
+    branch: string;
+    base_ref: string;
+    base_sha: string;
+}
+export declare function worktreeNote(worktree: ManagedWorktreeLike | null | undefined): string;