@north-light/crouter 0.3.154

package/dist/core/runtime/nodes.js

@@ -0,0 +1,330 @@
+// Runtime node operations — the behavior layer above the canvas store.
+//
+// canvas/ is the pure data-access layer (nodes + edges). This is where the
+// design's *rules* live: how a node comes into being, the env contract its pi
+// process inherits, and the spawn-time wiring of the subscription spine.
+//
+// Two ways a node is born:
+//   • root  — a user-opened entry point (bare `crtr`).
+//             No parent; resident by default (it's a conversation you live in).
+//   • child — spawned by another node. Terminal until it must persist. On
+//             spawn the PARENT auto-subscribes (active) to the child, so it
+//             learns when the work finishes — this seeds the subscription
+//             graph to mirror the spawn structure. A `spawned_by` audit edge
+//             is also recorded.
+import { randomBytes } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { createNode, getNode, getRow, subscribe, recordSpawn, contextDir, } from '../canvas/index.js';
+import { memoryDir } from './memory.js';
+import { resolveInstallId } from '../canvas/install-id.js';
+import { canvasDbPath } from '../canvas/paths.js';
+import { usage } from '../errors.js';
+// crtrd sets this once at boot (setInstallId) and it wins unconditionally —
+// a daemon process only ever serves one canvas home for its whole lifetime,
+// so no keying is needed there. Every OTHER in-process caller (tests,
+// in-process tooling — spawnNode is called directly by many existing test
+// files, several of which switch CRTR_HOME + closeDb() between cases) has no
+// such guarantee, so its lazy cache is keyed by canvas-db path — the same
+// identity openDb() itself keys its handle cache by (db.ts's `handles` map) —
+// so a CRTR_HOME switch can never leak one canvas's install id onto another's
+// nodes.
+let daemonInstallId;
+const lazyInstallIdByHome = new Map();
+/** Explicitly set the resolved install id. crtrd calls this once at boot,
+ *  immediately after `resolveInstallId()` — see crtrd.ts — so a provisioning
+ *  mismatch fails the daemon loudly at STARTUP rather than lazily on first
+ *  spawn. Exported for the daemon only; every other caller gets it lazily via
+ *  `installId()` below. */
+export function setInstallId(id) {
+    daemonInstallId = id;
+}
+/** Lazily resolve and cache the canvas-install id, keyed by the currently
+ *  active canvas home so a process that switches `CRTR_HOME` (tests, in-
+ *  process tooling) never keeps stamping a stale home's install id onto a
+ *  different home's nodes. crtrd's boot-set value (`setInstallId`) always
+ *  wins when present — a daemon never switches homes mid-process. */
+function installId() {
+    if (daemonInstallId !== undefined)
+        return daemonInstallId;
+    const home = canvasDbPath();
+    const cached = lazyInstallIdByHome.get(home);
+    if (cached !== undefined)
+        return cached;
+    const resolved = resolveInstallId();
+    lazyInstallIdByHome.set(home, resolved);
+    return resolved;
+}
+/** Raw time-sortable + random id shape — used for non-node opaque ids such as
+ *  focus ids (`f-…`) that are NOT canvas node identities and keep their
+ *  historical 2-segment shape (unstamped by the canvas-install id). */
+export function newJobId() {
+    return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+}
+/** Generate a NODE id: `<install>-<time36>-<rand4hex>` (3 segments) — the
+ *  canvas-install id stamped onto the historical job-id shape, so every
+ *  minted node id is a globally-unique NAME that also names the canvas that
+ *  minted it (see the unified-chat/addressing design's "ID scheme"). crtrd is
+ *  the sole node minter. */
+export function newNodeId() {
+    return `${installId()}-${newJobId()}`;
+}
+// The node id itself is an OPAQUE, caller-meaningless NAME (see the unified
+// chat/addressing design's "ID scheme") — never parsed for structure. This is
+// therefore a single non-structural, charset-safety predicate: lowercase
+// [a-z0-9-] only (so 'remote42' — zero hyphens — is exactly as valid as any
+// stamped 3-segment id) and a length cap. 128 is chosen to exactly match
+// paths.ts's `isSafeNodeId` filesystem-path-segment boundary (the sole other
+// place a node id's raw byte length is safety-checked) rather than picking an
+// independent number that could drift out of sync with it. Every id that
+// passes here is automatically also a safe fs path segment, a safe
+// `crtr/<id>` git branch suffix, and never contains '.', '..', '/', '\\', or a
+// null byte (the charset alone rules all of those out) — no sink needs a
+// leading/trailing/double-hyphen restriction on top, so none is imposed.
+const NODE_ID_MAX_LEN = 128;
+const NODE_ID_FORMAT = /^[a-z0-9-]+$/;
+/** Thrown when a caller-specified `--node-id` (or its API twin `node_id`)
+ *  already names a live node. Distinguishable from every other spawn failure
+ *  so a caller can treat it as "attach instead of create" per the unified
+ *  chat/addressing design's ensure semantics — never overwrite, never
+ *  double-spawn. Mapped to HTTP 409 in `src/daemon/api/map.ts`. */
+export class NodeIdConflictError extends Error {
+    nodeId;
+    constructor(nodeId) {
+        super(`node already exists: ${nodeId}`);
+        this.nodeId = nodeId;
+        this.name = 'NodeIdConflictError';
+    }
+}
+/** Format-validate a CALLER-SUPPLIED node id operand. Throws a usage error on
+ *  a bad shape; never touches the canvas. Shared by the early best-effort
+ *  preflight (`preflightNodeId`, run before any worktree is allocated) and the
+ *  authoritative check immediately before node creation (`validatedExplicitNodeId`
+ *  below) so the two can never disagree about what shape is valid. */
+function validateNodeIdFormat(nodeId) {
+    if (nodeId.length === 0 || nodeId.length > NODE_ID_MAX_LEN) {
+        throw usage(`invalid --node-id '${nodeId}': must be 1-${NODE_ID_MAX_LEN} characters`, {
+            next: `Pass an id-safe string (lowercase letters, digits, hyphens) of at most ${NODE_ID_MAX_LEN} characters.`,
+        });
+    }
+    if (!NODE_ID_FORMAT.test(nodeId)) {
+        throw usage(`invalid --node-id '${nodeId}': must contain only lowercase letters, digits, and hyphens (e.g. 'remote42', 'my-node-1')`, { next: 'Use only lowercase letters, digits, and hyphens.' });
+    }
+}
+/** Best-effort preflight for a caller-supplied `--node-id`, run BEFORE any
+ *  worktree is allocated for it (`spawnChild` in spawn.ts) — so a malformed or
+ *  already-taken id fails before there is anything to leak/clean up. Format
+ *  validation here is authoritative (an id that fails it can never become
+ *  valid); the duplicate check is advisory only — a concurrent create can
+ *  still win the race between this check and the synchronous check-then-
+ *  create below, which remains the SOLE authoritative decider. */
+export function preflightNodeId(nodeId) {
+    validateNodeIdFormat(nodeId);
+    if (getNode(nodeId) !== null)
+        throw new NodeIdConflictError(nodeId);
+}
+/** Validate + duplicate-check a CALLER-SUPPLIED node id operand before it
+ *  reaches the canvas. Internally-minted ids (newNodeId()-derived) already
+ *  satisfy the format unconditionally and are never a duplicate (they embed a
+ *  fresh timestamp+random suffix), so this is only ever exercised by an
+ *  explicit `opts.nodeId` from a real caller (`--node-id` / API `node_id`).
+ *
+ *  RACE SAFETY: this function and the `createNode()` call that follows it in
+ *  `spawnNode` run with no `await` between them, and `spawnNode` itself is a
+ *  synchronous function — so on the single-threaded daemon process, the
+ *  existence-check-then-create is atomic relative to any other concurrent
+ *  request. Two concurrent creates at the same id resolve to exactly one
+ *  winner (whichever's synchronous `spawnNode()` call runs first) and one
+ *  `NodeIdConflictError` for the loser. */
+function validatedExplicitNodeId(nodeId) {
+    validateNodeIdFormat(nodeId);
+    if (getNode(nodeId) !== null)
+        throw new NodeIdConflictError(nodeId);
+    return nodeId;
+}
+/** The root of a node's spine: walk the `parent` column up to `parent == null`.
+ *  Cycle-guarded (parents must not cycle, but never loop forever). Lives in the
+ *  node layer (not placement) so the env-builder and placement both reach it
+ *  without an import cycle — `CRTR_SUBTREE` is emitted as `rootOfSpine(nodeId)`
+ *  at every launch site. */
+export function rootOfSpine(nodeId) {
+    let cur = nodeId;
+    const seen = new Set();
+    for (;;) {
+        if (seen.has(cur))
+            return cur;
+        seen.add(cur);
+        const row = getRow(cur);
+        if (row === null || row.parent == null)
+            return cur;
+        cur = row.parent;
+    }
+}
+/** Read the current node's identity from the environment. A spawned pi process
+ *  runs with CRTR_NODE_ID set; its own `crtr` invocations spawn children under
+ *  it by reading CRTR_NODE_ID as the parent. */
+export function currentNodeContext() {
+    const env = process.env;
+    return {
+        nodeId: env['CRTR_NODE_ID'] ?? null,
+        kind: env['CRTR_KIND'] ?? null,
+        mode: env['CRTR_MODE'] ?? null,
+    };
+}
+/** The env injected into a node's pi process. Self-gating extensions read
+ *  CRTR_KIND/CRTR_MODE to flip behavior on polymorph without a respawn; the
+ *  feed/inbox machinery reads CRTR_NODE_ID. */
+export function nodeEnv(meta) {
+    const env = {
+        CRTR_NODE_ID: meta.node_id,
+        CRTR_KIND: meta.kind,
+        CRTR_MODE: meta.mode,
+        CRTR_LIFECYCLE: meta.lifecycle,
+        CRTR_NODE_CWD: meta.cwd,
+        // The node's own context dir (canvas home), as an ABSOLUTE path. The engine
+        // runs with cwd = CRTR_NODE_CWD (the project), so a relative `context/`
+        // resolves into the REPO, not here — agents must address artifacts via this.
+        CRTR_CONTEXT_DIR: contextDir(meta.node_id),
+        CRTR_CYCLES: (meta.cycles ?? 0).toString(),
+        // The runtime→resolver seam: memory-resolver.ts/scope.ts/config.ts read
+        // this process-wide env var to pull in the node's profile memory store and
+        // multi-project pointer set. '' (never omitted) only for historical
+        // null-profile rows, matching every other CRTR_* scalar here.
+        CRTR_PROFILE_ID: meta.profile_id ?? '',
+    };
+    if (meta.parent)
+        env['CRTR_PARENT_NODE_ID'] = meta.parent;
+    // Propagate an explicit canvas home so children share the same canvas.
+    const home = process.env['CRTR_HOME'];
+    if (home !== undefined && home !== '')
+        env['CRTR_HOME'] = home;
+    // Propagate the subtree-root node id. The broker uses it to group a subtree;
+    // each launch site also emits the authoritative rootOfSpine(nodeId) over this
+    // passthrough.
+    const subtree = process.env['CRTR_SUBTREE'];
+    if (subtree !== undefined && subtree !== '')
+        env['CRTR_SUBTREE'] = subtree;
+    // Merge any launch-spec env last (it may override / extend).
+    return { ...env, ...(meta.launch?.env ?? {}) };
+}
+// ---------------------------------------------------------------------------
+// Birth
+// ---------------------------------------------------------------------------
+function isHumanWorkTarget(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const target = value;
+    return ((target.work_kind === 'follow_up' || target.work_kind === 'visual') &&
+        typeof target.dir === 'string' && target.dir !== '' &&
+        typeof target.request_id === 'string' && target.request_id !== '' &&
+        typeof target.root === 'string' && target.root !== '');
+}
+/** Refuse malformed private claims before createNode leaves a durable half-node.
+ *  This is intentionally private to the lifecycle-owned human-work birth API;
+ *  ordinary spawn callers do not acquire a second generic validation surface. */
+function validatePrivateForkBirth(opts) {
+    const hasTarget = opts.humanWorkTarget != null;
+    const hasPhase = opts.privateForkPhase != null;
+    const hasRecipe = opts.privateForkRecipe != null;
+    if (!hasTarget && !hasPhase && !hasRecipe) {
+        if (opts.initialStatus !== undefined)
+            throw new Error('only private human-work births may start inert');
+        return;
+    }
+    if (!isHumanWorkTarget(opts.humanWorkTarget)) {
+        throw new Error('private human-work birth requires a recognized humanWorkTarget');
+    }
+    if (opts.privateForkPhase !== 'fork_pending') {
+        throw new Error('private human-work birth requires privateForkPhase=fork_pending');
+    }
+    if (typeof opts.privateForkRecipe?.kickoff !== 'string' || opts.privateForkRecipe.kickoff.trim() === '') {
+        throw new Error('private human-work birth requires a non-empty kickoff recipe');
+    }
+    if (typeof opts.forkFrom !== 'string' || !isAbsolute(opts.forkFrom)) {
+        throw new Error('private human-work birth requires an absolute forkFrom provenance file');
+    }
+    if (opts.parent !== null && opts.parent !== undefined) {
+        throw new Error('private human-work birth must be parent-null');
+    }
+    if ((opts.lifecycle ?? 'terminal') !== 'terminal') {
+        throw new Error('private human-work birth must be terminal');
+    }
+    if (opts.launch?.modelExact !== true || typeof opts.launch.model !== 'string' || opts.launch.model.trim() === '') {
+        throw new Error('private human-work birth requires an exact persisted model');
+    }
+}
+/** Create a node on the canvas and wire its spawn-time edges.
+ *
+ *  For a child (parent given): the parent auto-subscribes ACTIVE to the child
+ *  (so it's woken when the child finishes), and a spawned_by audit edge is
+ *  recorded. For a root (no parent): no edges, resident by default. */
+export function spawnNode(opts) {
+    validatePrivateForkBirth(opts);
+    const nodeId = opts.nodeId !== undefined ? validatedExplicitNodeId(opts.nodeId) : newNodeId();
+    const parent = opts.parent ?? null;
+    const isRoot = parent === null;
+    // Provenance is independent of the spine: a root has no parent but still
+    // records who spawned it. A child's spawner is its parent unless overridden.
+    const spawnedBy = opts.spawnedBy ?? parent;
+    const mode = opts.mode ?? 'base';
+    // A user-opened root is resident (a conversation you live in); a spawned node
+    // is terminal until it must persist (promotion handles that later).
+    const lifecycle = opts.lifecycle ?? (isRoot ? 'resident' : 'terminal');
+    const meta = {
+        node_id: nodeId,
+        name: opts.name ?? opts.kind,
+        description: opts.description,
+        cycles: 0,
+        created: new Date().toISOString(),
+        cwd: opts.cwd,
+        // Broker is the only host: every node runs on the headless broker; a tmux
+        // pane is only an attach viewer.
+        host_kind: 'broker',
+        profile_id: opts.profile_id ?? null,
+        kind: opts.kind,
+        mode,
+        lifecycle,
+        // Born already acked to its initial persona: a fresh node has been "given
+        // guidance" for the state it starts in (its bearings carry it), so the
+        // persona injector sees no drift on its first turn boundary.
+        persona_ack: { mode, lifecycle },
+        status: opts.initialStatus ?? 'active',
+        parent,
+        spawned_by: spawnedBy,
+        fork_from: opts.forkFrom,
+        human_work_target: opts.humanWorkTarget,
+        private_fork_phase: opts.privateForkPhase,
+        private_fork_recipe: opts.privateForkRecipe,
+        model_override: opts.modelOverride ?? null,
+        passive_default: opts.passiveDefault ?? false,
+        ...(opts.managedWorktree !== undefined ? { managed_worktree: opts.managedWorktree } : {}),
+        intent: null,
+        pi_session_id: null,
+        pi_session_file: null,
+        launch: opts.launch,
+    };
+    // Validate BEFORE minting: a bad parent must leave no half-born orphan row or
+    // dirs behind, so the parent's existence is checked before createNode
+    // scaffolds anything on disk or in the db.
+    if (parent !== null && getNode(parent) === null) {
+        throw new Error(`cannot spawn under unknown parent node: ${parent}`);
+    }
+    createNode(meta);
+    // Create the node-local memory directory so substrate docs can be written
+    // directly into it without a separate mkdir. Skip for ephemeral human-bridge
+    // rows (kind 'human') — they are not agent nodes.
+    if (meta.kind !== 'human') {
+        mkdirSync(memoryDir(meta.node_id), { recursive: true });
+    }
+    if (parent !== null) {
+        // The load-bearing seed: parent subscribes (active) to child so it learns
+        // when the work finishes. This mirrors spawn structure into the spine.
+        // A root (parent=null) gets NO subscription — nobody is woken by it.
+        subscribe(parent, meta.node_id, true);
+    }
+    // Audit-only provenance edge — recorded for a root too (from its spawner).
+    if (spawnedBy !== null && spawnedBy !== undefined && getNode(spawnedBy) !== null) {
+        recordSpawn(meta.node_id, spawnedBy);
+    }
+    return meta;
+}

