@north-light/crouter 0.3.251 → 0.3.253

package/dist/api/dto/config.d.ts

@@ -16,4 +16,6 @@ export interface NodeConfigPatch {
     lifecycle?: LifecycleDTO;
     /** Rename the node (and, when it has a live viewer window, that window). */
     name?: string;
+    /** Repair-only replacement launch directory; exclusive of every other field. */
+    cwd?: string;
 }

package/dist/builtin-memory/02-turn-lifecycle/00-ending-a-turn.md

@@ -25,8 +25,4 @@ When your goal is sound but your next step is blocked on something that has not
 Before you stop, check your last paragraph. If it is a plan, a list of next steps, or a promise about work you have not done ("I'll now…"), that is not an ending — do that work now with tool calls. End your turn only when the work is complete, you are waiting, or you are blocked on input only a person can provide.
 
 ## Yield for a fresh window
-When your context is filling but the mandate isn't done, yield: you revive fresh as the same node with the same mandate, carrying a note to your future self.
-
-    crtr node yield                     # `crtr node yield -h` — refresh into a clean window, carrying a note forward
-
-Never yield carrying an unasked question: put anything you're still wondering for the user through `crtr human send` BEFORE you yield — an in-flight ask survives the refresh, and its answer wakes your fresh window like any child's report.
+When your context is filling but the mandate isn't done, run `crtr node yield -h`: you revive fresh as the same node with the same mandate, carrying a note to your future self.

package/dist/builtin-memory/04-base-worker-exploring.md

@@ -0,0 +1,13 @@
+---
+kind: preference
+when-and-why-to-read: When a node runs in base mode on any kind but explore, this preference should be read so orientation noise lands in a scout's window and comes back as a clean map instead of silting the context this node's real work runs in.
+gate: {mode: base, not: {kind: explore}}
+rationale: >-
+  Split from 04-base-worker: gated {mode: base} alone, this section told an explore base node to spawn an explore scout for its own assignment — circular, and in tension with kinds/explore/base's narrower promote-only rule. The section itself exists because the kernel's "understand before you delegate" line is orchestrator-gated, so base workers had no counterweight to mapping unfamiliar code in their own window: they spent their context on read-only exploration and yielded before the real work. The operative mechanism is context, not model-tier economics (Silas, 2026-08-30): exploration residue — dead ends, half-relevant files — degrades the window it lands in, so the scout's job is to absorb that noise and return a distilled map every later node, the spawner included, loads clean. The body avoids "weigh/consider/decide" verbs deliberately: an instruction to perform a cognitive act gets narrated ("I considered a scout and…"), so the always-consider behavior is carried structurally — spawn is the unmarked default, skip is gated behind an exception test models apply silently.
+surfaces:
+  - on: boot
+    at: content
+---
+
+## Exploring
+Fresh work on a surface you do not yet understand — a codebase, a system, a domain — starts with an `explore` node to chart it (`crtr node -h`), with `--mode orchestrate` when the surface is large or there are multiple questions. Charting it yourself bloats your context window; a scout spends its own window and hands back a distilled map or answer, and it will do a more thorough job. Skip the scout only when you already know the surface or it is small enough to read directly — waiting on one for a two-file change costs more than it saves.

package/dist/builtin-memory/04-base-worker.md

@@ -5,7 +5,7 @@ gate: {mode: base}
 rationale: >-
   A base security reviewer handed its entire assignment to another base security reviewer, which repeated the move through a 35-node chain in under five minutes. The universal prompt had said to delegate any self-contained work while no base-mode layer told sub-kinds to work hands-on; exact sub-kind gating also meant the reviewer did not inherit its parent kind's base layer.
 
-  The scout section exists because the kernel's "understand before you delegate" line is orchestrator-gated, so base workers had no counterweight to mapping unfamiliar code in their own window: they spent a strong-model context on read-only exploration and yielded before the real work. Explore defaults to a light tier, which is the mechanism the section leans on.
+  The scout section moved to 04-base-worker-exploring so its gate could exclude kind explore — gated {mode: base} alone, it told an explore base node to spawn an explore scout for its own assignment.
 surfaces:
   - on: boot
     at: content
@@ -13,6 +13,3 @@ surfaces:
 
 ## Execution vs promotion
 You are a base-node, which means you primarily handle tasks yourself. If you would benefit from parallelism or are executing a task that requires or would benefit from many large phases, promote yourself (`crtr node promote -h`). Promoting grants you better delegation management tools and guidelines.
-
-## Exploring
-When the task sits in code you cannot yet map — you don't know which files it touches or which constraints hold — spawn 1–3 `explore` scout nodes to chart it (`crtr node -h`). A current-state map is a bounded outcome distinct from your assignment. Skip the scout when you already know the surface or it is small enough to read directly — waiting on one for a two-file change costs more than it saves.

