@north-light/crouter 0.3.250 → 0.3.252

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/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/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

package/dist/clients/attach/input/titled-editor.js

@@ -740,6 +740,11 @@ export class TitledEditor extends CustomEditor {
     setResolvedRefNames(names) {
         this.resolvedRefNames = new Set(names);
     }
+    /** 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() {
+        return this.resolvedRefNames;
+    }
     setLocalCommandNames(names) {
         this.localCommandNames = new Set(names);
     }

package/dist/clients/attach/session/editor-inventory.d.ts

@@ -1,5 +1,6 @@
 import { CombinedAutocompleteProvider } from '@earendil-works/pi-tui';
 import type { BrokerDataFrame, RefMeta } from '../../../core/runtime/broker-protocol.js';
+import type { FrecencyStore } from '../input/completion-frecency.js';
 import type { ViewerCapabilities } from '../input/capabilities.js';
 import { type PreviewableCommand } from '../slash/prompt-preview.js';
 import type { AttachBindings } from './bindings.js';
@@ -51,6 +52,8 @@ export interface EditorInventoryHooks {
     bindings: () => AttachBindings;
     /** Resolved once in `runAttach`; never changes for the session. */
     fdPath: string | null;
+    /** Per-user frecency store — biases command/ref completion order by usage. */
+    frecency: FrecencyStore;
 }
 /** Owns everything the editor can complete against — the merged slash-command
  *  list, the loaded-command preview, the broker's raw command metadata, and the

package/dist/clients/attach/session/editor-inventory.js

@@ -91,7 +91,7 @@ export function createEditorInventory(ctx, capabilities, hooks) {
     // reads only `commands`, never `memoryRefs`).
     const syncEditorInventories = () => {
         const commandProvider = buildAttachAutocompleteProvider(meta.cwd, hooks.fdPath, brokerCommands, capabilities);
-        editor.setAutocompleteProvider(new RefAwareAutocompleteProvider(memoryRefs, commandProvider));
+        editor.setAutocompleteProvider(new RefAwareAutocompleteProvider(memoryRefs, commandProvider, hooks.frecency));
         editor.setResolvedRefNames(memoryRefs.map((ref) => ref.name));
         // Two independent suppression inventories: the viewer-local
         // set (everything `dispatchSlashCommand` handles entirely locally, trimmed

package/dist/clients/attach/session/input-wiring.d.ts

@@ -1,4 +1,5 @@
 import { InputController } from '../input/controller.js';
+import type { FrecencyStore } from '../input/completion-frecency.js';
 import { type ViewerCapabilities } from '../input/capabilities.js';
 import type { ToolDisplayToggle } from '../render/chat-view.js';
 import type { KeybindingsManager } from '@earendil-works/pi-tui';
@@ -40,6 +41,8 @@ export interface InputWiringHooks {
     setChipColor: (color: string | null) => void;
     /** A prompt or steer was accepted from the editor. */
     onPromptSent: () => void;
+    /** Per-user completion frecency store, shared with the editor inventory. */
+    frecency: FrecencyStore;
 }
 /** Construct the viewer's one capability authority. */
 export declare function createViewerCapabilitiesForInput(ctx: Pick<AttachSession, 'nodeId' | 'remote' | 'role' | 'meta'>): ViewerCapabilities;

package/dist/clients/attach/session/input-wiring.js

@@ -74,6 +74,8 @@ export function createInputController(ctx, km, capabilities, hooks) {
         },
         onColor: hooks.setChipColor,
         onPromptSent: hooks.onPromptSent,
+        frecency: hooks.frecency,
+        knownRefNames: () => editor.getResolvedRefNames(),
         // Global display toggles (Ctrl+O tools / Ctrl+T thinking) — pure render
         // state owned by ChatView, surfaced as a footer notice mirroring pi's
         // status line.