package/dist/core/runtime/package-health.d.ts

@@ -0,0 +1,49 @@
+export interface MissingPackage {
+    /** The raw `packages[]` entry as stored in settings.json. */
+    source: string;
+    /** Absolute path it resolved to (which does not exist). */
+    resolved: string;
+}
+export interface GlobalHumanloopHealth {
+    bundledVersion: string | null;
+    globalVersion: string | null;
+    current: boolean;
+}
+/** Read the installed library's version rather than coupling this check to the
+ * dependency range in crouter's package.json. The bundled copy is the floor
+ * required by crouter's generated `hl inbox toggle` binding. */
+export declare function bundledHumanloopVersion(): string | null;
+/** Read the PATH-visible `hl` package directly. Spawning `npm ls -g` here
+ * makes every front-door boot pay for npm's global dependency-tree scan; a
+ * linked development install can make that scan take many seconds. The real
+ * executable points into the package for both ordinary and npm-linked installs,
+ * so walking upward to its package.json is authoritative for the CLI crtr will
+ * actually invoke. */
+export declare function globalHumanloopVersion(): string | null;
+export declare function globalHumanloopHealth(): GlobalHumanloopHealth;
+/** A non-fatal action-oriented diagnostic for a missing, unreadable, or stale
+ * global `hl` executable. */
+export declare function globalHumanloopWarning(): string | null;
+export declare function globalHumanloopInstallCommand(): string;
+/**
+ * The pi agent config dir (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`) — a local
+ * reimplementation of pi's `getAgentDir()`. Reimplemented (not imported) ON
+ * PURPOSE: `getAgentDir` lives in `@earendil-works/pi-coding-agent`, and
+ * importing that package pulls in the ENTIRE ~360ms pi engine module graph. The
+ * front door calls this on every bare-`crtr` boot BEFORE spawning the broker, so
+ * a static/dynamic pi import here adds ~316ms of serialized dead-time in the
+ * foreground before the broker (which loads pi itself) even starts. This mirrors
+ * pi's contract exactly: `$PI_CODING_AGENT_DIR` (tilde-expanded) else
+ * `~/.pi/agent`. Same precedent as `bearings.ts` (keep the pi engine out of the
+ * hot/foreground path). If pi ever rebrands its configDir/env, update here.
+ */
+export declare function piAgentDir(homeDir?: string): string;
+/**
+ * Return every local-path package in `<agentDir>/settings.json` whose resolved
+ * path is missing. Empty when settings is absent/unreadable or all paths exist.
+ * Mirrors pi's own resolution: `resolve(agentDir, expandTilde(source))`.
+ */
+export declare function findMissingPackagePaths(agentDir: string, homeDir?: string): MissingPackage[];
+/** A human-readable, actionable warning for a set of missing packages, or
+ *  `null` when nothing is missing. Names `crtr sys setup` as the fix. */
+export declare function missingPackageWarning(agentDir: string, homeDir?: string): string | null;

