hafez 1.4.0 → 2.1.0

package/dist/cli/upgrade.js

@@ -3,7 +3,8 @@
 // `hafez upgrade` — agent-directed update check. It CHECKS AND PRINTS; it
 // never installs. The printed steps install code and overwrite the user's
 // agent instructions, so the privileged step is the human's — same discipline
-// as `onboard` (writes nothing outside the vault) and as the release skill
+// as bare `onboard` (writes nothing; only `--install`/`--remove`, run after
+// the user's yes, write outside the vault) and as the release skill
 // (`npm publish` is the user's action). It also sidesteps a process replacing
 // its own binary mid-run.
 //
@@ -11,6 +12,11 @@
 // or the native SQLite binding is unbuilt, which is exactly when someone is
 // trying to upgrade. Nothing here touches the core.
 //
+// The skills and the Block are checked by their hashes, in every place
+// `onboard --install` writes them (install.ts), and only where they are
+// installed: no Block means invoke-only, never a Block to offer. Refreshing
+// them is `onboard --install`'s job, so that is the step printed.
+//
 // Untrusted input: the registry response is rendered into a document an agent
 // will execute commands from. Only the `version` field is read, only after it
 // matches plain X.Y.Z, and no caught error's message, cause, or stack ever
@@ -21,8 +27,9 @@ import { existsSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { UsageError } from './args.js';
-import { INTEGRATION_SNIPPET } from './onboard.js';
+import { UsageError, helpIfAsked } from './args.js';
+import { HARNESSES, detectAgent, isHarness } from '../harness.js';
+import { checkInstall, fixBrokenMarkers, legacyLine, removeLegacy } from './install.js';
 const PLAIN_SEMVER = /^\d+\.\d+\.\d+$/;
 const REGISTRY_TIMEOUT_MS = 3000;
 const NPM_PROBE_TIMEOUT_MS = 3000;
@@ -122,28 +129,70 @@ function devCheckoutStep(packageRoot) {
     }
     return { kind: 'command', text: `cd '${packageRoot}' && ${DEV_CHECKOUT_WORK}` };
 }
