@north-light/crouter 0.3.219 → 0.3.221

package/dist/core/__tests__/profile-project-memory-delivery.test.js

@@ -0,0 +1,217 @@
+// A selected profile's project relationship caps AUTOMATIC delivery — boot and
+// workspace-open — and nothing else. The reported failure this suite exists for:
+// a profile project that is also the node's cwd rendered its authored rung, as
+// if the relationship applied only to projects reached through the manifest.
+//
+// One real fixture drives the real scope resolver, the real boot renderer, the
+// real workspace-open renderer, and the real `crtr memory read` leaf: a profile
+// whose four projects sit at none/name/preview/content in manifest order, with
+// the `preview` project as cwd and canonical-name collisions across projects and
+// against the wider user scope.
+//
+// Migration convergence is NOT here — it lives in migration.test.ts.
+//
+// Run: node --conditions=crtr-src --import tsx/esm --test src/core/__tests__/profile-project-memory-delivery.test.ts
+import { test, before, beforeEach, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { closeDb } from '../canvas/db.js';
+import { resetScopeCache } from '../scope.js';
+import { createProfile } from '../profiles/manifest.js';
+import { spawnNode } from '../runtime/nodes.js';
+import { clearSessionCache } from '../substrate/session-cache.js';
+import { renderKnowledgeBlock } from '../substrate/render-node.js';
+import { renderWorkspaceOpenDocs } from '../substrate/on-read-node.js';
+import { deliveredAtOrAbove, loadInjectedDocs, saveInjectedDocs, } from '../substrate/injected-store.js';
+import { readLeaf } from '../../commands/memory/read.js';
+const B = {
+    pnone: 'BODY-T9-PNONE',
+    pname: 'BODY-T9-PNAME',
+    ppreview: 'BODY-T9-PPREVIEW',
+    pcontent: 'BODY-T9-PCONTENT',
+    sharedFromPnone: 'BODY-T9-SHARED-FROM-PNONE',
+    sharedFromPcontent: 'BODY-T9-SHARED-FROM-PCONTENT',
+    nameFromPname: 'BODY-T9-NAMEDUP-FROM-PNAME',
+    nameFromPcontent: 'BODY-T9-NAMEDUP-FROM-PCONTENT',
+    userDupFromPnone: 'BODY-T9-USERDUP-FROM-PNONE',
+    userDupFromUser: 'BODY-T9-USERDUP-FROM-USER',
+};
+let home;
+let canvasHome;
+let profileId;
+let prevHome;
+let prevCanvasHome;
+let prevProfile;
+let prevNode;
+let prevCwd;
+let cwdProject;
+let ppreviewDocPath;
+/** A doc delivered automatically at the top rung by both automatic channels —
+ *  every cap observed below is the relationship's, never the author's. */
+function autoDoc(when, body) {
+    return [
+        '---',
+        'kind: knowledge',
+        `when-and-why-to-read: "${when}"`,
+        'surfaces:',
+        '  - {on: boot, at: content}',
+        '  - {on: workspace-open, at: content}',
+        '---',
+        '',
+        body,
+        '',
+    ].join('\n');
+}
+/** No surfaces at all: invisible at boot, counted into its dir's `[+N more]`. */
+function bootlessDoc(when, body) {
+    return ['---', 'kind: knowledge', `when-and-why-to-read: "${when}"`, '---', '', body, ''].join('\n');
+}
+function writeDoc(storeDir, relName, contents) {
+    const path = join(storeDir, `${relName}.md`);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, contents);
+    return path;
+}
+before(() => {
+    prevHome = process.env['HOME'];
+    prevCanvasHome = process.env['CRTR_HOME'];
+    prevProfile = process.env['CRTR_PROFILE_ID'];
+    prevNode = process.env['CRTR_NODE_ID'];
+    prevCwd = process.cwd();
+    // realpath: the manifest owner persists realpath-resolved project paths. A raw
+    // /var/folders path on macOS makes the cwd ancestor walk and the profile
+    // pointer name two different roots, and the cwd project then reads as uncapped
+    // for the wrong reason.
+    home = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-ppm-home-')));
+    canvasHome = realpathSync(mkdtempSync(join(tmpdir(), 'crtr-ppm-canvas-')));
+    process.env['HOME'] = home;
+    process.env['CRTR_HOME'] = canvasHome;
+    const store = (slug) => {
+        const dir = join(home, slug, '.crouter', 'memory');
+        mkdirSync(dir, { recursive: true });
+        return dir;
+    };
+    const pnone = store('pnone');
+    const pname = store('pname');
+    const ppreview = store('ppreview');
+    const pcontent = store('pcontent');
+    const user = join(home, '.crouter', 'memory');
+    mkdirSync(user, { recursive: true });
+    writeDoc(pnone, 't9-pnone-doc', autoDoc('When the none project delivers', B.pnone));
+    writeDoc(pname, 't9-pname-doc', autoDoc('When the name project delivers', B.pname));
+    ppreviewDocPath = writeDoc(ppreview, 't9-ppreview-doc', autoDoc('When the cwd project delivers', B.ppreview));
+    writeDoc(pcontent, 't9-pcontent-doc', autoDoc('When the content project delivers', B.pcontent));
+    // Collision one: `none` (earlier in manifest order) vs `content`. The cap must
+    // apply before name dedupe, so the dropped entry cannot shadow the winner.
+    writeDoc(pnone, 't9-shared-doc', autoDoc('When the shared name resolves', B.sharedFromPnone));
+    writeDoc(pcontent, 't9-shared-doc', autoDoc('When the shared name resolves', B.sharedFromPcontent));
+    // Collision two: `name` vs `content`. A non-none cap keeps its project's
+    // precedence and discloses at the capped rung — it does not step aside.
+    writeDoc(pname, 't9-namedup-doc', autoDoc('When the name-capped duplicate resolves', B.nameFromPname));
+    writeDoc(pcontent, 't9-namedup-doc', autoDoc('When the name-capped duplicate resolves', B.nameFromPcontent));
+    // Collision three: `none` vs the wider user scope, which project precedence
+    // would otherwise beat.
+    writeDoc(pnone, 't9-userdup-doc', autoDoc('When the user duplicate resolves', B.userDupFromPnone));
+    writeDoc(user, 't9-userdup-doc', autoDoc('When the user duplicate resolves', B.userDupFromUser));
+    // Hidden-count pair: a top-level dir always renders, so a dir holding only a
+    // bootless doc shows as `<dir>/` + `[+1 more]` — unless its project is `none`.
+    writeDoc(pnone, join('t9-none-hidden', 'probe'), bootlessDoc('When counted', 'HIDDEN-NONE'));
+    writeDoc(pcontent, join('t9-hidden-control', 'probe'), bootlessDoc('When counted', 'HIDDEN-CONTROL'));
+    profileId = createProfile('t9', [
+        { path: join(home, 'pnone'), memory: 'none' },
+        { path: join(home, 'pname'), memory: 'name' },
+        { path: join(home, 'ppreview'), memory: 'preview' },
+        { path: join(home, 'pcontent'), memory: 'content' },
+    ]).profileId;
+    process.env['CRTR_PROFILE_ID'] = profileId;
+    // The node works INSIDE a capped project: the reported failure.
+    cwdProject = join(home, 'ppreview');
+    process.chdir(cwdProject);
+});
+beforeEach(() => {
+    resetScopeCache();
+    clearSessionCache();
+});
+after(() => {
+    closeDb();
+    resetScopeCache();
+    clearSessionCache();
+    process.chdir(prevCwd);
+    rmSync(home, { recursive: true, force: true });
+    rmSync(canvasHome, { recursive: true, force: true });
+    const restore = (key, value) => {
+        if (value === undefined)
+            delete process.env[key];
+        else
+            process.env[key] = value;
+    };
+    restore('HOME', prevHome);
+    restore('CRTR_HOME', prevCanvasHome);
+    restore('CRTR_PROFILE_ID', prevProfile);
+    restore('CRTR_NODE_ID', prevNode);
+});
+function newNode() {
+    return spawnNode({ kind: 'general', cwd: cwdProject, parent: null, profile_id: profileId }).node_id;
+}
+test('boot delivery caps every profile project at its relationship, including the one used as cwd', () => {
+    const boot = renderKnowledgeBlock(newNode(), new Map());
+    // The control: an uncapped relationship still renders its authored content.
+    assert.ok(boot.includes(B.pcontent), `the content-capped project renders its body; got:\n${boot}`);
+    // The reported failure. cwd reaches this root before the manifest pointer
+    // does, and the relationship still decides the ceiling.
+    assert.ok(!boot.includes(B.ppreview), `the cwd project is capped at preview — its body must not render; got:\n${boot}`);
+    assert.match(boot, /t9-ppreview-doc {2}# read when: When the cwd project delivers\./, `the cwd project's doc discloses at preview; got:\n${boot}`);
+    // `name` discloses the bare identifier and nothing else.
+    assert.ok(!boot.includes(B.pname), 'a name-capped project must not render a body');
+    assert.match(boot, /[├└]─ t9-pname-doc$/m, `the name-capped doc discloses as a bare name; got:\n${boot}`);
+    assert.ok(!boot.includes('When the name project delivers'), 'a name-capped doc discloses no preview line');
+});
+test('a `none` project contributes nothing to boot — no body, no name, no hidden count, no shadow', () => {
+    const boot = renderKnowledgeBlock(newNode(), new Map());
+    assert.ok(!boot.includes(B.pnone), 'a none-capped body must not render');
+    assert.ok(!boot.includes('t9-pnone-doc'), 'a none-capped doc must not appear as a name either');
+    // Hidden counts are disclosure too: the control dir proves a bootless doc
+    // does surface as a `[+N more]` count, so the none project's absence is the cap.
+    assert.match(boot, /t9-hidden-control\/\n.*\[\+1 more\]/, `the control dir shows its hidden count; got:\n${boot}`);
+    assert.ok(!boot.includes('t9-none-hidden'), 'a none-capped project contributes no `[+N more]` count');
+    // Shadowing: `none` wins name dedupe on precedence, so a cap applied after
+    // dedupe would silently delete the winner instead of deferring to it.
+    assert.ok(boot.includes(B.sharedFromPcontent) && !boot.includes(B.sharedFromPnone), `the content project wins the collision the none project would have taken; got:\n${boot}`);
+    assert.ok(boot.includes(B.userDupFromUser) && !boot.includes(B.userDupFromPnone), `a none project does not shadow the wider user-scope winner; got:\n${boot}`);
+});
+test('a non-none cap keeps its project precedence and discloses the duplicate at the capped rung', () => {
+    const boot = renderKnowledgeBlock(newNode(), new Map());
+    assert.match(boot, /[├└]─ t9-namedup-doc$/m, `the name-capped duplicate wins dedupe; got:\n${boot}`);
+    assert.ok(!boot.includes(B.nameFromPname), 'the winner discloses at `name`, never its body');
+    assert.ok(!boot.includes(B.nameFromPcontent), 'the content project does not take a collision the name project already won');
+});
+test('workspace-open clamps each project store the same way boot does', () => {
+    const opened = renderWorkspaceOpenDocs(newNode(), new Map());
+    assert.ok(opened.includes(B.pcontent), `the content-capped project delivers its body; got:\n${opened}`);
+    assert.ok(!opened.includes(B.ppreview), `the cwd project must not deliver its body; got:\n${opened}`);
+    assert.match(opened, /name="t9-ppreview-doc"[^>]*>\nWhen the cwd project delivers\./, `the cwd project delivers its preview line; got:\n${opened}`);
+    assert.match(opened, /name="t9-pname-doc"[^>]*\/>/, `the name-capped doc delivers name-only; got:\n${opened}`);
+    assert.ok(!opened.includes('t9-pnone-doc'), 'the none-capped project delivers nothing at workspace-open');
+    assert.ok(!opened.includes(B.sharedFromPnone), 'nor its side of a name collision');
+});
+test('an explicit `crtr memory read` returns and records the full body a cap withheld', async () => {
+    const node = newNode();
+    process.env['CRTR_NODE_ID'] = node;
+    const seen = loadInjectedDocs(node);
+    const opened = renderWorkspaceOpenDocs(node, seen);
+    assert.ok(!opened.includes(B.ppreview), 'workspace-open disclosed the capped doc at preview only');
+    saveInjectedDocs(node, seen);
+    const result = (await readLeaf.run({ name: 't9-ppreview-doc', frontmatter: false }));
+    assert.equal(result.path, ppreviewDocPath, 'the read resolved the cwd project doc');
+    assert.ok(result.content.includes(B.ppreview), `an explicit read is uncapped and returns the full body; got:\n${result.content}`);
+    const afterRead = loadInjectedDocs(node);
+    assert.ok(deliveredAtOrAbove(afterRead, ppreviewDocPath, 'content'), 'the explicit read records a content delivery, upgrading the preview disclosure');
+    // A later automatic event runs at the capped rung, which is now below what the
+    // transcript holds, so it re-delivers nothing.
+    assert.equal(renderWorkspaceOpenDocs(node, afterRead), '', 'a later lower automatic event re-delivers nothing');
+    // ...and the emptiness is the dedup set, not a dead render.
+    assert.ok(renderWorkspaceOpenDocs(node, new Map()).includes('t9-ppreview-doc'), 'the same call against a fresh transcript still delivers');
+    delete process.env['CRTR_NODE_ID'];
+});

package/dist/core/__tests__/seam/dormancy-release.test.js

@@ -19,20 +19,23 @@
 // they belong to the compiled seam tier; neither needs tmux.
 import { after, before, test } from 'node:test';
 import assert from 'node:assert/strict';
-import { writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { appendInbox, readCursor, readInboxSince } from '../../feed/inbox.js';
 import { registerWarmSpare, subscribe, updateNode } from '../../canvas/index.js';
 import { isPidAlive } from '../../canvas/pid.js';
 import { reviveNode } from '../../runtime/revive.js';
 import { createHarness } from '../helpers/harness.js';
+import { createAttachKit } from '../helpers/broker-clients.js';
 let h;
 let root;
+const attach = createAttachKit(() => h);
 before(async () => {
     h = await createHarness({ headless: true, sessionPrefix: 'crtr-dormancy' });
     root = h.spawnRoot('dormancy-release suite root');
 });
 after(async () => {
+    attach.closeAll();
     if (h !== undefined)
         await h.dispose();
 });
@@ -187,6 +190,39 @@ test('an unattended resident with no live obligation completes on the daemon clo
             process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
     }
 });