package/dist/core/runtime/package-health.js

@@ -0,0 +1,217 @@
+// package-health: detect pi packages configured in `<agentDir>/settings.json`
+// whose LOCAL-PATH source no longer exists on disk.
+//
+// Why this exists: pi installs a local-path package (e.g. crouter's bundled
+// `pi-crtr-extensions`, which surfaces `~/.claude` commands/skills/plugins as
+// slash commands) by storing its path in settings.json RELATIVE to the settings
+// dir. Moving the crouter repo silently invalidates that relative path — and pi
+// DISCARDS a missing package with no error, so the extension just never loads
+// and its whole feature (here: every Claude command/marketplace command) simply
+// vanishes with no diagnostic. This turns that silent failure into a loud,
+// actionable warning. The fix it points at is `crtr sys setup`, which re-resolves
+// package paths to the repo's current location.
+import { accessSync, constants, existsSync, readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join, resolve } from 'node:path';
+const GLOBAL_HUMANLOOP_INSTALL_COMMAND = 'npm i -g @crouton-kit/humanloop@latest';
+/** Read the installed library's version rather than coupling this check to the
+ * dependency range in crouter's package.json. The bundled copy is the floor
+ * required by crouter's generated `hl inbox toggle` binding. */
+export function bundledHumanloopVersion() {
+    try {
+        // package.json is deliberately not an exported subpath. Resolve the public
+        // ESM entry, then walk from dist/index.js to the package root.
+        const entryPath = fileURLToPath(import.meta.resolve('@crouton-kit/humanloop'));
+        const packageJsonPath = join(dirname(entryPath), '..', 'package.json');
+        const value = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+        return typeof value.version === 'string'
+            ? value.version
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Compare ordinary npm semvers without loading a semver dependency on the
+ * foreground/daemon startup path. Unparseable versions deliberately fail the
+ * health check: setup can repair them and boot only warns. */
+function compareVersions(left, right) {
+    const parse = (version) => {
+        const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+        if (match === null)
+            return null;
+        return { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4]?.split('.') ?? [] };
+    };
+    const a = parse(left);
+    const b = parse(right);
+    if (a === null || b === null)
+        return null;
+    for (let index = 0; index < a.core.length; index++) {
+        const difference = a.core[index] - b.core[index];
+        if (difference !== 0)
+            return difference;
+    }
+    if (a.prerelease.length === 0 || b.prerelease.length === 0) {
+        return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
+    }
+    for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index++) {
+        const aPart = a.prerelease[index];
+        const bPart = b.prerelease[index];
+        if (aPart === undefined || bPart === undefined)
+            return aPart === bPart ? 0 : aPart === undefined ? -1 : 1;
+        if (aPart === bPart)
+            continue;
+        const aNumber = /^\d+$/.test(aPart);
+        const bNumber = /^\d+$/.test(bPart);
+        if (aNumber && bNumber)
+            return Number(aPart) - Number(bPart);
+        if (aNumber !== bNumber)
+            return aNumber ? -1 : 1;
+        return aPart < bPart ? -1 : 1;
+    }
+    return 0;
+}
+/** Read the PATH-visible `hl` package directly. Spawning `npm ls -g` here
+ * makes every front-door boot pay for npm's global dependency-tree scan; a
+ * linked development install can make that scan take many seconds. The real
+ * executable points into the package for both ordinary and npm-linked installs,
+ * so walking upward to its package.json is authoritative for the CLI crtr will
+ * actually invoke. */
+export function globalHumanloopVersion() {
+    const executable = (process.env['PATH'] ?? '')
+        .split(delimiter)
+        .filter(Boolean)
+        .map((entry) => join(entry, 'hl'))
+        .find((candidate) => {
+        try {
+            accessSync(candidate, constants.X_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (executable === undefined)
+        return null;
+    try {
+        let cursor = dirname(realpathSync(executable));
+        for (;;) {
+            const packageJsonPath = join(cursor, 'package.json');
+            if (existsSync(packageJsonPath)) {
+                const value = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+                const manifest = value;
+                if (manifest.name === '@crouton-kit/humanloop')
+                    return typeof manifest.version === 'string' ? manifest.version : null;
+            }
+            const parent = dirname(cursor);
+            if (parent === cursor)
+                return null;
+            cursor = parent;
+        }
+    }
+    catch {
+        return null;
+    }
+}
+export function globalHumanloopHealth() {
+    const bundledVersion = bundledHumanloopVersion();
+    const globalVersion = globalHumanloopVersion();
+    const comparison = bundledVersion !== null && globalVersion !== null
+        ? compareVersions(globalVersion, bundledVersion)
+        : null;
+    return { bundledVersion, globalVersion, current: comparison !== null && comparison >= 0 };
+}
+/** A non-fatal action-oriented diagnostic for a missing, unreadable, or stale
+ * global `hl` executable. */
+export function globalHumanloopWarning() {
+    const { bundledVersion, globalVersion, current } = globalHumanloopHealth();
+    if (current)
+        return null;
+    const floor = bundledVersion ?? 'the bundled version';
+    const found = globalVersion === null ? 'missing or unprobeable' : globalVersion;
+    return `crtr: global \`hl\` CLI is ${found}; crouter requires at least bundled humanloop ${floor} for its inbox toggle.\n` +
+        `  Fix: run \`${GLOBAL_HUMANLOOP_INSTALL_COMMAND}\`.`;
+}
+export function globalHumanloopInstallCommand() {
+    return GLOBAL_HUMANLOOP_INSTALL_COMMAND;
+}
+/** Expand a leading `~` against `homeDir` (pi's own convention). */
+function expandTilde(pathValue, homeDir) {
+    if (pathValue === '~')
+        return homeDir;
+    if (pathValue.startsWith('~/'))
+        return join(homeDir, pathValue.slice(2));
+    return pathValue;
+}
+/**
+ * The pi agent config dir (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`) — a local
+ * reimplementation of pi's `getAgentDir()`. Reimplemented (not imported) ON
+ * PURPOSE: `getAgentDir` lives in `@earendil-works/pi-coding-agent`, and
+ * importing that package pulls in the ENTIRE ~360ms pi engine module graph. The
+ * front door calls this on every bare-`crtr` boot BEFORE spawning the broker, so
+ * a static/dynamic pi import here adds ~316ms of serialized dead-time in the
+ * foreground before the broker (which loads pi itself) even starts. This mirrors
+ * pi's contract exactly: `$PI_CODING_AGENT_DIR` (tilde-expanded) else
+ * `~/.pi/agent`. Same precedent as `bearings.ts` (keep the pi engine out of the
+ * hot/foreground path). If pi ever rebrands its configDir/env, update here.
+ */
+export function piAgentDir(homeDir = homedir()) {
+    const envDir = process.env['PI_CODING_AGENT_DIR'];
+    if (envDir !== undefined && envDir !== '')
+        return expandTilde(envDir, homeDir);
+    return join(homeDir, '.pi', 'agent');
+}
+/** A `packages[]` entry is a LOCAL PATH (not an npm ref) — the only kind that
+ *  can go stale on a repo move. `npm:...` and bare registry names resolve
+ *  through node/npm, not the filesystem, so they are out of scope here. */
+function isLocalPathSource(source) {
+    if (source.startsWith('npm:'))
+        return false;
+    return source.startsWith('.') || source.startsWith('/') || source.startsWith('~');
+}
+/**
+ * Return every local-path package in `<agentDir>/settings.json` whose resolved
+ * path is missing. Empty when settings is absent/unreadable or all paths exist.
+ * Mirrors pi's own resolution: `resolve(agentDir, expandTilde(source))`.
+ */
+export function findMissingPackagePaths(agentDir, homeDir = homedir()) {
+    let raw;
+    try {
+        raw = readFileSync(join(agentDir, 'settings.json'), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    let packages;
+    try {
+        packages = JSON.parse(raw).packages;
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(packages))
+        return [];
+    const missing = [];
+    for (const entry of packages) {
+        if (typeof entry !== 'string' || !isLocalPathSource(entry))
+            continue;
+        const resolved = resolve(agentDir, expandTilde(entry, homeDir));
+        if (!existsSync(resolved))
+            missing.push({ source: entry, resolved });
+    }
+    return missing;
+}
+/** A human-readable, actionable warning for a set of missing packages, or
+ *  `null` when nothing is missing. Names `crtr sys setup` as the fix. */
+export function missingPackageWarning(agentDir, homeDir = homedir()) {
+    const missing = findMissingPackagePaths(agentDir, homeDir);
+    if (missing.length === 0)
+        return null;
+    const lines = missing.map((m) => `  • ${m.source}\n      → ${m.resolved} (missing)`);
+    return (`crtr: ${missing.length} configured pi package path${missing.length === 1 ? '' : 's'} ` +
+        `no longer exist${missing.length === 1 ? 's' : ''} — pi silently skips these, so their ` +
+        `slash commands (e.g. ~/.claude commands & marketplace plugins) will not load.\n` +
+        lines.join('\n') +
+        `\n  Fix: re-run \`crtr sys setup\` (re-resolves package paths to this repo's current location).`);
+}

package/dist/core/runtime/persona.d.ts

@@ -0,0 +1,25 @@
+import { type Mode, type Lifecycle } from '../canvas/index.js';
+/** The two-axis persona state the injector keys on. */
+export interface Persona {
+    mode: Mode;
+    lifecycle: Lifecycle;
+}
+export interface PersonaDriftResult {
+    from: Persona;
+    to: Persona;
+    /** The built transition guidance to inject for `to`. */
+    guidance: string;
+}
+/** Build the injected transition prompt for a `from → to` persona change.
+ *  Concatenates the relevant section per changed axis (both when both changed).
+ *  Pure read of the node's roadmap/memory for the base→orchestrator case. */
+export declare function transitionGuidance(nodeId: string, from: Persona, to: Persona): string;
+/** Compare a node's live {mode,lifecycle} against its `persona_ack` (the last
+ *  state it was given guidance for). Returns the transition + built guidance
+ *  when they differ, else null. Does NOT mutate — the caller delivers the
+ *  guidance, then `commitPersonaAck`s the new state. An unset `persona_ack`
+ *  (legacy node) defaults to the current persona, so it reads as no drift and
+ *  never fabricates spurious guidance. */
+export declare function personaDrift(nodeId: string): PersonaDriftResult | null;
+/** Commit the persona state the node has now been given guidance for. */
+export declare function commitPersonaAck(nodeId: string, to: Persona): void;