hafez 2.1.0 → 2.2.0

package/dist/surfaces/items.d.ts

@@ -9,6 +9,11 @@ import type { Mode } from '../cli/install.js';
 export type SurfaceId = 'block' | 'hafezSkillDescription' | 'hafezSkillBody' | 'hafezSaveDescription' | 'hafezSaveBody' | 'read' | 'readHeader' | 'readFooter' | 'readMiss' | 'updateSuccess' | 'updateMisuse' | 'createKnowledge' | 'digestError' | 'batchMisuse' | 'mechanised' | 'schema' | 'onboard';
 /** Places another Item inside this one's text, counted against the same Surface. */
 export type Place = (id: string) => string;
+/** What a static Surface is composed for. `vaultRepo`: the Block for a cloud
+ * container, whose vault is that GitHub repo (#160). */
+export interface SurfaceCtx {
+    vaultRepo?: string;
+}
 export interface Item {
     /** The Item's row text in the owner table. */
     label: string;
@@ -21,7 +26,7 @@ export interface Item {
     evidence: string;
     /** Static text. A function form may place nested Items, and may give the
      * fallback a shorter form than the Owner. */
-    text?: string | ((place: Place, at: 'owner' | 'fallback') => string);
+    text?: string | ((place: Place, at: 'owner' | 'fallback', ctx: SurfaceCtx) => string);
     /** What the binary computes: for Items owned by command output, and for a
      * static Item a binary Surface places filled in (the create line in the
      * `read` miss). */
@@ -94,6 +99,19 @@ declare function renderUpdateSummary({ slug, fields, result }: {
 /** The suffix a Stale open line carries on `read`: its age, or that it is
  * undated. A fresh line carries none. */
 declare function renderStaleMarker({ stale, age_days }: ActionAge): string;
+/** The `read` header line naming the sessions that touched an entity, with
+ * the look back from it. None: no line. */
+declare function renderSessionsLine({ slug, count, latest }: {
+    slug: string;
+    count: number;
+    latest: string | null;
+}): string;
+/** The `read` header line naming an entity's archived log entries, with the
+ * command that reads them. No archive: no line. */
+declare function renderArchivePointer({ slug, entries }: {
+    slug: string;
+    entries: number;
+}): string;
 /** The line after an update's success while Stale lines remain on the entity. */
 declare function renderStaleReminder({ handles }: {
     handles: string[];
@@ -129,6 +147,15 @@ declare function renderTeachingLines({ harness, mode, line2Only }: {
     mode: Mode;
     line2Only?: boolean;
 }): string;
+/** A GitHub `<owner>/<repo>`, as one shell word safe to print in a command
+ * and to name a directory by: not `.` or `..`, not a clone URL's `.git`. */
+export declare const isVaultRepo: (value: string) => boolean;
+/** `onboard --cloud`: the cloud environment's setup script. It cannot clone
+ * (it runs without GitHub credentials) and no step may fail session start: a
+ * failed install exits 0, leaving a session without Hafez rather than none. */
+declare function renderCloudSetup({ vaultRepo }: {
+    vaultRepo: string;
+}): string;
 export declare const ITEMS: {
     loadTriggers: {
         label: string;
@@ -159,6 +186,20 @@ export declare const ITEMS: {
             description: string | null;
         }) => string;
     };
+    sessionsLine: {
+        label: string;
+        owner: "readHeader";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderSessionsLine;
+    };
+    archivePointer: {
+        label: string;
+        owner: "readHeader";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderArchivePointer;
+    };
     writeTriggers: {
         label: string;
         owner: "block";
@@ -354,6 +395,20 @@ export declare const ITEMS: {
         evidence: string;
         render: typeof renderHarnessPermissions;
     };
+    cloudVault: {
+        label: string;
+        owner: "block";
+        invokeOnly: string;
+        evidence: string;
+        text: (_place: Place, _at: "owner" | "fallback", { vaultRepo }: SurfaceCtx) => string;
+    };
+    cloudSetup: {
+        label: string;
+        owner: "onboard";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderCloudSetup;
+    };
     teachingLines: {
         label: string;
         owner: "onboard";

package/dist/surfaces/items.js

@@ -162,6 +162,20 @@ function renderStaleMarker({ stale, age_days }) {
         return '';
     return age_days === null ? ' · stale, undated' : ` · stale ${age_days}d`;
 }
+/** The `read` header line naming the sessions that touched an entity, with
+ * the look back from it. None: no line. */
+function renderSessionsLine({ slug, count, latest }) {
+    if (count === 0)
+        return '';
+    return `sessions: ${count}${latest ? ` · latest ${latest}` : ''} · hafez query --kind session --related-to ${slug}`;
+}
+/** The `read` header line naming an entity's archived log entries, with the
+ * command that reads them. No archive: no line. */
+function renderArchivePointer({ slug, entries }) {
+    if (entries === 0)
+        return '';
+    return `archive: ${entries} older log ${entries === 1 ? 'entry' : 'entries'} · hafez read ${slug} --archive`;
+}
 /** The line after an update's success while Stale lines remain on the entity. */
 function renderStaleReminder({ handles }) {
     const n = handles.length;
@@ -221,6 +235,38 @@ function renderTeachingLines({ harness, mode, line2Only = false }) {
         '4. If a hafez command ever asks for permission, setup is unfinished: run `hafez onboard` again.',
     ].join('\n');
 }
+/** A GitHub `<owner>/<repo>`, as one shell word safe to print in a command
+ * and to name a directory by: not `.` or `..`, not a clone URL's `.git`. */
+export const isVaultRepo = (value) => /^[A-Za-z0-9-]+\/[\w.-]+$/.test(value) && !/\/\.\.?$/.test(value) && !value.endsWith('.git');
+/** Where a cloud container clones a repo attached to the session. */
+const CLOUD_HOME = '/home/user';
+const repoName = (vaultRepo) => vaultRepo.slice(vaultRepo.indexOf('/') + 1);
+/** The Block's self-heal rule in a cloud container: a session started without
+ * the vault attached attaches, clones and registers it (verified, #160). */
+function renderCloudVault(vaultRepo) {
+    const path = `${CLOUD_HOME}/${repoName(vaultRepo)}`;
+    return `If \`hafez init\` shows no registered vault: attach \`${vaultRepo}\` to this session (add_repo, push access), clone it to ${path}, run \`hafez init --register ${path}\`, then continue. Never create a throwaway vault.`;
+}
+/** `onboard --cloud`: the cloud environment's setup script. It cannot clone
+ * (it runs without GitHub credentials) and no step may fail session start: a
+ * failed install exits 0, leaving a session without Hafez rather than none. */
+function renderCloudSetup({ vaultRepo }) {
+    return [
+        `Each Claude Code cloud session is a fresh container: no \`hafez\`, no vault, no Block. Paste this into the cloud environment's Setup script; the Trusted network policy is enough.`,
+        '',
+        fence([
+            '#!/bin/bash',
+            'npm install -g hafez --allow-scripts=better-sqlite3 || exit 0',
+            `VAULT=${CLOUD_HOME}/${repoName(vaultRepo)}`,
+            'if [ -d "$VAULT/.git" ]; then',
+            '  hafez init --register "$VAULT"',
+            'fi',
+            `hafez onboard --install --mode always-on --harness claude-code --vault-repo ${vaultRepo} || true`,
+        ].join('\n')),
+        '',
+        `Attach ${vaultRepo} when you start a session, with push access, and the script registers it. The script cannot clone it: it runs without GitHub credentials. A session started without it attached is told by the Block to attach, clone and register it.`,
+    ].join('\n');
+}
 const BATCH_EXAMPLE_OP = '{"op":"create","kind":"entity","name":"Token Rotation","fields":{"type":"entity"}}';
 export const ITEMS = {
     loadTriggers: {
@@ -259,13 +305,28 @@ export const ITEMS = {
          * in brackets when it has one. */
         render: ({ slug, description }) => description ? `${slug} (${description})` : slug,
     },
+    sessionsLine: {
+        label: 'Sessions line: the look back from an entity',
+        owner: 'readHeader',
+        invokeOnly: 'same',
+        evidence: '#35',
+        render: renderSessionsLine,
+    },
+    archivePointer: {
+        label: 'Archive pointer',
+        owner: 'readHeader',
+        invokeOnly: 'same',
+        evidence: '#34',
+        render: renderArchivePointer,
+    },
     writeTriggers: {
-        label: 'Write triggers: work landed, insight, weighing, "note this"',
+        label: 'Write triggers: work landed, decision made, insight, weighing, "note this"',
         owner: 'block',
         invokeOnly: 'absent',
-        evidence: 'M11, M2, never-ask decision #42',
+        evidence: 'M11, M2, never-ask decision #42, decision-record miss #159',
         text: place => [
-            '- Work landed (a commit, a merged PR, CI green): update the entity you read. The end of its `read` output shows the command.',
+            '- Work landed (a commit, a merged PR, CI green): update the entity that owns the work. That is the entity you read, unless the work belongs to another: read that one first. The end of its `read` output shows the command.',
+            '- A decision was made: if the repo keeps its own decisions record, write it there now and give Hafez one line that points at it (`hafez update <slug> --log "decision: <one line>, see decisions.md"`). Otherwise it goes in the save\'s `decisions`.',
             `- An insight emerged that is useful beyond this repo: create a knowledge note. ${place('knowledgeBoundary')}`,
             '- The user says "note this" or "record that": write it.',
             `- You are weighing whether something is worth writing: write it, as knowledge with \`--confidence ${CONFIDENCE_LEVELS[0]}\`.`,
@@ -438,9 +499,11 @@ export const ITEMS = {
         evidence: 'help decision #49',
         text: fence([
             `hafez query --filter ${oneOf([...ENTITY_STATUSES, 'stale', 'capture'])}`,
-            'hafez search "<terms>" --kind <entity|knowledge>',
+            'hafez search "<terms>" --kind <entity|knowledge|session|all>',
+            'hafez query --kind session --related-to <slug>',
             'hafez stats',
-        ].join('\n')),
+        ].join('\n'))
+            + '\n\n`search` and `query` reach entities and knowledge notes; `--kind all` adds the session notes, `--kind session` lists them alone, newest first. `hafez read <slug> --archive` prints an entity\'s archived log entries.',
     },
     rareOps: {
         label: 'Rare ops: promote, link, unlink, status, delete, validate',
@@ -517,6 +580,22 @@ export const ITEMS = {
         evidence: 'never-ask decision #42; onboard decision #58',
         render: renderHarnessPermissions,
     },
+    cloudVault: {
+        label: 'Cloud session: no vault registered, attach the vault repo, clone, register',
+        owner: 'block',
+        invokeOnly: 'absent',
+        evidence: '#160, verified 2026-10-16',
+        // Placed only in a Block composed for a cloud container, whose begin
+        // marker names the repo (renderBlock).
+        text: (_place, _at, { vaultRepo = '<owner>/<repo>' }) => renderCloudVault(vaultRepo),
+    },
+    cloudSetup: {
+        label: 'The cloud environment\'s setup script',
+        owner: 'onboard',
+        invokeOnly: 'not offered',
+        evidence: '#160, verified 2026-10-16',
+        render: renderCloudSetup,
+    },
     teachingLines: {
         label: 'The four teaching lines (to the user, not the agent)',
         owner: 'onboard',

package/dist/surfaces/surfaces.d.ts

@@ -1,16 +1,19 @@
-import { type FolderMatch, type Item, type ItemId, type SurfaceId } from './items.js';
+import { type FolderMatch, type Item, type ItemId, type SurfaceCtx, type SurfaceId } from './items.js';
 export interface Surface<Id extends string = ItemId> {
     /** How the owner table names this Surface. */
     label: string;
     /** Static Surfaces only: the text, built by placing Items. */
-    compose?: (place: (id: Id) => string) => string;
+    compose?: (place: (id: Id) => string, ctx: SurfaceCtx) => string;
 }
 export declare const SURFACES: Record<SurfaceId, Surface>;
 export declare const contentHash: (text: string) => string;
 /** An Item's text as a binary Surface places it at run time, in the form its
  * role there (Owner or fallback) calls for. */
 export declare function placeIn(surfaceId: SurfaceId, id: ItemId): string;
-export declare function renderBlock(): string;
+/** The Block; with `vaultRepo`, the Block for a cloud container whose vault
+ * is that repo. Its begin marker names the repo, so a check reads it from
+ * there and never from the Block's wording, which a release may change. */
+export declare function renderBlock(vaultRepo?: string): string;
 /** `onboard --block`, what the SessionStart hook prints: the Block, then the
  * read line for each entity matching the folder. */
 export declare function renderBlockHook(matches: FolderMatch[]): string;
@@ -26,7 +29,7 @@ export declare function renderOwnerTable(): string;
 /** Replace the marked owner-table region of `doc` with a fresh render. */
 export declare function spliceOwnerTable(doc: string): string;
 /** Every problem with the Item table: an Item with no Owner or no evidence
- * pointer, an Item its Owner or static fallback never places, or one placed more than once in a
- * Surface or in a Surface that is neither its Owner nor its declared fallback.
+ * pointer, an Item its Owner or static fallback never places in any context, or one placed more
+ * than once in a Surface or in a Surface that is neither its Owner nor its declared fallback.
  * Placement is checked for static Surfaces only; binary ones place at run time. */
 export declare function itemProblems(items: Record<string, Item>, surfaces: Record<string, Surface<string>>): string[];

package/dist/surfaces/surfaces.js

@@ -13,11 +13,12 @@ import { ITEMS } from './items.js';
 export const SURFACES = {
     block: {
         label: 'Block',
-        compose: place => [
+        compose: (place, { vaultRepo }) => [
             '## Hafez',
             '',
             'Hafez is this user\'s vault: what they are working on (entities) and what they have learned (knowledge). You reach it only through the `hafez` command.',
             '',
+            ...(vaultRepo === undefined ? [] : [`**Cloud session.** ${place('cloudVault')}`, '']),
             `**Load.** ${place('loadTriggers')}`,
             '',
             '**Write as it happens.** Each of these is due the moment it occurs:',
@@ -96,11 +97,14 @@ export const SURFACES = {
     schema: { label: '`schema`' },
     onboard: { label: '`onboard`' },
 };
+/** Every context a static Surface is composed in: the default, and the
+ * Block for a cloud container. */
+const CONTEXTS = [{}, { vaultRepo: '<owner>/<repo>' }];
 export const contentHash = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12);
 /** Compose a static Surface, placing each Item's text in the form its role
  * (Owner or fallback) calls for. `onPlace` sees every placement, nested ones
  * included. */
-function composeWith(items, surfaceId, surface, onPlace = () => { }) {
+function composeWith(items, surfaceId, surface, ctx = {}, onPlace = () => { }) {
     const place = (id) => {
         onPlace(id);
         const item = items[id];
@@ -108,16 +112,16 @@ function composeWith(items, surfaceId, surface, onPlace = () => { }) {
             throw new Error(`${surfaceId} places unknown Item ${id}`);
         const text = item.text;
         if (typeof text === 'function')
-            return text(place, item.owner === surfaceId ? 'owner' : 'fallback');
+            return text(place, item.owner === surfaceId ? 'owner' : 'fallback', ctx);
         if (text === undefined)
             throw new Error(`${surfaceId} places ${id}, which has no text`);
         return text;
     };
     if (!surface.compose)
         throw new Error(`${surfaceId} is not a static surface`);
-    return surface.compose(place);
+    return surface.compose(place, ctx);
 }
-const compose = (id) => composeWith(ITEMS, id, SURFACES[id]);
+const compose = (id, ctx = {}) => composeWith(ITEMS, id, SURFACES[id], ctx);
 /** An Item's text as a binary Surface places it at run time, in the form its
  * role there (Owner or fallback) calls for. */
 export function placeIn(surfaceId, id) {
@@ -147,9 +151,13 @@ function skillFile(name, description, body) {
     const text = compose(body);
     return `---\nname: ${name}\ndescription: >\n${fold(compose(description))}\nhash: ${contentHash(text)}\n---\n${text}`;
 }
-export function renderBlock() {
-    const inner = compose('block');
-    return `<!-- hafez:begin ${contentHash(inner)} -->\n${inner}<!-- hafez:end -->\n`;
+/** The Block; with `vaultRepo`, the Block for a cloud container whose vault
+ * is that repo. Its begin marker names the repo, so a check reads it from
+ * there and never from the Block's wording, which a release may change. */
+export function renderBlock(vaultRepo) {
+    const inner = compose('block', { vaultRepo });
+    const repo = vaultRepo === undefined ? '' : ` vault-repo=${vaultRepo}`;
+    return `<!-- hafez:begin ${contentHash(inner)}${repo} -->\n${inner}<!-- hafez:end -->\n`;
 }
 /** `onboard --block`, what the SessionStart hook prints: the Block, then the
  * read line for each entity matching the folder. */
@@ -185,21 +193,28 @@ export function spliceOwnerTable(doc) {
 }
 // --- Drift check 2: the typed Item table ---
 /** Every problem with the Item table: an Item with no Owner or no evidence
- * pointer, an Item its Owner or static fallback never places, or one placed more than once in a
- * Surface or in a Surface that is neither its Owner nor its declared fallback.
+ * pointer, an Item its Owner or static fallback never places in any context, or one placed more
+ * than once in a Surface or in a Surface that is neither its Owner nor its declared fallback.
  * Placement is checked for static Surfaces only; binary ones place at run time. */
 export function itemProblems(items, surfaces) {
     const problems = [];
+    // Per Surface, the most times each Item is placed in one of its contexts.
     const placed = {};
     for (const [sid, surface] of Object.entries(surfaces)) {
         if (!surface.compose)
             continue;
-        const counts = (placed[sid] = {});
-        try {
-            composeWith(items, sid, surface, id => { counts[id] = (counts[id] ?? 0) + 1; });
-        }
-        catch (err) {
-            problems.push(err.message);
+        const most = (placed[sid] = {});
+        for (const ctx of CONTEXTS) {
+            const counts = {};
+            try {
+                composeWith(items, sid, surface, ctx, id => { counts[id] = (counts[id] ?? 0) + 1; });
+            }
+            catch (err) {
+                if (!problems.includes(err.message))
+                    problems.push(err.message);
+            }
+            for (const [id, n] of Object.entries(counts))
+                most[id] = Math.max(most[id] ?? 0, n);
         }
     }
     for (const [id, item] of Object.entries(items)) {

package/dist/types.d.ts

@@ -13,8 +13,14 @@ export type PlanStatus = typeof PLAN_STATUSES[number];
  * lives on knowledge notes only. Asking for one on the entity branch is a
  * validation error, not a silent fall back to recency, so the entity opts
  * type declares only what that branch can actually sort by. */
-export type SortField = 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
-export type EntitySortField = Exclude<SortField, 'last_reinforced' | 'reinforcement_count'>;
+export type SortField = 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count' | 'session_date';
+export type EntitySortField = Exclude<SortField, 'last_reinforced' | 'reinforcement_count' | 'session_date'>;
+export type KnowledgeSortField = Exclude<SortField, 'session_date'>;
+/** A session note carries only its dates and its name. */
+export type SessionSortField = 'session_date' | 'created' | 'name';
+/** What `search` reaches. Unset is the working set, entity + knowledge;
+ * `all` is literal, sessions included. */
+export type SearchKind = 'entity' | 'knowledge' | 'session' | 'all';
 export interface EntityQueryOpts {
     filter?: QueryFilter;
     type?: EntityType;
@@ -39,14 +45,28 @@ export interface KnowledgeQueryOpts {
     createdSince?: string;
     createdBefore?: string;
     tags?: string[];
-    sort_by?: SortField;
+    sort_by?: KnowledgeSortField;
+    sort_order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+/** Sessions carry no status, domain or tags: the time window (`since`/`before`
+ * against `session-date`), sort and paging are all a session query takes. */
+export interface SessionQueryOpts {
+    since?: string;
+    before?: string;
+    createdSince?: string;
+    createdBefore?: string;
+    sort_by?: SessionSortField;
     sort_order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
 }
 /** `kind: 'all'` (or unset): reaches both sides, so it takes opts from both
  * and can honour every sort field. Status filters narrow the entity side only
- * — knowledge notes carry no status and are never excluded by one. */
+ * — knowledge notes carry no status and are never excluded by one. Unset
+ * is the working set, entity + knowledge; `all` is literal and reaches the
+ * sessions too. */
 export interface AllQueryOpts extends Omit<EntityQueryOpts, 'sort_by'> {
     kind?: 'all';
     confidence?: ConfidenceLevel;
@@ -63,6 +83,8 @@ export type UnifiedQueryOpts = AllQueryOpts | (EntityQueryOpts & {
     kind: 'entity';
 }) | (KnowledgeQueryOpts & {
     kind: 'knowledge';
+}) | (SessionQueryOpts & {
+    kind: 'session';
 });
 export interface EntityFrontmatter {
     name: string;
@@ -114,11 +136,8 @@ export type ParsedVaultFile = {
     frontmatter: SessionFrontmatter;
     body: string;
 };
-/** What read() returns: the indexed arms of ParsedVaultFile (a session slug is
- * never resolvable through read()), so consumers narrow on `kind`. */
-export type ParsedFile = Extract<ParsedVaultFile, {
-    kind: 'entity' | 'knowledge';
-}>;
+/** What read() returns: any vault file, so consumers narrow on `kind`. */
+export type ParsedFile = ParsedVaultFile;
 export interface SessionLogEntry {
     type: SessionLogType;
     summary: string;
@@ -221,10 +240,19 @@ export interface KnowledgeQueryResult {
     last_reinforced: string | null;
     last_touched: string | null;
 }
+export interface SessionQueryResult {
+    slug: string;
+    name: string;
+    session_date: string;
+    created: string;
+    related: string[];
+}
 export type UnifiedResult = (QueryResult & {
     kind: 'entity';
 }) | (KnowledgeQueryResult & {
     kind: 'knowledge';
+}) | (SessionQueryResult & {
+    kind: 'session';
 });
 export interface ValidationIssue {
     slug: string;
@@ -237,10 +265,11 @@ export interface ValidationReport {
     missing_fields: ValidationIssue[];
     total_entities: number;
     total_knowledge: number;
+    total_sessions: number;
 }
 export interface SearchResult {
     slug: string;
-    kind: 'entity' | 'knowledge';
+    kind: 'entity' | 'knowledge' | 'session';
     name: string;
     snippet: string;
     type?: EntityType;
@@ -275,7 +304,7 @@ export interface VaultStats {
 }
 export interface ChangelogEntry {
     slug: string;
-    kind: 'entity' | 'knowledge';
+    kind: 'entity' | 'knowledge' | 'session';
     operation: 'created' | 'updated' | 'deleted';
     timestamp: string;
     commit_message: string;
@@ -355,7 +384,7 @@ export interface BatchValidationReport {
     valid: boolean;
     operations: BatchOpValidation[];
 }
-export type HafezErrorCode = 'NOT_FOUND' | 'SLUG_EXISTS' | 'VALIDATION_FAILED' | 'GIT_PUSH_FAILED' | 'GIT_COMMIT_FAILED' | 'VAULT_LOCKED';
+export type HafezErrorCode = 'NOT_FOUND' | 'SLUG_EXISTS' | 'VALIDATION_FAILED' | 'GIT_PUSH_FAILED' | 'GIT_COMMIT_FAILED' | 'GIT_READ_FAILED' | 'VAULT_LOCKED';
 export declare class HafezError extends Error {
     code: HafezErrorCode;
     details?: string[] | undefined;
@@ -370,10 +399,11 @@ export interface GitConfig {
  * production (src/git.ts); tests may inject an in-memory adapter.
  */
 export interface Journal {
-    /** Persist one logical change: stage written+deleted paths (vault-relative)
-     * and commit under message. Must clean up its own partial state (e.g.
-     * staged files) before rethrowing on a commit-stage failure; a push-stage
-     * failure surfaces as GIT_PUSH_FAILED with the commit kept. */
+    /** Persist one logical change: stage written+deleted paths (vault-relative,
+     * '/'-separated on every platform) and commit under message. Must clean up
+     * its own partial state (e.g. staged files) before rethrowing on a
+     * commit-stage failure; a push-stage failure surfaces as GIT_PUSH_FAILED
+     * with the commit kept. */
     commit(written: string[], deleted: string[], message: string): Promise<void>;
     /** Bidirectional sync with the remote, if any. */
     sync(): Promise<{
@@ -381,9 +411,11 @@ export interface Journal {
         pushed: boolean;
         remote: boolean;
     }>;
-    /** History-derived changelog for entities/ and knowledge/ since a date. */
+    /** History-derived changelog for the indexed dirs since a date. Empty when
+     * the repo has no commits; any other git failure throws `GIT_READ_FAILED`. */
     changelog(since: string): Promise<ChangelogEntry[]>;
-    /** Newest history timestamp per vault file (modified = any change, added = creation). */
+    /** Newest history timestamp per vault file (modified = any change, added = creation).
+     * Empty when the repo has no commits; any other git failure throws `GIT_READ_FAILED`. */
     fileTimes(mode: 'modified' | 'added'): Promise<Map<string, string>>;
 }
 export interface HafezConfig {
@@ -432,9 +464,21 @@ export interface Hafez {
         items: KnowledgeQueryResult[];
         total: number;
     }>;
+    query_sessions(opts?: SessionQueryOpts): Promise<{
+        items: SessionQueryResult[];
+        total: number;
+    }>;
+    /** An entity's archived log entries (`entities/archive/<slug>-log.md`), as
+     * written; null when it has none. Read from disk, never indexed: the
+     * archive is reached from its entity on purpose, never found by search. */
+    archive(slug: string): Promise<string | null>;
     validate(): Promise<ValidationReport>;
-    search(query: string, kind?: 'entity' | 'knowledge' | 'all'): Promise<SearchResult[]>;
+    search(query: string, kind?: SearchKind): Promise<SearchResult[]>;
     rebuildIndex(): Promise<void>;
     stats(): Promise<VaultStats>;
     changelog(since: string): Promise<ChangelogEntry[]>;
+    /** Release the SQLite index handle. Idempotent; the next call that needs
+     * the index reopens it. Call before deleting the vault: Windows cannot
+     * remove a directory holding an open file. */
+    close(): void;
 }