+test('a non-attending observer does not prevent unattended resident parking', { timeout: 30_000 }, async () => {
+    const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+    process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';
+    const nodeId = h.fabricateBrokerNode({
+        id: 'settled-with-system-observer',
+        parent: root,
+        lifecycle: 'resident',
+        status: 'idle',
+        intent: 'idle-release',
+    });
+    updateNode(nodeId, { launch: { extensions: [], tools: [], systemPrompt: '', env: {} } });
+    reviveNode(nodeId, { resume: true });
+    const boot = await h.awaitBoot(nodeId);
+    await attach.attach(nodeId, 'observer', 'system-observer-test', { attends: false });
+    assert.equal(JSON.parse(readFileSync(join(h.home, 'nodes', nodeId, 'job', 'attach.json'), 'utf8')).viewers, 0, 'a non-attending hello is not persisted as human attendance');
+    try {
+        const seenAt = 12_000;
+        await h.tick(seenAt);
+        await h.tick(seenAt + 1500);
+        await h.waitFor(() => h.node(nodeId)?.status === 'done' && !isPidAlive(boot.pid), {
+            timeoutMs: 10_000,
+            intervalMs: 20,
+            label: 'system-observed unattended completion and broker exit',
+        });
+        await h.awaitFleetExit(nodeId);
+    }
+    finally {
+        if (priorParkMs === undefined)
+            delete process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
+        else
+            process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = priorParkMs;
+    }
+});
 test('a connected broker viewer keeps an obligation-free resident live', { timeout: 30_000 }, async () => {
     const priorParkMs = process.env['CRTR_TEST_UNATTENDED_PARK_MS'];
     process.env['CRTR_TEST_UNATTENDED_PARK_MS'] = '1500';

package/dist/core/__tests__/serial/broker-sdk-wiring.test.js

@@ -26,9 +26,10 @@ import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createAgentSessionServices, createAgentSessionFromServices, SessionManager, VERSION, } from '../../runtime/broker-sdk.js';
-import { buildBrokerSession, makeBrokerUiContext } from '../../runtime/broker.js';
-import { isLeadingEngineCommand, resolveSteerCall, chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, isHiddenJsonlBranchEntry, stripHiddenEntriesFromJsonlExport, engineLeadingCommandTokens, } from '../../runtime/broker/frame-dispatch.js';
+import { buildBrokerSession, makeBrokerUiContext, snapshotMessages } from '../../runtime/broker.js';
+import { isLeadingEngineCommand, resolveSteerCall, chooseGuidanceDeliveryMode, promptWithNextTurnGuidance, promptWithAdvertisedCommandInvocation, isHiddenJsonlBranchEntry, stripHiddenEntriesFromJsonlExport, engineLeadingCommandTokens, } from '../../runtime/broker/frame-dispatch.js';
 import { CANVAS_EXTENSIONS } from '../../runtime/launch.js';
+import { prepareAdvertisedCommandPersistence } from '../../runtime/advertised-command-invocation.js';
 // The REAL engine, assembled from broker-sdk's static SDK re-exports — bypasses
 // the CRTR_BROKER_ENGINE seam entirely so these tests can never accidentally hit
 // the fake (the whole point: prove the wiring the mock hid).
@@ -403,6 +404,105 @@ test('C5 — isLeadingEngineCommand against a REAL session (registered extension
         rmSync(cwd, { recursive: true, force: true });
     }
 });