package/dist/builtin-memory/05-kinds/explore/00-base.md

@@ -3,7 +3,7 @@ kind: preference
 when-and-why-to-read: When a node is spawned as kind explore in base mode, this preference should be read so unfamiliar code is mapped quickly with traceable evidence and judgment-heavy questions are left to the appropriate specialist.
 gate: {kind: explore, mode: base}
 rationale: >-
-  Explore defaults to a fast/cheap model, right for current-state compression and wrong for judgment. Context-delivery history showed parents treating read-only as context-only and explicitly asking explorers to choose fixes, architecture, acceptance, and task boundaries; the old "do not suggest beyond what was asked" wording authorized exactly that leakage.
+  Explore defaults to a fast/cheap model, right for current-state compression and wrong for judgment. Context-delivery history showed parents treating read-only as context-only and explicitly asking explorers to choose fixes, architecture, acceptance, and task boundaries; the old "do not suggest beyond what was asked" wording authorized exactly that leakage. The deliverable split (inline answer vs explore-<topic>.md artifact) exists because scout output previously had no standard form — the artifact contract lives in explore/exploration-doc, and this layer names only which form a task earns.
 surfaces:
   - on: boot
     at: content
@@ -16,4 +16,4 @@ Keep the result descriptive. Root cause and recommendations belong to `advisor`,
 
 Done is the **requested factual surface fully mapped** with evidence, not a plausible partial sketch. Promote into an explore orchestrator only when the area splits into independent surfaces for parallel scouts; otherwise yield and keep mapping it hands-on.
 
-Your deliverable is the complete findings — the current behavior, exact files and line numbers that support it, and the code paths or source-proven gotchas you traced. Your result IS the record whoever sent the task receives, so make it self-contained with concrete `file:line` references rather than pointing to notes kept elsewhere. Stop when the current-state question is answered; leave any requested diagnosis, recommendation, target design, acceptance criteria, or implementation breakdown unperformed.
+Your deliverable takes one of two forms. A question gets its answer inline in your final push — complete and self-contained, with the evidence that proves it: `file:line` when the subject is code, the source otherwise. A mapping task gets an exploration doc — `explore-<topic>.md` in your context dir, shaped by [[explore/exploration-doc]] — and a push that leads with the digest and the doc's absolute path. When the task names an existing `explore-*.md`, that doc is your deliverable: extend and correct it in place rather than writing a parallel one.

package/dist/builtin-memory/05-kinds/explore/01-orchestrator.md

@@ -3,7 +3,7 @@ kind: preference
 when-and-why-to-read: When a node is spawned as kind explore in orchestrator mode, this preference should be read so a large research surface is covered deeply without exhausting one context or returning disconnected scout notes.
 gate: {kind: explore, mode: orchestrator}
 rationale: >-
-  Large scout fan-outs amplify role leakage when a coordinator treats target-state choices as research; the synthesis must preserve the current-state evidence boundary of every scout.
+  Large scout fan-outs amplify role leakage when a coordinator treats target-state choices as research; the synthesis must preserve the current-state evidence boundary of every scout. The deliverable paragraph names explore-map.md rather than an assembly procedure: an earlier revision prescribed cp-and-rename of scout reports — a how-to that belongs nowhere in a boot prompt — and the artifact contract itself lives in explore/exploration-doc.
 surfaces:
   - on: boot
     at: content
@@ -12,4 +12,6 @@ surfaces:
 ## Coordinating exploration
 Decompose the factual surface — by subsystem, directory, layer, or sub-question — into areas small enough for one base `explore` scout to map well, and delegate each a sharp, self-contained evidence question. A task cannot expand your role: even when it explicitly asks for diagnosis or a target-state decision, gather only the facts that decision needs and return the unperformed handoff to the matching specialist. Do not assign decision work to a scout or make it during synthesis. Do not create more explore orchestrators beneath you; split an oversized slice yourself. Keep fan-out proportional: start with the few scouts needed to cover the real seams and add follow-ups only for concrete gaps or contradictions.
 
-Integrate what they return into one coherent current-state map: the existing architecture, call paths, constraints, gaps, and `file:line` evidence. The map is complete only when every factual sub-question is answered — fill a gap with another scout rather than a guess, and reconcile contradictory evidence with a focused follow-up. Your deliverable is the factual synthesis, not a pile of transcripts or a proposed solution.
+Wait for all exploration agents in each wave to complete before reading their responses. Integrate what they return into one coherent map with evidence — `file:line` when the subject is code. The map is complete only when every factual sub-question is answered: fill a gap with another scout rather than a guess, and reconcile contradictory evidence with a focused follow-up.
+
+Your deliverable is `explore-map.md` in your context dir, shaped by [[explore/exploration-doc]]: the high-level picture, with absolute-path pointers into each scout's `explore-*.md` for depth. Task each scout to write its findings as an `explore-*.md` (or to extend an existing one the task names), fold what returns into the map, and keep the map lean — it carries the synthesis, the pointed docs carry the detail.