-function skillCopyStep(source, target, sourceExists) {
-    if (!sourceExists) {
-        // Emitting the cp anyway would hand the agent a step that fails with
-        // ENOENT and reads as a failed upgrade, for a check that found nothing.
-        return {
-            kind: 'action',
-            text: `No bundled skill at ${source}, so the installed copy at ${target} cannot be refreshed from this ` +
-                'package. Re-copy it from the installed hafez package after upgrading — see the README Updating section.',
-        };
+function readIntegration(home) {
+    try {
+        const { skills, blocks, legacy } = checkInstall(home);
+        return { mode: blocks.length > 0 || legacy.length > 0 ? 'always-on' : 'invoke-only', blocks, skills, legacy };
     }
-    if (unquotable(source) || unquotable(target)) {
-        return {
+    catch {
+        return null;
+    }
+}
+const HARNESS_IDS = Object.keys(HARNESSES).join('|');
+/** `onboard --install` writes both skills on every run, so a skill needs no
+ * run of its own when a Block's run is printed. Broken markers make that run
+ * refuse, so they get only the hand fix until it is done. When upgrading,
+ * every installed piece is refreshed: the new version renders new text, and
+ * this check can only compare against the running one's. */
+function integrationSteps(integration, upgrading, env) {
+    if (integration === null) {
+        return [{ kind: 'action', text: 'The installed skills and Block could not be read, so they were not checked.' }];
+    }
+    const broken = integration.blocks.filter(b => b.state === 'broken');
+    if (broken.length > 0) {
+        return broken.map(b => ({
             kind: 'action',
-            text: 'Copy the bundled skill file over the installed one by hand — the paths contain characters ' +
-                `that single-quoting cannot make safe. Source: ${source} — Target: ${target}`,
-        };
+            text: fixBrokenMarkers(b.path, 'hafez upgrade'),
+        }));
+    }
+    const { blocks, skills, legacy } = integration;
+    // The 1.x section goes first: the always-on install writes a Block beside
+    // it, and both would be loaded.
+    const removals = legacy.map(l => ({ kind: 'action', text: removeLegacy(l.path, l.line) }));
+    const unblocked = legacy
+        .filter(l => !blocks.some(b => b.harness === l.harness))
+        .map(l => ({ kind: 'command', text: `hafez onboard --install --mode always-on --harness ${l.harness}` }));
+    // With no Block, the always-on install refreshes the skills too.
+    const rest = blocks.length === 0 && legacy.length > 0 ? [] : blockSteps(integration, upgrading, env);
+    return [...removals, ...unblocked, ...rest];
+}
+function blockSteps({ blocks, skills }, upgrading, env) {
+    const skillDrift = skills.some(s => s.state === 'stale' || s.state === 'hand-edited');
+    const blockDrift = (b) => b.state === 'stale' || (b.state === 'hand-edited' && b.renderChanged);
+    const installed = blocks.length > 0 || skills.some(s => s.state !== 'absent');
+    if (!installed || (!upgrading && !skillDrift && !blocks.some(blockDrift)))
+        return [];
+    if (blocks.length > 0) {
+        // Skills alone: any Block's run writes them, so pick one that run will not
+        // stop on to ask about a hand-edit the status says needs nothing.
+        const skillsOnly = [blocks.find(b => b.state !== 'hand-edited') ?? blocks[0]];
+        const targets = upgrading ? blocks : blocks.filter(blockDrift);
+        return (targets.length > 0 ? targets : skillsOnly).map(b => ({
+            kind: 'command',
+            text: `hafez onboard --install --mode always-on --harness ${b.harness}`,
+        }));
     }
-    return { kind: 'command', text: `mkdir -p '${dirname(target)}' && cp '${source}' '${target}'` };
+    const harness = detectAgent(env);
+    if (isHarness(harness))
+        return [{ kind: 'command', text: `hafez onboard --install --mode invoke-only --harness ${harness}` }];
+    return [{
+            kind: 'action',
+            text: `Run \`hafez onboard --install --mode invoke-only --harness <${HARNESS_IDS}>\`, naming the harness you are running in.`,
+        }];
 }
 /** The action list, in execution order. Every command is built from static
- * constants; the only interpolated values are the regex-validated version and
- * the quoted absolute paths (package root, skill source, skill target). */
+ * constants; the only interpolated values are the regex-validated version,
+ * the quoted package root, and harness ids from the HARNESSES table. */
 function deriveSteps(state, ctx) {
     const steps = [];
     let alternativeInstall = null;
@@ -169,12 +218,7 @@ function deriveSteps(state, ctx) {
             steps.push({ kind: 'action', text: ETARGET_NOTE });
         }
     }
-    // Unconditional when the skill exists: the bundled skill ships INSIDE the
-    // installed package, so on the main upgrade path the bundled copy is equally
-    // stale and any byte-compare reports "current" in exactly the silent-drift
-    // case detection would exist for. Copying an identical file is a no-op.
-    if (state.skill === 'present')
-        steps.push(skillCopyStep(state.skillSource, state.skillTarget, ctx.skillSourceExists));
+    steps.push(...integrationSteps(state.integration, upgrading, ctx.env));
     // A SCHEMA_VERSION bump does not self-heal: the read-only path warns and
     // returns null, so the first post-upgrade query answers *empty* until a
     // write command or an explicit rebuild.
@@ -195,14 +239,9 @@ export async function buildUpgradeState(deps) {
         npmMajor: probeNpmMajor(deps),
         // Published tarballs carry only dist, skill, README.md and LICENSE.
         install: exists(join(deps.packageRoot, 'src')) ? 'dev-checkout' : 'registry',
-        skill: exists(deps.installedSkillPath) ? 'present' : 'absent',
-        skillSource: join(deps.packageRoot, 'skill', 'SKILL.md'),
-        skillTarget: deps.installedSkillPath,
-    };
-    return {
-        ...base,
-        ...deriveSteps(base, { packageRoot: deps.packageRoot, skillSourceExists: exists(base.skillSource) }),
+        integration: readIntegration(deps.home),
     };
+    return { ...base, ...deriveSteps(base, { packageRoot: deps.packageRoot, env: deps.env }) };
 }
 function versionLines(state) {
     const lines = [`Installed version: ${state.current}`];
@@ -223,6 +262,33 @@ function versionLines(state) {
         lines.push('Could not compare: the installed version is not a plain X.Y.Z. Check manually.');
     return lines;
 }
+const BLOCK_STATE = {
+    current: () => 'current',
+    stale: () => 'stale',
+    'hand-edited': b => b.renderChanged
+        ? "hand-edited, and the Block Hafez writes has changed since. `onboard --install` leaves it alone and prints a diff; replace it with --confirm only after the user's yes"
+        : 'hand-edited, over the current Block — nothing to update',
+    broken: () => 'broken markers',
+};
+function integrationLines(integration) {
+    if (integration === null)
+        return ['Skills and Block: could not be read.'];
+    const lines = integration.mode === 'always-on'
+        ? [integration.blocks.length > 0 ? 'Mode: always-on (a Block is installed).' : 'Mode: always-on (legacy: a Hafez 1.x section with no markers).']
+        : [
+            'Mode: invoke-only (no Block in any instructions file Hafez writes); installing a Block is not offered.',
+            "A Block pasted into Cursor's User Rules lives in its Settings and is not checked here.",
+        ];
+    for (const b of integration.blocks)
+        lines.push(`- Block in ${b.path}: ${BLOCK_STATE[b.state](b)}`);
+    for (const l of integration.legacy)
+        lines.push(`- ${legacyLine(l.path, l.line)}, from Hafez 1.x, with no markers`);
+    for (const s of integration.skills) {
+        const lost = s.state === 'hand-edited' ? ' — `onboard --install` replaces it, and the edit is lost' : '';
+        lines.push(`- ${s.path}: ${s.state}${lost}`);
+    }
+    return lines;
+}
 export function renderUpgrade(state) {
     const out = [
         '# Hafez — Upgrade Check',
@@ -240,16 +306,7 @@ export function renderUpgrade(state) {
         out.push('Install source: development checkout (this package has a src/ directory) — upgrade with git, not npm.');
     }
     out.push('');
-    out.push(state.skill === 'present'
-        ? `Skill: installed at ${state.skillTarget}. The skill ships inside the hafez package, so an upgraded package leaves this copy stale — the re-copy step is idempotent, run it either way.`
-        : `Skill: none at ${state.skillTarget} — nothing to re-copy (a non-Claude-Code harness, not drift).`);
-    out.push('');
-    out.push('Integration snippet — compare this against the Hafez section of the');
-    out.push("user's instructions file (Claude Code: ~/.claude/CLAUDE.md; any");
-    out.push('AGENTS.md harness: its global AGENTS.md) and reconcile differences');
-    out.push('with them. Do not rewrite their file unasked.');
-    out.push('');
-    out.push(INTEGRATION_SNIPPET);
+    out.push(...integrationLines(state.integration));
     out.push('');
     out.push('## Steps');
     out.push('');
@@ -279,7 +336,8 @@ function defaultDeps() {
         // The documented escape hatch for private registries and proxied networks.
         registryUrl: process.env.HAFEZ_REGISTRY_URL || DEFAULT_REGISTRY_URL,
         packageRoot: join(here, '..', '..'),
-        installedSkillPath: join(homedir(), '.claude', 'skills', 'hafez', 'SKILL.md'),
+        home: homedir(),
+        env: process.env,
         // Bounded for the same reason the registry fetch is: a global prefix on a
         // network mount or a cold cache can hang npm, and `upgrade` has to stay
         // answerable when the environment is the thing that is broken. A timeout
@@ -295,6 +353,7 @@ const USAGE = 'Usage: hafez upgrade [--json]';
 /** `deps` is the third parameter, unreachable from dispatch (PreVaultRun is
  * `(args, ctx)`) — the tests inject it directly. */
 export async function cmdUpgrade(args, ctx, deps = defaultDeps()) {
+    helpIfAsked(args, USAGE);
     for (const arg of args) {
         if (arg.startsWith('--'))
             throw new UsageError(`Unknown flag ${arg}\n${USAGE}`);

package/dist/closest.d.ts

@@ -0,0 +1,8 @@
+export interface SlugCandidate {
+    slug: string;
+    name: string;
+    description: string | null;
+}
+/** Up to five slugs closest to `miss`, closest first. Ties go to the note
+ * whose name the miss covers most, then to slug order. */
+export declare function closestSlugs(miss: string, candidates: SlugCandidate[]): string[];

package/dist/closest.js

@@ -0,0 +1,65 @@
+// src/closest.ts
+//
+// The closest slugs a `read` miss offers (#91). A miss is usually a slug
+// guessed from a repo folder name, so the words of the miss are matched
+// against each note's name and slug at full weight and its description at
+// half. A note is close when its matched weight covers at least half the
+// words of the miss.
+import { tokenize } from './stopwords.js';
+const LIMIT = 5;
+/** Lowercased words with stopwords dropped and a plural `s` stripped, so
+ * `launchpads` and `launchpad` are one word. */
+function words(text) {
+    return tokenize(text, { stem: true });
+}
+/** At most one insertion, deletion or substitution apart. */
+function oneEditApart(a, b) {
+    if (Math.abs(a.length - b.length) > 1)
+        return false;
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i])
+        i++;
+    if (a.length === b.length)
+        return a.slice(i + 1) === b.slice(i + 1);
+    return a.length > b.length ? a.slice(i + 1) === b.slice(i) : a.slice(i) === b.slice(i + 1);
+}
+/** A word of the miss matches a word of a note when equal, when the miss cut
+ * it short (four letters or more), or when one typo apart (five or more). */
+function matches(missWord, word) {
+    if (missWord === word)
+        return true;
+    if (missWord.length >= 4 && word.startsWith(missWord))
+        return true;
+    return Math.min(missWord.length, word.length) >= 5 && oneEditApart(missWord, word);
+}
+/** Up to five slugs closest to `miss`, closest first. Ties go to the note
+ * whose name the miss covers most, then to slug order. */
+export function closestSlugs(miss, candidates) {
+    const missWords = words(miss);
+    if (missWords.length === 0)
+        return [];
+    const scored = candidates.map(c => {
+        const nameWords = [...new Set([...words(c.name), ...words(c.slug)])];
+        const descriptionWords = words(c.description ?? '');
+        let weight = 0;
+        const covered = new Set();
+        for (const m of missWords) {
+            const hit = nameWords.filter(w => matches(m, w));
+            if (hit.length > 0) {
+                weight += 1;
+                for (const w of hit)
+                    covered.add(w);
+            }
+            else if (descriptionWords.some(w => matches(m, w))) {
+                weight += 0.5;
+            }
+        }
+        const coverage = nameWords.length > 0 ? covered.size / nameWords.length : 0;
+        return { slug: c.slug, score: weight / missWords.length, coverage };
+    });
+    return scored
+        .filter(s => s.score >= 0.5)
+        .sort((a, b) => b.score - a.score || b.coverage - a.coverage || a.slug.localeCompare(b.slug))
+        .slice(0, LIMIT)
+        .map(s => s.slug);
+}

package/dist/contracts.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeSubtype } from './types.js';
+import type { KnowledgeSubtype, UpdateFields } from './types.js';
 export declare const ENTITY_TYPES: readonly ["capture", "entity", "project"];
 export declare const ENTITY_STATUSES: readonly ["active", "paused", "done"];
 export declare const SESSION_LOG_TYPES: readonly ["progress", "decision", "blocker", "research"];
@@ -73,3 +73,19 @@ export declare function unreachableFields(target: DocTarget, fields: Record<stri
 }>;
 /** Human label for a target, used in every gate's error text. */
 export declare function describeTarget(target: DocTarget): string;
+/** Which Footer a document's `read` ends with. Entity and project share one;
+ * a capture's is the promote line, since it is sorted before it is written to. */
+export type FooterForm = 'entity' | 'insight' | 'plan' | 'capture';
+export declare function footerForm(target: DocTarget): FooterForm;
+/** The update fields each Footer names, in the order it names them. Every
+ * other field that contract's update accepts is in WRITE_LINE_OMITS with its
+ * reason; drift check 3 (tests/read-footer.test.ts) holds the two together
+ * against the Op Spec update shape and the kind gate. */
+export declare const WRITE_LINE_FIELDS: {
+    readonly entity: readonly ["session_log", "complete_action", "remove_action", "add_actions", "brief", "current_state", "related", "parent"];
+    readonly insight: readonly ["add_evidence", "add_source", "synthesis", "confidence", "domain", "related"];
+    readonly plan: readonly ["status", "domain", "related"];
+};
+export type WriteLineField = (typeof WRITE_LINE_FIELDS)[keyof typeof WRITE_LINE_FIELDS][number];
+/** Update fields a contract accepts that its Footer leaves out, and why. */
+export declare const WRITE_LINE_OMITS: Record<Exclude<FooterForm, 'capture'>, Partial<Record<keyof UpdateFields, string>>>;

package/dist/contracts.js

@@ -172,3 +172,49 @@ export function describeTarget(target) {
         ? `type '${target.type}'`
         : `knowledge subtype '${target.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE}'`;
 }
+export function footerForm(target) {
+    if (target.kind === 'knowledge')
+        return target.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE;
+    return target.type === 'capture' ? 'capture' : 'entity';
+}
+/** The update fields each Footer names, in the order it names them. Every
+ * other field that contract's update accepts is in WRITE_LINE_OMITS with its
+ * reason; drift check 3 (tests/read-footer.test.ts) holds the two together
+ * against the Op Spec update shape and the kind gate. */
+export const WRITE_LINE_FIELDS = {
+    entity: ['session_log', 'complete_action', 'remove_action', 'add_actions', 'brief', 'current_state', 'related', 'parent'],
+    insight: ['add_evidence', 'add_source', 'synthesis', 'confidence', 'domain', 'related'],
+    plan: ['status', 'domain', 'related'],
+};
+const SET_AT_CREATE = 'set at create, rarely rewritten; `hafez schema update` has it';
+const INSIGHT_ALIAS = 'an alias of synthesis';
+const PLAN_BODY = 'a plan\'s body is Goal, Steps and Dependencies, which no op writes';
+/** Update fields a contract accepts that its Footer leaves out, and why. */
+export const WRITE_LINE_OMITS = {
+    entity: {
+        status: 'a lifecycle change, not a write-back: the `hafez` skill\'s rare ops carry the status line',
+        agent: 'detected from the Harness; the override is never shown',
+        add_action: 'the one-line form of add_actions, written by the same flag',
+        complete_actions: 'the repeated form of complete_action, written by the same flag',
+        remove_actions: 'the repeated form of remove_action, written by the same flag',
+        clear_actions: 'drops lines unseen; the Footer drops one line by its Handle',
+        description: SET_AT_CREATE,
+        resource: SET_AT_CREATE,
+        domain: SET_AT_CREATE,
+        tags: SET_AT_CREATE,
+    },
+    insight: {
+        insight: INSIGHT_ALIAS,
+        description: SET_AT_CREATE,
+        tags: SET_AT_CREATE,
+    },
+    plan: {
+        synthesis: PLAN_BODY,
+        add_evidence: PLAN_BODY,
+        add_source: PLAN_BODY,
+        insight: INSIGHT_ALIAS,
+        confidence: 'an insight matures by confidence; a plan moves by status',
+        description: SET_AT_CREATE,
+        tags: SET_AT_CREATE,
+    },
+};

package/dist/db.d.ts

@@ -1,6 +1,6 @@
 import { type VaultIndexRow } from './knowledge-index.js';
-import type { SearchResult, VaultStats, QueryResult, KnowledgeQueryResult, UnifiedResult, EntityQueryOpts, KnowledgeQueryOpts, UnifiedQueryOpts } from './types.js';
-export declare const SCHEMA_VERSION = "10";
+import type { SearchResult, VaultStats, QueryResult, KnowledgeQueryResult, UnifiedResult, EntityQueryOpts, KnowledgeQueryOpts, UnifiedQueryOpts, SortField } from './types.js';
+export declare const SCHEMA_VERSION = "11";
 interface IndexItem {
     slug: string;
     kind: 'entity' | 'knowledge';
@@ -90,4 +90,17 @@ export declare function createIndex(vaultPath: string): HafezIndex;
 export declare function createIndex(vaultPath: string, opts: {
     readonly: true;
 }): HafezIndex | null;
+/** Opts a branch cannot map into SQL. Declared per branch and rejected on
+ * sight: the CLI has rejected these since 43124ba, but the rule lived only
+ * there, so a library caller got the silent drop the CLI had already closed.
+ * Asserted against the CLI's flag matrix in query-surface.test.ts. */
+export declare const ENTITY_ONLY_OPTS: readonly ["filter", "type", "parent"];
+export declare const KNOWLEDGE_ONLY_OPTS: readonly ["confidence", "subtype"];
+/** Every opt any branch might carry, flattened. Only the unified read uses it,
+ * and only to check: the checks must see an opt the caller's own type forbids,
+ * because an untyped caller can still send it. */
+export type UnmappableCheckOpts = Omit<EntityQueryOpts, 'sort_by'> & Omit<KnowledgeQueryOpts, 'sort_by'> & {
+    kind?: 'entity' | 'knowledge' | 'all';
+    sort_by?: SortField;
+};
 export {};

package/dist/db.js

@@ -7,6 +7,9 @@ import { ensureLocalExclude } from './knowledge-index.js';
 import { WIKI_LINK_RE, documentForFile } from './document.js';
 import { ENTITY_STATUSES, ENTITY_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, DEFAULT_KNOWLEDGE_SUBTYPE } from './contracts.js';
 import { HafezError } from './types.js';
+import { STOPWORDS } from './stopwords.js';
+import { ENTITY_AGE_DAYS_SQL, ENTITY_STALE_SQL } from './stale.js';
+import { localDay } from './dates.js';
 // Bump this when indexing logic changes to force a full rebuild.
 // v5: wiki link harvesting (mention relations), parent link indexing, relation filter on queries.
 // v6: description column on items.
@@ -18,8 +21,10 @@ import { HafezError } from './types.js';
 // v10: re-indexing an externally changed file is delete-then-insert instead of
 //     INSERT OR REPLACE. Indexes written by v9 and earlier may hold ghost FTS
 //     rows (REPLACE never fired the delete trigger) and must be rebuilt, not reused.
+// v11: next_action and the searchable body store action text with its
+//     added-date stamp stripped.
 // Existing instances will fully rebuild the index on first access after upgrade.
-export const SCHEMA_VERSION = '10';
+export const SCHEMA_VERSION = '11';
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS items (
   slug               TEXT PRIMARY KEY,
@@ -79,18 +84,6 @@ CREATE TABLE IF NOT EXISTS meta (
   value TEXT NOT NULL
 );
 `;
-const STOPWORDS = new Set([
-    'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'of',
-    'with', 'by', 'from', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
-    'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could', 'should',
-    'may', 'might', 'can', 'shall', 'not', 'no', 'nor', 'so', 'if', 'then', 'than',
-    'that', 'this', 'these', 'those', 'it', 'its', 'my', 'your', 'his', 'her',
-    'our', 'their', 'what', 'which', 'who', 'whom', 'how', 'when', 'where', 'why',
-    'all', 'each', 'every', 'both', 'few', 'more', 'most', 'some', 'any', 'such',
-    'about', 'into', 'over', 'after', 'before',
-    'work', 'works', 'working', 'use', 'using', 'used', 'get', 'got', 'make', 'made',
-    'need', 'want', 'like', 'just', 'also', 'still', 'already', 'very', 'much',
-]);
 function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
 }
@@ -213,13 +206,8 @@ function queryItemsFn(db, opts) {
     if (opts.filter === 'stale') {
         conditions.push("i.kind = 'entity'");
         conditions.push("i.status = 'active'");
-        conditions.push(`(
-      julianday('now') - julianday(i.last_touched) >
-      CASE
-        WHEN i.staleness_days IS NOT NULL THEN i.staleness_days
-        ELSE 14
-      END
-    )`);
+        conditions.push(`(${ENTITY_STALE_SQL})`);
+        params.today = localDay();
     }
     if (opts.filter === 'capture') {
         conditions.push("i.type = 'capture'");
@@ -256,14 +244,13 @@ function queryItemsFn(db, opts) {
     assertCount(opts.offset, 'offset');
     let sortCol = 'i.last_touched';
     if (opts.sort_by) {
-        const isKnowledgeOnly = KNOWLEDGE_ONLY_SORTS.has(opts.sort_by);
-        const isEntityQuery = opts.kind === 'entity';
-        if (isKnowledgeOnly && isEntityQuery) {
-            sortCol = 'i.last_touched';
+        // Same rule as the unmappable opts, one code path over: a sort field the
+        // branch cannot honour is rejected, not quietly swapped for recency.
+        if (KNOWLEDGE_ONLY_SORTS.has(opts.sort_by) && opts.kind === 'entity') {
+            outOfScope('sort_by', opts.sort_by, 'entity');
         }
-        else if (SORT_COL_MAP[opts.sort_by]) {
+        if (SORT_COL_MAP[opts.sort_by])
             sortCol = SORT_COL_MAP[opts.sort_by];
-        }
     }
     let sortOrder;
     if (opts.sort_order) {
@@ -379,16 +366,11 @@ function getStatsFn(db) {
             by_type[row.type] = row.cnt;
     }
     const stale = db.prepare(`
-    SELECT slug, name, type, CAST(julianday('now') - julianday(last_touched) AS INTEGER) as days_since_touched
-    FROM items
-    WHERE kind = 'entity' AND status = 'active'
-      AND julianday('now') - julianday(last_touched) >
-        CASE
-          WHEN staleness_days IS NOT NULL THEN staleness_days
-          ELSE 14
-        END
+    SELECT slug, name, type, ${ENTITY_AGE_DAYS_SQL} as days_since_touched
+    FROM items i
+    WHERE kind = 'entity' AND status = 'active' AND ${ENTITY_STALE_SQL}
     ORDER BY days_since_touched DESC
-  `).all();
+  `).all({ today: localDay() });
     const no_next_action = db.prepare(`
     SELECT slug, name, type FROM items
     WHERE kind = 'entity' AND status = 'active' AND next_action_count = 0
@@ -627,7 +609,8 @@ export function createIndex(vaultPath, opts) {
             last_reinforced: fm['last-reinforced'] ?? null,
             created: fm.created,
             last_touched: fm['last-touched'] ?? null,
-            body,
+            // Search sees action text, not the added-date stamp (file format only).
+            body: doc.stripNextActionStamps(body),
             file_hash: hash,
             subtype: kind === 'knowledge' ? (fm.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE) : null,
             description: fm.description ?? null,
@@ -878,6 +861,27 @@ function validateEntityFilterOpts(opts) {
     assertEnum(opts?.filter, QUERY_FILTERS, 'filter');
     assertEnum(opts?.type, ENTITY_TYPES, 'type');
 }
+/** Opts a branch cannot map into SQL. Declared per branch and rejected on
+ * sight: the CLI has rejected these since 43124ba, but the rule lived only
+ * there, so a library caller got the silent drop the CLI had already closed.
+ * Asserted against the CLI's flag matrix in query-surface.test.ts. */
+export const ENTITY_ONLY_OPTS = ['filter', 'type', 'parent'];
+export const KNOWLEDGE_ONLY_OPTS = ['confidence', 'subtype'];
+/** The one sentence both scope rejections speak — opts here, sort fields in
+ * queryItemsFn — so a caller sees the same shape whichever one they hit. */
+function outOfScope(label, name, branch) {
+    const belongsTo = branch === 'entity' ? 'knowledge notes only' : 'entities only';
+    throw new HafezError('VALIDATION_FAILED', `Invalid ${label} for a ${branch} query: "${name}" — ${belongsTo}. Use kind: 'all' to query both.`);
+}
+function rejectUnmappableOpts(opts, reject, branch) {
+    if (!opts)
+        return;
+    // Only a *defined* value is a request — an explicit `undefined` (what a
+    // spread of unset CLI flags produces) asks for nothing.
+    for (const name of reject)
+        if (opts[name] !== undefined)
+            outOfScope('opt', name, branch);
+}
 function validateKnowledgeFilterOpts(opts) {
     assertEnum(opts?.confidence, CONFIDENCE_LEVELS, 'confidence');
     assertEnum(opts?.subtype, VALID_SUBTYPES, 'subtype');
@@ -885,7 +889,9 @@ function validateKnowledgeFilterOpts(opts) {
 function queryEntitiesFn(index, opts) {
     index.syncIfStale();
     validateEntityFilterOpts(opts);
-    validateKnowledgeFilterOpts(opts);
+    // Was validateKnowledgeFilterOpts — it checked the *value* of an opt this
+    // branch then discarded, so a valid-looking one returned unfiltered.
+    rejectUnmappableOpts(opts, KNOWLEDGE_ONLY_OPTS, 'entity');
     validateTimeOpts(opts);
     validateListOpts(opts);
     const qopts = { kind: 'entity' };
@@ -908,6 +914,7 @@ function queryRelatedToFn(index, slug, relation) {
 function queryKnowledgeFn(index, opts) {
     index.syncIfStale();
     validateKnowledgeFilterOpts(opts);
+    rejectUnmappableOpts(opts, ENTITY_ONLY_OPTS, 'knowledge');
     validateTimeOpts(opts);
     validateListOpts(opts);
     const qopts = { kind: 'knowledge' };
@@ -919,19 +926,33 @@ function queryKnowledgeFn(index, opts) {
 }
 function queryUnifiedFn(index, opts) {
     index.syncIfStale();
-    assertEnum(opts?.kind, ['entity', 'knowledge', 'all'], 'kind');
-    validateEntityFilterOpts(opts);
-    validateKnowledgeFilterOpts(opts);
-    validateTimeOpts(opts);
-    validateListOpts(opts);
+    // The public type is a union discriminated on `kind`, so an out-of-scope opt
+    // is a compile error. The runtime still has to see every opt to reject it —
+    // an untyped caller (JS, JSON over MCP) reaches here regardless — so widen
+    // once, here, and let the checks below speak for both.
+    const o = opts;
+    assertEnum(o?.kind, ['entity', 'knowledge', 'all'], 'kind');
+    validateEntityFilterOpts(o);
+    validateKnowledgeFilterOpts(o);
+    // Only `kind: 'all'` (or unset) maps both sides. `kind` also narrows this
+    // query to one of them, and a narrowed branch maps no more than the
+    // dedicated one does: the out-of-scope conditions land on columns the
+    // selected kind leaves NULL, so every row is excluded and the caller gets
+    // 0 results with exit 0 — the same wrong answer, one function over.
+    if (o?.kind === 'entity')
+        rejectUnmappableOpts(o, KNOWLEDGE_ONLY_OPTS, 'entity');
+    if (o?.kind === 'knowledge')
+        rejectUnmappableOpts(o, ENTITY_ONLY_OPTS, 'knowledge');
+    validateTimeOpts(o);
+    validateListOpts(o);
     const qopts = {};
-    if (opts?.kind && opts.kind !== 'all')
-        qopts.kind = opts.kind;
+    if (o?.kind && o.kind !== 'all')
+        qopts.kind = o.kind;
     // When kind is 'all' or unset, no kind filter — both entities and knowledge are returned
-    mapEntityFilterOpts(qopts, opts);
-    mapKnowledgeFilterOpts(qopts, opts);
-    mapTimeOpts(qopts, opts);
-    mapListOpts(qopts, opts);
+    mapEntityFilterOpts(qopts, o);
+    mapKnowledgeFilterOpts(qopts, o);
+    mapTimeOpts(qopts, o);
+    mapListOpts(qopts, o);
     const result = index.queryItems(qopts);
     const items = result.items.map(i => {
         if (i.kind === 'entity') {

package/dist/digest.d.ts

@@ -1,11 +1,11 @@
 import { z } from 'zod';
-import type { BatchOperation } from './types.js';
+import { type BatchOperation } from './types.js';
 export declare const DigestInputSchema: z.ZodObject<{
     entities_touched: z.ZodArray<z.ZodString>;
     decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
     narrative: z.ZodString;
     session_date: z.ZodString;
-    agent: z.ZodDefault<z.ZodString>;
+    agent: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type DigestInput = z.infer<typeof DigestInputSchema>;
 /**
@@ -24,6 +24,8 @@ export declare function parseDigestInput(raw: unknown): {
 /**
  * Convert session context into a hafez batch payload.
  * Pure function — no file I/O, no vault access.
- * Unknown slugs in entities_touched are silently omitted (caller should warn).
+ * An unknown slug in entities_touched is a NOT_FOUND naming it (and only the
+ * unknown ones), never a session log that points nowhere. A knowledge slug is
+ * known: the note links it, but a session log is entity-only.
  */
-export declare function digest(input: DigestInput, existingSlugs: Set<string>, now?: Date): BatchOperation[];
+export declare function digest(input: DigestInput, entitySlugs: Set<string>, knowledgeSlugs?: Set<string>): BatchOperation[];