+test('an advertised custom command persists its exact raw invocation without replacing expanded agent input', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-advertised-command-'));
+    try {
+        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C5_EXT] }));
+        try {
+            const raw = '/gatewaycmd   exact  spacing  ';
+            await promptWithAdvertisedCommandInvocation(session, raw, () => session.prompt(raw, {}));
+            const custom = session.sessionManager
+                .buildSessionContext()
+                .messages.find((message) => message.role === 'custom' && message.customType === 'fixture-output');
+            assert.deepEqual(custom, {
+                role: 'custom',
+                customType: 'fixture-output',
+                content: 'expanded agent input',
+                display: true,
+                details: { fixture: true },
+                crouterAdvertisedCommandInvocation: { raw },
+                timestamp: custom?.timestamp,
+            });
+            const welcome = snapshotMessages(session);
+            assert.ok(welcome);
+            const welcomeCustom = welcome.filter(({ message }) => message.role === 'custom' && message.customType === 'fixture-output');
+            assert.equal(welcomeCustom.length, 1, 'welcome reconstructs one advertised custom message');
+            assert.deepEqual(welcomeCustom[0].message
+                .crouterAdvertisedCommandInvocation, { raw }, 'welcome preserves the exact advertised invocation spacing');
+            const persisted = session.sessionManager
+                .getEntries()
+                .find((entry) => entry.type === 'custom_message' &&
+                entry.customType === 'fixture-output');
+            assert.equal(persisted?.type, 'custom_message');
+            if (persisted?.type !== 'custom_message')
+                assert.fail('custom message was not persisted');
+            assert.equal(persisted.content, 'expanded agent input');
+            assert.deepEqual(persisted.details, {
+                crouterPersistenceEnvelope: true,
+                crouterAdvertisedCommandInvocation: { raw },
+                extensionDetails: { fixture: true },
+            });
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});
+test('advertised invocation metadata survives nextTurn delivery and null content normalization', async () => {
+    const cwd = mkdtempSync(join(tmpdir(), 'crtr-advertised-next-turn-'));
+    try {
+        const { session } = await buildBrokerSession(realEngine, cfg(cwd, { extensionPaths: [C5_EXT] }));
+        try {
+            const rawA = '/gatewaynext  first exact text ';
+            const rawB = '/gatewaynext  second exact text ';
+            for (const raw of [rawA, rawB]) {
+                await promptWithAdvertisedCommandInvocation(session, raw, () => session.prompt(raw, {}));
+            }
+            const pending = session._pendingNextTurnMessages;
+            assert.deepEqual(pending.map((queued) => ({
+                content: queued.content,
+                details: queued.details,
+                invocation: queued.crouterAdvertisedCommandInvocation,
+            })), [
+                {
+                    content: [],
+                    details: 'extension-details',
+                    invocation: { raw: rawA },
+                },
+                {
+                    content: [],
+                    details: 'extension-details',
+                    invocation: { raw: rawB },
+                },
+            ]);
+            // Simulate a queue policy draining B before A. Payload equality cannot
+            // identify them; the app-message metadata must bind each persistence.
+            for (const queued of [pending[1], pending[0]]) {
+                prepareAdvertisedCommandPersistence(session, queued);
+                session.sessionManager.appendCustomMessageEntry(queued.customType, queued.content, queued.display, queued.details);
+            }
+            const restored = session.sessionManager
+                .buildSessionContext()
+                .messages.slice(-2);
+            assert.deepEqual(restored.map((message) => ({
+                details: message.details,
+                invocation: message.crouterAdvertisedCommandInvocation,
+            })), [
+                { details: 'extension-details', invocation: { raw: rawB } },
+                { details: 'extension-details', invocation: { raw: rawA } },
+            ]);
+        }
+        finally {
+            session.dispose();
+        }
+    }
+    finally {
+        rmSync(cwd, { recursive: true, force: true });
+    }
+});
 test('C5 — chooseGuidanceDeliveryMode truth table (pure)', () => {
     // idle prompt (routeCall='prompt', not streaming) -> guidance precedes the
     // human call, in the SAME turn.

package/dist/core/bootstrap.js

@@ -14,6 +14,12 @@ function shouldSkipForArgv(argv) {
     const sub = argv[2];
     if (sub === undefined)
         return true;
+    // `sys migrate` converges state that every other read already depends on:
+    // resolving a scope here would read the selected profile through the current
+    // reader (blind to a pre-migration manifest) and could scaffold a cwd scope
+    // the migration then has to treat as real. It owns its own discovery.
+    if (sub === 'sys' && argv[3] === 'migrate')
+        return true;
     return SKIP_SUBCOMMANDS.has(sub);
 }
 export function ensureProjectScope(argv) {

package/dist/core/canvas/browse/app.js

@@ -10,6 +10,7 @@
 import { execFileSync } from 'node:child_process';
 import { resolve } from 'node:path';
 import { dashboardRowsAllFromSource, enrichRowsFromSource, loadPreviewFromSource, renderForestFromSource } from '../render-source.js';
+import { fullName } from '../labels.js';
 import { setupTerminal, restoreTerminal, getTerminalSize, parseKeypress, } from '../../tui/terminal.js';
 import { buildTree, flatten, pruneNode, TABS } from './model.js';
 import { loadPins, savePins } from './pins.js';
@@ -483,8 +484,10 @@ export async function runBrowse(opts) {
                 /* best-effort — a rename failure never wedges the picker */
             }
             const n = tree.nodes.get(id);
-            if (n !== undefined)
-                n.row.name = name;
+            if (n !== undefined) {
+                n.row.handle = name;
+                n.row.name = fullName({ name, kind: n.row.kind, description: n.row.description });
+            }
         }
         recompute(state.renameTarget ?? undefined);
         scheduleFlush();

package/dist/core/canvas/browse/model.d.ts

@@ -70,11 +70,8 @@ export interface SnippetLine {
     text: string;
     hi: Set<number>;
 }
-/** Highlight indices for the preview: the literal case-insensitive SUBSTRING span
- *  when present (so "where does this text appear?" is answered exactly), else the
- *  scattered subsequence indices, else empty (empty query). This is a different,
- *  stricter model than the subsequence super-search on purpose — a contiguous span
- *  is what reads as a highlight. */
+/** The literal case-insensitive substring span in a conversation preview.
+ *  Scattered letters are not a message match and never receive a highlight. */
 export declare function highlightIndices(query: string, text: string): Set<number>;
 /**
  * Build the preview snippet for `text` under the live `query`: up to `maxLines`
@@ -91,17 +88,27 @@ export declare function previewSnippet(query: string, text: string, width: numbe
  *  windowed in the preview, so search matches a prompt from ANYWHERE in the
  *  conversation, not just the first one. */
 export declare function promptText(row: DashboardRow): string;
-/** Does this row match the live query? Super-search spans name (which already
- *  folds in the pi-generated description), kind, short-id, AND every user prompt
- *  in the conversation (`promptText`). Empty query matches everything. */
+/** Does this row match the live query? Empty query matches everything; a
+ *  non-empty query uses the same fields and match tiers as relevance ranking. */
 export declare function queryMatch(query: string, row: DashboardRow): boolean;
-/** Score how well `query` matches one field, 0 (no match) → 1 (exact). Tiers:
- *  exact > prefix > word-boundary substring > interior substring > subsequence.
- *  An interior match decays slightly the later it starts so leading matches win. */
-export declare function fieldScore(query: string, text: string): number;
-/** Weighted relevance of a row to the query across all searched fields. 0 means
- *  no field matched (excluded from relevance results, same as `queryMatch`). */
-export declare function scoreRow(query: string, row: DashboardRow): number;
+export type MatchTier = 0 | 1 | 2 | 3;
+export interface FieldMatch {
+    /** 3 = bounded word/phrase, 2 = contiguous partial, 1 = subsequence. */
+    tier: MatchTier;
+    /** Tie-break quality within one tier. */
+    quality: number;
+}
+export interface RelevanceScore {
+    tier: MatchTier;
+    strength: number;
+}
+/** One field's best match. Match class is deliberately separate from quality:
+ *  a bounded literal always outranks a contiguous partial, which always outranks
+ *  a scattered subsequence, regardless of field weights. */
+export declare function fieldMatch(query: string, text: string): FieldMatch;
+/** Rank a row by its strongest match class, then by weighted evidence only from
+ *  that class. Weaker classes cannot add up to beat one stronger literal match. */
+export declare function scoreRow(query: string, row: DashboardRow): RelevanceScore;
 /** The "most recent message" signal for the attention sort: the pi session-file
  *  mtime (ms) the snapshot stamps on each row, falling back to the `created`
  *  birth timestamp when no session file exists. Larger = more recent.
@@ -111,6 +118,9 @@ export declare function scoreRow(query: string, row: DashboardRow): number;
  *  update this single accessor. `created` is ISO 8601, so its epoch-ms is a
  *  monotonic stand-in within the same tier. */
 export declare function attentionMtime(row: DashboardRow): number;
+/** Up to a 10% relevance lift for recent conversation activity, halving after a
+ *  week. Match tier remains separate, so freshness never promotes fuzzy over literal. */
+export declare function relevanceFreshness(row: DashboardRow, now: number): number;
 /** Attention tier (lower = higher priority, shown first):
  *    T0 — attached AND streaming (`viewed && streaming`)
  *    T1 — attached, not streaming (`viewed`)