package/dist/builtin-memory/05-kinds/review/security-findings.md

@@ -10,4 +10,4 @@ surfaces:
 ---
 
 ## When a security concern is unproven
-A security finding needs evidence that the scenario applies: trace the reachable exploit path against the actual trust boundary and deployment context, resolving that context from source and deployment evidence first. When a material security posture is unknown rather than defective, ask through `crtr human send` instead of rating a hypothetical — the observed facts in plain language, the actor/access scenario and asset that would make the tightening worthwhile, and whether that scenario applies and should be fixed. That question stays out of the severity-rated findings. When you have a parent, report the confirmed verdict and the non-blocking question upward before awaiting the answer, with an urgent push when work is waiting on this review, so an unresolved posture does not stall what is already proved.
+A security finding needs evidence that the scenario applies: trace the reachable exploit path against the actual trust boundary and deployment context, resolving that context from source and deployment evidence first. When a material security posture is unknown rather than defective, ask through `crtr human send` instead of rating a hypothetical — the observed facts in plain language, the actor/access scenario and asset that would make the tightening worthwhile, and whether that scenario applies and should be fixed. That question stays out of the severity-rated findings. When you have a parent, report the confirmed verdict and the non-blocking question upward before awaiting the answer, with `crtr push update --tier urgent` when work is waiting on this review, so an unresolved posture does not stall what is already proved.

package/dist/builtin-memory/explore/exploration-doc.md

@@ -0,0 +1,27 @@
+---
+kind: knowledge
+when-and-why-to-read: When an explore node is about to write, extend, or synthesize an exploration doc, this knowledge should be read because the shared shape lets whoever receives the map act from the high level and drill into depth only where their task needs it.
+gate: {kind: explore}
+rationale: >-
+  Scout results arrived as one-off prose in whatever shape each node improvised: parents could not hand a map forward, follow-up scouts started over instead of extending, and orchestrators reassembled transcripts by hand — one layer revision even prescribed cp-and-rename of scout reports. A single named artifact contract replaces all of that.
+surfaces:
+  - on: boot
+    at: preview
+---
+
+# Exploration docs
+
+An exploration doc is the durable form of a mapping result: `explore-<topic>.md`, flat in your context dir, shared by absolute path. An orchestrator's synthesis is `explore-map.md` — the high-level picture, with absolute-path pointers into the `explore-*.md` docs that carry depth.
+
+Sections:
+
+- **Scope** — one or two lines: what this maps and where the boundary sits.
+- **The map** — the current state, organized by the subject's real seams (subsystem, layer, sub-question). Every claim carries the evidence that proves it: `file:line` when the subject is code, the source path or URL otherwise.
+- **Pointers** — absolute paths to the exploration docs holding deeper detail, one line each naming what depth it holds. Omit when there are none.
+- **Gaps** — what remains unmapped or unverified, stated explicitly so a reader does not mistake silence for verified absence.
+
+Rules:
+
+- When a task names an existing `explore-*.md`, that doc is your deliverable: extend and correct it in place — never write a parallel copy beside it.
+- Current state only. Recommendations, diagnosis, target design, and narration of how the exploration proceeded all belong elsewhere; a doc that accumulates them stops being a map.
+- These are goal-scoped working artifacts, not memory. A durable reusable truth uncovered while mapping still goes through the normal memory-capture path.

package/dist/clients/attach/__tests__/completion-frecency.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/clients/attach/__tests__/completion-frecency.test.js

@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { CombinedAutocompleteProvider } from '@earendil-works/pi-tui';
+import { RefAwareAutocompleteProvider } from '../input/ref-autocomplete.js';
+const noop = { record() { }, bonus: () => 0 };
+function ref(name) {
+    return { name, kind: 'knowledge', scope: 'user', shortForm: `${name} docs`, gatewayVisible: true };
+}
+const inertDelegate = {
+    async getSuggestions() { return null; },
+    applyCompletion(lines, cursorLine, cursorCol) { return { lines, cursorLine, cursorCol }; },
+    shouldTriggerFileCompletion() { return false; },
+};
+test('acceptance: typing /devnor surfaces northlight:dev via the ref provider', async () => {
+    const refs = [ref('northlight/dev'), ref('northlight/prod'), ref('taste/writing')];
+    const provider = new RefAwareAutocompleteProvider(refs, inertDelegate, noop);
+    const line = 'see /devnor';
+    const caret = line.length;
+    const result = await provider.getSuggestions([line], 0, caret, { signal: new AbortController().signal });
+    assert.ok(result, 'a ref suggestion is returned');
+    const labels = result.items.map((i) => i.label);
+    assert.ok(labels.includes('/northlight:dev'), `expected /northlight:dev, got ${labels.join(', ')}`);
+});
+test('acceptance: typing /devn at the start of the line surfaces the northlight:dev command', async () => {
+    // A memory doc flagged `slash: true` reaches the editor as an ordinary chat
+    // command named with `:` segments. pi-tui filters those by a subsequence over
+    // the raw name, which `devn` cannot satisfy; leaf-first matching can.
+    const commands = [{ name: 'northlight:dev' }, { name: 'reload' }, { name: 'git:pr-loop' }];
+    const provider = new RefAwareAutocompleteProvider([], new CombinedAutocompleteProvider(commands, process.cwd(), null), noop);
+    const line = '/devn';
+    const result = await provider.getSuggestions([line], 0, line.length, { signal: new AbortController().signal });
+    assert.ok(result, 'a command suggestion is returned');
+    assert.equal(result.prefix, line, 'prefix stays the text before the cursor so applyCompletion slices correctly');
+    assert.equal(result.items[0]?.value, 'northlight:dev', `expected northlight:dev first, got ${result.items.map((i) => i.value).join(', ')}`);
+});

package/dist/clients/attach/__tests__/ref-autocomplete.test.js

@@ -4,6 +4,8 @@ import { findRefCompletionContext, RefAwareAutocompleteProvider } from '../input
 function ref(name, shortForm = `${name} docs`) {
     return { name, kind: 'knowledge', scope: 'user', shortForm, gatewayVisible: true };
 }
+/** No-op frecency store: never records, never biases. */
+const noopFrecency = { record() { }, bonus: () => 0 };
 /** The wrapped provider; ref handling must never reach it in a ref context. */
 const inertDelegate = {
     async getSuggestions() { return null; },
@@ -51,7 +53,7 @@ test('findRefCompletionContext classifies leading, non-leading, and non-token ca
     assert.equal(findRefCompletionContext(['/dev  x'], 0, 5), null);
 });
 test('applying a ref completion replaces only the token and adds no separator', () => {
-    const provider = new RefAwareAutocompleteProvider([ref('dev')], inertDelegate);
+    const provider = new RefAwareAutocompleteProvider([ref('dev')], inertDelegate, noopFrecency);
     const line = 'before /de after';
     const cursorCol = line.indexOf('/de') + '/de'.length;
     const item = { value: 'dev', label: '/dev' };

package/dist/clients/attach/__tests__/titled-editor-preview.test.js

@@ -56,7 +56,8 @@ test('Enter-confirming a non-leading ref completion accepts the token and return
             return { lines, cursorLine, cursorCol };
         },
     };
-    editor.setAutocompleteProvider(new RefAwareAutocompleteProvider(refs, delegate));
+    const noopFrecency = { record() { }, bonus: () => 0 };
+    editor.setAutocompleteProvider(new RefAwareAutocompleteProvider(refs, delegate, noopFrecency));
     editor.setText('hey check /d');
     editor.handleInput('e'); // completes the typed prefix to '/de', triggering the non-leading bridge
     await new Promise((resolve) => setTimeout(resolve, 20));

package/dist/clients/attach/input/completion-frecency.d.ts

@@ -0,0 +1,45 @@
+export interface FrecencyStore {
+    /** Bump an item's count and stamp it now. `id` is namespaced by the caller
+     *  (`command:<name>` / `ref:<canonicalName>`) so a command and a ref of the
+     *  same name never collide. */
+    record(id: string): void;
+    /** The non-negative bonus to SUBTRACT from an item's fuzzy score. */
+    bonus(id: string, now?: number): number;
+}
+/** Create the viewer's single frecency store. Loads once; writes are debounced
+ *  and unref'd so they never hold the process open. */
+export declare function createFrecencyStore(filePath?: string): FrecencyStore;
+/**
+ * Filter `items` to fuzzy matches of `query` and sort by combined
+ * `fuzzyScore − frecencyBonus` (ascending; lower = better, matching pi-tui's
+ * convention). An empty query matches everything at fuzzy score 0, so the
+ * result is ordered purely by frecency — the bare-`/` "most-used first" list.
+ *
+ * `fuzzyMatch` is pi-tui's own exported matcher, so for a single-token query
+ * this produces exactly pi-tui's per-item score; the frecency term is the only
+ * perturbation.
+ */
+export declare function rankByFuzzyFrecency<T>(items: readonly T[], query: string, opts: {
+    searchableOf: (item: T) => string;
+    idOf: (item: T) => string;
+    store: FrecencyStore;
+    now?: number;
+}): T[];
+/**
+ * The string a namespaced name is fuzzy-matched against. Users reach for the
+ * meaningful LEAF ("dev"), so the leaf is placed first (earning pi-tui's
+ * word-boundary bonus) and the full name follows. This is what lets a
+ * cross-segment query like `devnor` match `northlight/dev` — `dev` from the
+ * leaf then `nor` from `northlight` — which a subsequence over the raw name
+ * cannot do.
+ *
+ * One helper serves both inventories: memory refs are namespaced with `/`
+ * (canonical `northlight/dev`) and slash commands with `:` (the same doc
+ * invoked as `/northlight:dev`), so the leaf is whatever follows the last
+ * separator of either kind.
+ */
+export declare function leafFirstSearchable(name: string): string;
+/** Normalize a typed ref query for matching: drop the surface `:` separators so
+ *  a typed `northlight:dev` matches the `/`-separated canonical searchable text,
+ *  and so cross-segment queries are not blocked by a separator mismatch. */
+export declare function normalizeRefQuery(surfacePrefixWithoutSlash: string): string;

package/dist/clients/attach/input/completion-frecency.js

@@ -0,0 +1,141 @@
+// input/completion-frecency.ts — per-user frequency/recency ("frecency") bias
+// for `/` completion, shared by the leading slash-command path and the inline
+// memory-ref path. The store persists a small usage map to the user scope root
+// (`~/.crouter/completion-frecency.json`) — user-wide state with no cwd
+// dimension, which per the storage tiers belongs there and NOT in canvas.db.
+// The viewer is a client and owns this plain JSON file directly; it never
+// touches canvas state.
+//
+// The design intent is a SLIGHT bias: `bonus` is capped well below the spread
+// of fuzzy scores, so it only breaks near-ties and fully orders the bare-`/`
+// list (where every fuzzy score is 0) by most-recent/most-used. A clearly
+// better fuzzy match always wins.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fuzzyMatch } from '@earendil-works/pi-tui';
+import { userScopeRoot } from '../../../core/scope.js';
+const FILE_NAME = 'completion-frecency.json';
+/** Recency half-life: a use's recency weight halves every two weeks. */
+const HALF_LIFE_MS = 14 * 24 * 60 * 60 * 1000;
+/** Maximum bonus subtracted from a fuzzy score. Chosen well below typical
+ *  good-match scores (−10…−30) so the bias never overrides a clearly better
+ *  fuzzy match — it only breaks near-ties and orders the all-zero empty list. */
+const BONUS_CAP = 8;
+/** Coalesce bursts of records into one disk write. */
+const WRITE_DEBOUNCE_MS = 1000;
+/** Pure frecency curve. Every entry reaching it is well-formed — `loadMap` is
+ *  the only untrusted source and validates there — so an unknown id is the only
+ *  case to handle here. */
+function frecencyBonus(entry, now) {
+    if (!entry)
+        return 0;
+    const ageMs = Math.max(0, now - entry.t);
+    const recency = Math.pow(0.5, ageMs / HALF_LIFE_MS); // (0, 1], 1 at age 0
+    const saturate = 1 - Math.exp(-entry.n / 3); // climbs fast, then flattens < 1
+    return BONUS_CAP * recency * saturate;
+}
+/** Load the usage map, keeping only well-formed entries. Anything else —
+ *  a non-object container, an array, a non-finite or non-positive `n`, a
+ *  non-finite `t` — is dropped, so a parseable-but-malformed file can never
+ *  poison a sort or silently swallow later writes. */
+function loadMap(filePath) {
+    const map = {};
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return map;
+        for (const [id, value] of Object.entries(parsed)) {
+            if (!value || typeof value !== 'object')
+                continue;
+            const { n, t } = value;
+            if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0)
+                continue;
+            if (typeof t !== 'number' || !Number.isFinite(t))
+                continue;
+            map[id] = { n, t };
+        }
+    }
+    catch {
+        // Missing or corrupt → start empty. No fallback theater; a fresh map is the
+        // honest state and self-heals on the next successful write.
+    }
+    return map;
+}
+function saveMap(filePath, map) {
+    try {
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, JSON.stringify(map), 'utf8');
+    }
+    catch {
+        // Best-effort persistence — a failed write loses only this session's counts,
+        // never breaks completion. The in-memory map stays authoritative for now.
+    }
+}
+/** Create the viewer's single frecency store. Loads once; writes are debounced
+ *  and unref'd so they never hold the process open. */
+export function createFrecencyStore(filePath = join(userScopeRoot(), FILE_NAME)) {
+    const map = loadMap(filePath);
+    let timer;
+    const scheduleWrite = () => {
+        if (timer)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            saveMap(filePath, map);
+        }, WRITE_DEBOUNCE_MS);
+        timer.unref?.();
+    };
+    return {
+        record: (id) => {
+            const prev = map[id];
+            map[id] = { n: (prev?.n ?? 0) + 1, t: Date.now() };
+            scheduleWrite();
+        },
+        bonus: (id, now = Date.now()) => frecencyBonus(map[id], now),
+    };
+}
+/**
+ * Filter `items` to fuzzy matches of `query` and sort by combined
+ * `fuzzyScore − frecencyBonus` (ascending; lower = better, matching pi-tui's
+ * convention). An empty query matches everything at fuzzy score 0, so the
+ * result is ordered purely by frecency — the bare-`/` "most-used first" list.
+ *
+ * `fuzzyMatch` is pi-tui's own exported matcher, so for a single-token query
+ * this produces exactly pi-tui's per-item score; the frecency term is the only
+ * perturbation.
+ */
+export function rankByFuzzyFrecency(items, query, opts) {
+    const now = opts.now ?? Date.now();
+    const scored = [];
+    for (const item of items) {
+        const match = fuzzyMatch(query, opts.searchableOf(item));
+        if (!match.matches)
+            continue;
+        scored.push({ item, score: match.score - opts.store.bonus(opts.idOf(item), now) });
+    }
+    scored.sort((a, b) => a.score - b.score);
+    return scored.map((s) => s.item);
+}
+/**
+ * The string a namespaced name is fuzzy-matched against. Users reach for the
+ * meaningful LEAF ("dev"), so the leaf is placed first (earning pi-tui's
+ * word-boundary bonus) and the full name follows. This is what lets a
+ * cross-segment query like `devnor` match `northlight/dev` — `dev` from the
+ * leaf then `nor` from `northlight` — which a subsequence over the raw name
+ * cannot do.
+ *
+ * One helper serves both inventories: memory refs are namespaced with `/`
+ * (canonical `northlight/dev`) and slash commands with `:` (the same doc
+ * invoked as `/northlight:dev`), so the leaf is whatever follows the last
+ * separator of either kind.
+ */
+export function leafFirstSearchable(name) {
+    const cut = Math.max(name.lastIndexOf('/'), name.lastIndexOf(':'));
+    return cut < 0 ? name : `${name.slice(cut + 1)} ${name}`;
+}
+/** Normalize a typed ref query for matching: drop the surface `:` separators so
+ *  a typed `northlight:dev` matches the `/`-separated canonical searchable text,
+ *  and so cross-segment queries are not blocked by a separator mismatch. */
+export function normalizeRefQuery(surfacePrefixWithoutSlash) {
+    return surfacePrefixWithoutSlash.replace(/:/g, '');
+}

package/dist/clients/attach/input/controller.d.ts

@@ -2,6 +2,7 @@ import type { CustomEditor } from '@earendil-works/pi-coding-agent';
 import type { Component, KeybindingsManager, TUI } from '@earendil-works/pi-tui';
 import { type BrokerDataFrame, type BrokerSnapshot, type ClientToBroker, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from '../../../core/runtime/broker-protocol.js';
 import type { ReadOpRequest } from '../../../core/broker-client/index.js';
+import type { FrecencyStore } from './completion-frecency.js';
 import type { CopyTarget } from '../render/transcript-copy.js';
 import { type ViewerCapabilities } from './capabilities.js';
 import { InputOverlayOwner } from './overlay-owner.js';
@@ -31,6 +32,12 @@ export interface InputControllerHooks {
     isDormant?: () => boolean;
     onDormantSubmit?: (text: string) => void;
     onPromptSent?: () => void;
+    /** Per-user completion frecency store — usage recorded here biases the sort
+     *  order the next time `/` completion opens. */
+    frecency?: FrecencyStore;
+    /** Canonical names of currently-resolvable memory refs, so a submitted
+     *  message records ONLY real refs, not arbitrary slash tokens. */
+    knownRefNames?: () => ReadonlySet<string>;
 }
 export declare class InputController {
     private readonly tui;
@@ -57,6 +64,16 @@ export declare class InputController {
     private readOnlyLabel;
     private wire;
     private slashContext;
+    /** Record a leading slash command as used. Called only once the command has
+     *  actually run — after a successful local dispatch or a successful send — so
+     *  refused, unsupported, and rejected submissions never bias completion. */
+    private recordCommandUse;
+    /** Record usage so `/` completion can bias toward frequently/recently used
+     *  items next time. A leading slash token is a command; every resolvable
+     *  memory ref found in submitted prose is a ref use. Called only on the
+     *  success paths of `handleSubmit` — never for bash, a refused drive, or a
+     *  submission that classified out. */
+    private recordCompletionUse;
     private handleSubmit;
     private handleFollowUp;
     private handleDequeue;

package/dist/clients/attach/input/controller.js

@@ -7,6 +7,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { BROKER_READ_CAPS, encodeFrame, } from '../../../core/runtime/broker-protocol.js';
 import { classifySubmit } from '../../conversation/submit.js';
+import { findRefTokens } from '../../../core/memory/inline-ref-grammar.js';
 import { dispatchSlashCommand, isSlashCommand } from '../slash/dispatch.js';
 import { viewerOperationForFrame } from './capabilities.js';
 import { readClipboardImage, writeClipboardImageToFile } from './clipboard-image.js';
@@ -141,11 +142,48 @@ export class InputController {
             openLogoutPicker: this.hooks.openLogoutPicker,
         };
     }
+    /** Record a leading slash command as used. Called only once the command has
+     *  actually run — after a successful local dispatch or a successful send — so
+     *  refused, unsupported, and rejected submissions never bias completion. */
+    recordCommandUse(trimmed) {
+        const store = this.hooks.frecency;
+        if (!store)
+            return;
+        const name = trimmed.slice(1).split(/\s/, 1)[0];
+        if (name)
+            store.record(`command:${name}`);
+    }
+    /** Record usage so `/` completion can bias toward frequently/recently used
+     *  items next time. A leading slash token is a command; every resolvable
+     *  memory ref found in submitted prose is a ref use. Called only on the
+     *  success paths of `handleSubmit` — never for bash, a refused drive, or a
+     *  submission that classified out. */
+    recordCompletionUse(text) {
+        const store = this.hooks.frecency;
+        if (!store)
+            return;
+        const trimmed = text.trim();
+        if (isSlashCommand(trimmed)) {
+            this.recordCommandUse(trimmed);
+            return;
+        }
+        const known = this.hooks.knownRefNames?.();
+        if (!known || known.size === 0)
+            return;
+        const recorded = new Set();
+        for (const token of findRefTokens(text)) {
+            if (known.has(token.candidate) && !recorded.has(token.candidate)) {
+                recorded.add(token.candidate);
+                store.record(`ref:${token.candidate}`);
+            }
+        }
+    }
     handleSubmit(text) {
         const trimmed = text.trim();
         if (!trimmed)
             return;
         if (isSlashCommand(trimmed) && dispatchSlashCommand(trimmed, this.slashContext())) {
+            this.recordCommandUse(trimmed);
             this.editor.setText('');
             return;
         }
@@ -162,6 +200,7 @@ export class InputController {
             if (submit === undefined)
                 return;
             submit(this.expandImagePlaceholders(classification.text));
+            this.recordCompletionUse(text);
             this.editor.addToHistory(classification.trimmed);
             this.editor.setText('');
             this.clearPastedImages();
@@ -183,6 +222,7 @@ export class InputController {
         const expanded = this.expandImagePlaceholders(classification.kind === 'slash' ? text : classification.text);
         if (!this.emitDrive(delivery === 'steer' ? { type: 'steer', text: expanded } : { type: 'prompt', text: expanded }))
             return;
+        this.recordCompletionUse(text);
         this.editor.addToHistory(classification.trimmed);
         this.editor.setText('');
         this.clearPastedImages();

package/dist/clients/attach/input/ref-autocomplete.d.ts

@@ -1,5 +1,6 @@
 import type { AutocompleteItem, AutocompleteProvider, AutocompleteSuggestions } from '@earendil-works/pi-tui';
 import type { RefMeta } from '../../../core/runtime/broker-protocol.js';
+import { type FrecencyStore } from './completion-frecency.js';
 /** The caret's classification for completion purposes. `null` means the caret
  *  is not touching any slash token at all (every other autocomplete mode —
  *  file, `@`, etc. — is unaffected and this provider fully delegates). */
@@ -52,7 +53,8 @@ export declare class RefAwareAutocompleteProvider implements AutocompleteProvide
     private readonly refs;
     private readonly refNames;
     private readonly delegate;
-    constructor(refs: ReadonlyArray<RefMeta>, delegate: AutocompleteProvider);
+    private readonly frecency;
+    constructor(refs: ReadonlyArray<RefMeta>, delegate: AutocompleteProvider, frecency: FrecencyStore);
     /** Pass through unchanged — pi-tui's editor explicitly discards `/` as a
      *  trigger character regardless, and `CombinedAutocompleteProvider` doesn't
      *  declare any of its own, so this is normally `undefined`. */

package/dist/clients/attach/input/ref-autocomplete.js

@@ -15,6 +15,7 @@
 // command context") or anywhere else ("non-leading ref context"). It does not
 // reimplement `[A-Za-z0-9_:-]`, trimming, or boundary detection.
 import { findRefTokenAtCaret, formatRefToken } from '../../../core/memory/inline-ref-grammar.js';
+import { leafFirstSearchable, normalizeRefQuery, rankByFuzzyFrecency, } from './completion-frecency.js';
 /**
  * Classify the slash token (if any) touching the caret at
  * `(cursorLine, cursorCol)` in the editor's logical `lines`. Joins the lines
@@ -67,10 +68,12 @@ export class RefAwareAutocompleteProvider {
     refs;
     refNames;
     delegate;
-    constructor(refs, delegate) {
+    frecency;
+    constructor(refs, delegate, frecency) {
         this.refs = refs;
         this.refNames = new Set(refs.map((ref) => ref.name));
         this.delegate = delegate;
+        this.frecency = frecency;
     }
     /** Pass through unchanged — pi-tui's editor explicitly discards `/` as a
      *  trigger character regardless, and `CombinedAutocompleteProvider` doesn't
@@ -80,11 +83,49 @@ export class RefAwareAutocompleteProvider {
     }
     async getSuggestions(lines, cursorLine, cursorCol, options) {
         const context = findRefCompletionContext(lines, cursorLine, cursorCol);
-        if (!context || context.kind === 'leading') {
+        if (!context) {
             return this.delegate.getSuggestions(lines, cursorLine, cursorCol, options);
         }
-        const prefix = context.prefix;
-        const matches = this.refs.filter((ref) => formatRefToken(ref.name).startsWith(prefix));
+        if (context.kind === 'leading') {
+            // Leading command-name completion. On a forced (Tab) trigger pi-tui runs
+            // file completion instead of command completion, so that must delegate
+            // verbatim.
+            if (options.force) {
+                return this.delegate.getSuggestions(lines, cursorLine, cursorCol, options);
+            }
+            // The delegate still CONSTRUCTS the items (reusing its description and
+            // argumentHint formatting), but it filters them by a subsequence over the
+            // raw command name, which cannot match a namespaced command by its leaf:
+            // `devn` never matches `northlight:dev` because the `n` comes first in the
+            // raw string. So ask it for the whole list — an empty query matches
+            // everything — and apply the same leaf-first fuzzy match plus slight
+            // frecency bias the ref path uses. A one-token query over a name with no
+            // separator scores exactly as pi-tui scored it, so plain commands keep
+            // their previous order and frecency is the only perturbation there.
+            // `applyCompletion` slices back by `prefix.length`, so the query and the
+            // returned prefix are both the text before the cursor — exactly what pi-tui
+            // matches on and returns for this branch. A leading token starts at global
+            // offset 0, so that text always begins with the `/`.
+            const textBeforeCursor = (lines[cursorLine] ?? '').slice(0, cursorCol);
+            const all = await this.delegate.getSuggestions(['/'], 0, 1, options);
+            if (!all)
+                return null;
+            const items = rankByFuzzyFrecency(all.items, textBeforeCursor.slice(1), {
+                searchableOf: (item) => leafFirstSearchable(item.value),
+                idOf: (item) => `command:${item.value}`,
+                store: this.frecency,
+            });
+            if (items.length === 0)
+                return null;
+            return { items, prefix: textBeforeCursor };
+        }
+        // Non-leading ref completion: fuzzy match (leaf-first searchable) with a
+        // slight frecency bias, replacing the former case-sensitive prefix filter.
+        const matches = rankByFuzzyFrecency(this.refs, normalizeRefQuery(context.prefix.slice(1)), {
+            searchableOf: (ref) => leafFirstSearchable(ref.name),
+            idOf: (ref) => `ref:${ref.name}`,
+            store: this.frecency,
+        });
         if (matches.length === 0)
             return null;
         const items = matches.map((ref) => ({
@@ -92,9 +133,9 @@ export class RefAwareAutocompleteProvider {
             label: formatRefToken(ref.name),
             description: ref.shortForm || undefined,
         }));
-        // Filtering above used the full slash-form `prefix` (context.prefix always
-        // starts with '/' for a matched token), but the RETURNED prefix strips that
-        // leading '/'. pi-tui's `handleInput` (tui.select.confirm
+        // Matching above used a normalized query, but the RETURNED prefix is the
+        // typed surface form with its leading '/' stripped. pi-tui's `handleInput`
+        // (tui.select.confirm
         // branch) falls through to `submitValue()` whenever `autocompletePrefix`
         // (set verbatim from this return value) starts with '/' — that's its own
         // leading-command-completion submit shortcut, and a non-leading ref
@@ -105,7 +146,7 @@ export class RefAwareAutocompleteProvider {
         // its `prefix` argument (it recomputes the token position fresh each call
         // via `findRefCompletionContext`), so this change has no effect on
         // replacement correctness.
-        return { items, prefix: prefix.slice(1) };
+        return { items, prefix: context.prefix.slice(1) };
     }
     applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
         const context = findRefCompletionContext(lines, cursorLine, cursorCol);

package/dist/clients/attach/input/titled-editor.d.ts

@@ -198,6 +198,9 @@ export declare class TitledEditor extends CustomEditor {
      *  `list_memory_refs` reply, alongside `resolvedRefNames`. */
     private engineCommandNames;
     setResolvedRefNames(names: Iterable<string>): void;
+    /** The canonical names of memory refs currently resolvable in this session —
+     *  used to record ref usage on submit without counting non-ref slash tokens. */
+    getResolvedRefNames(): ReadonlySet<string>;
     setLocalCommandNames(names: Iterable<string>): void;
     setEngineCommandNames(names: Iterable<string>): void;
     /** Render-only decoration pass: underlines every resolved-ref span visible