hafez 2.1.0 → 2.3.0

package/dist/cli/commands.js

@@ -7,49 +7,69 @@ import { BatchOperationSchema, normalizeAliases, opErrorLine, batchInvalidHeader
 import { formatBatchError } from './batch-errors.js';
 import { parseDigestInput, digest } from '../digest.js';
 import { detectAgent } from '../harness.js';
-import { getActionItems } from '../document.js';
 import { resemblances } from '../near-match.js';
-import { actionAge, agedActions, staleHandles, stalenessDaysOf } from '../stale.js';
+import { actionAge, staleHandles, stalenessDaysOf } from '../stale.js';
 import { slugify } from '../vault.js';
-import { ITEMS, footerOp } from '../surfaces/items.js';
+import { GRAPH_LAYERS } from '../contracts.js';
+import { ITEMS } from '../surfaces/items.js';
+import { footerFor, pointersFor, readJsonOf } from '../read-json.js';
 import { placeIn } from '../surfaces/surfaces.js';
-import { formatEntityHeader, formatKnowledgeHeader, formatQueryTable, formatKnowledgeTable, formatSearchResults, formatValidation, formatStats, formatChangelog } from './format.js';
+import { formatEntityHeader, formatKnowledgeHeader, formatSessionHeader, formatQueryTable, formatKnowledgeTable, formatSessionTable, formatSearchResults, formatValidation, formatHealth, formatStats, formatChangelog } from './format.js';
 function jsonOut(data) {
     return JSON.stringify(data, null, 2);
 }
-const READ_USAGE = 'Usage: hafez read <slug> [--depth frontmatter|summary|full]';
-const READ_FLAGS = { depth: 'string' };
+const READ_USAGE = 'Usage: hafez read <slug> [--depth frontmatter|summary|full] [--archive]';
+const READ_FLAGS = { depth: 'string', archive: 'boolean' };
 export async function cmdRead(os, args, opts = {}) {
     const { flags, positionals } = parseArgs(args, READ_FLAGS, READ_USAGE);
     const slug = positionals[0];
     if (!slug)
         throw new UsageError(READ_USAGE);
     const depth = (str(flags.depth) ?? 'summary');
-    const result = await os.read(slug, depth).catch(err => {
-        if (!(err instanceof HafezError) || err.code !== 'NOT_FOUND')
-            throw err;
-        const closest = err.details ?? [];
-        throw opts.json
-            ? new RenderedError('NOT_FOUND', jsonOut({ slug, closest }), 'stdout')
-            : new RenderedError('NOT_FOUND', ITEMS.slugMissRecovery.render({ slug, closest }), 'stderr');
-    });
-    const footer = await footerFor(os, slug, result, depth);
-    if (opts.json) {
-        const writes = footerOp(footer);
-        // A frontmatter-depth read carries no body, so it has no actions to list.
-        if (result.kind !== 'entity' || depth === 'frontmatter')
-            return jsonOut({ ...result, writes });
-        return jsonOut({ ...result, actions: agedActions(result.body, result.frontmatter), writes });
+    const result = await os.read(slug, depth).catch(err => { throw readMiss(err, slug, opts); });
+    if (flags.archive) {
+        // The archive is an entity's: reached from it on purpose (#34).
+        if (result.kind !== 'entity')
+            throw new UsageError(`--archive reads an entity's archived log entries; '${slug}' is a ${result.kind === 'session' ? 'session note' : 'knowledge note'}\n${READ_USAGE}`);
+        const archive = await os.archive(slug);
+        if (opts.json)
+            return jsonOut({ slug, archive });
+        return archive ?? `no archive for ${slug}`;
     }
+    if (opts.json)
+        return jsonOut(await readJsonOf(os, slug, depth, result));
+    // A session note is read, never written: no Footer (#35).
+    if (result.kind === 'session')
+        return formatSessionHeader(result.frontmatter, result.body);
+    // The Footer and the pointers are the same at every depth: they read the
+    // whole file, not the body this depth shows.
+    const whole = depth === 'full' ? result : await os.read(slug, 'full');
+    const footer = footerFor(slug, whole);
+    const pointers = whole.kind === 'entity' ? await pointersFor(os, slug, whole.body) : null;
     const fm = result.frontmatter;
     const days = stalenessDaysOf(fm);
     const staleMark = (added) => ITEMS.staleMarker.render(actionAge(added, days));
     const text = result.kind === 'entity'
-        ? formatEntityHeader(fm, ITEMS.handles.render(result.body, staleMark), await parentLine(os, fm.parent))
+        ? formatEntityHeader(fm, ITEMS.handles.render(result.body, staleMark), await parentLine(os, fm.parent), [
+            ITEMS.childrenBlock.render({ slug, children: pointers.children }),
+            ...pointers.workstreams.map(w => ITEMS.workstreamLine.render(w)),
+            ITEMS.sessionsLine.render({ slug, ...pointers.sessions }),
+            ITEMS.archivePointer.render({ slug, entries: pointers.archive_entries }),
+        ].filter(Boolean))
         : formatKnowledgeHeader(fm, result.body);
     // Trailing newlines only: the Footer brings its own blank line.
     return `${text.replace(/\n+$/, '')}\n${ITEMS.writeLine.render(footer)}`;
 }
+/** A `read` miss as the CLI renders it: the closest slugs on stderr (`--json`:
+ * `{slug, closest}` on stdout), exit 1. Any other error passes through. */
+function readMiss(err, slug, opts) {
+    if (!(err instanceof HafezError) || err.code !== 'NOT_FOUND')
+        return err;
+    const closest = err.details ?? [];
+    return opts.json
+        ? new RenderedError('NOT_FOUND', jsonOut({ slug, closest }), 'stdout')
+        : new RenderedError('NOT_FOUND', ITEMS.slugMissRecovery.render({ slug, closest }), 'stderr');
+}
 /** The `parent:` line's value: the slug with the parent's description. The
  * one thing `read` takes from another file; a parent that cannot be read
  * (a broken slug) is named by its slug alone. */
@@ -73,25 +93,16 @@ async function staleAfterWrite(os, slug) {
         return [];
     }
 }
-/** The Footer for a file `read` returned at `depth`. The Footer is the same
- * at every depth, so its Handle comes from the whole file, not from the body
- * this depth shows. */
-async function footerFor(os, slug, result, depth) {
-    return { slug, agent: detectAgent(), ...(result.kind === 'entity'
-            ? {
-                target: { kind: 'entity', type: result.frontmatter.type },
-                handle: getActionItems(depth === 'full' ? result.body : (await os.read(slug, 'full')).body).find(a => a.handle)?.handle,
-            }
-            : { target: { kind: 'knowledge', subtype: result.frontmatter.subtype } }) };
-}
-const QUERY_USAGE = `Usage: hafez query [--kind entity|knowledge|all] [--filter ...] [--type t] [--parent slug] [--related-to slug] [--domain d] [--confidence c] [--subtype s] [--tag t] [--since d] [--before d] [--created-since d] [--created-before d] [--sort-by f] [--sort-order asc|desc] [--limit n] [--offset n]
+const QUERY_USAGE = `Usage: hafez query [--kind entity|knowledge|session|all] [--filter ...] [--type t] [--parent slug] [--related-to slug] [--domain d] [--confidence c] [--subtype s] [--tag t] [--since d] [--before d] [--created-since d] [--created-before d] [--sort-by f] [--sort-order asc|desc] [--limit n] [--offset n]
 
-  --filter active|paused|done matches entity status; knowledge notes carry no
-  status, so under --kind all they are always included alongside the matching
-  entities. --filter stale|capture are entity-only views and return no
-  knowledge. --filter/--type/--parent are rejected with --kind knowledge, and
-  --confidence/--subtype are rejected with --kind entity, rather than being
-  silently dropped. --related-to takes no other query flags.`;
+  --filter active|paused|done matches entity status; knowledge and session
+  notes carry no status, so under --kind all they are always included
+  alongside the matching entities. --filter stale|capture are entity-only
+  views and return no knowledge. --filter/--type/--parent are rejected with
+  --kind knowledge, and --confidence/--subtype are rejected with --kind
+  entity, rather than being silently dropped. --kind session lists session
+  notes newest first and takes the time window, sort and paging flags only.
+  --related-to takes --kind to narrow to one kind and no other query flag.`;
 const QUERY_FLAGS = {
     kind: 'string', filter: 'string', type: 'string', parent: 'string', 'related-to': 'string',
     domain: 'string', confidence: 'string', subtype: 'string', tag: 'string',
@@ -107,8 +118,9 @@ export const QUERY_FLAG_NAMES = Object.keys(QUERY_FLAGS);
 export const QUERY_FLAG_SUPPORT = {
     entity: ['kind', 'filter', 'type', 'parent', 'domain', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
     knowledge: ['kind', 'domain', 'confidence', 'subtype', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
+    session: ['kind', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
     all: ['kind', 'filter', 'type', 'parent', 'domain', 'confidence', 'subtype', 'tag', 'since', 'before', 'created-since', 'created-before', 'sort-by', 'sort-order', 'limit', 'offset'],
-    'related-to': ['related-to'],
+    'related-to': ['related-to', 'kind'],
 };
 const FLAG_SCOPE_REASON = {
     filter: 'it selects entity status (or the entity-only stale/capture views); knowledge notes carry no status',
@@ -117,16 +129,17 @@ const FLAG_SCOPE_REASON = {
     confidence: 'knowledge notes only',
     subtype: 'knowledge notes only',
 };
-const QUERY_KINDS = ['entity', 'knowledge', 'all'];
+const QUERY_KINDS = ['entity', 'knowledge', 'session', 'all'];
 function rejectUnsupportedFlags(branch, flags) {
     const supported = new Set(QUERY_FLAG_SUPPORT[branch]);
     for (const [name, value] of Object.entries(flags)) {
         if (value === undefined || supported.has(name))
             continue;
         const where = branch === 'related-to'
-            ? 'with --related-to (it returns every entity and knowledge note linked to the slug)'
+            ? 'with --related-to (it returns every entity, knowledge note and session note linked to the slug)'
             : `with --kind ${branch}`;
-        const reason = FLAG_SCOPE_REASON[name] ? ` — ${FLAG_SCOPE_REASON[name]}` : '';
+        const scope = branch === 'session' && (name === 'domain' || name === 'tag') ? 'a session note carries none' : FLAG_SCOPE_REASON[name];
+        const reason = scope ? ` — ${scope}` : '';
         throw new UsageError(`--${name} is not supported ${where}${reason}\n${QUERY_USAGE}`);
     }
 }
@@ -142,9 +155,10 @@ function intFlag(raw, name) {
 export async function cmdQuery(os, args, opts = {}) {
     const { flags } = parseArgs(args, QUERY_FLAGS, QUERY_USAGE);
     const relatedTo = str(flags['related-to']);
-    const branch = relatedTo !== undefined ? 'related-to' : (str(flags.kind) ?? 'entity');
-    if (branch !== 'related-to' && !QUERY_KINDS.includes(branch)) {
-        throw new UsageError(`--kind must be one of ${QUERY_KINDS.join(', ')} (got "${branch}")\n${QUERY_USAGE}`);
+    const kindFlag = str(flags.kind);
+    const branch = relatedTo !== undefined ? 'related-to' : (kindFlag ?? 'entity');
+    if (kindFlag !== undefined && !QUERY_KINDS.includes(kindFlag)) {
+        throw new UsageError(`--kind must be one of ${QUERY_KINDS.join(', ')} (got "${kindFlag}")\n${QUERY_USAGE}`);
     }
     rejectUnsupportedFlags(branch, flags);
     const filter = (str(flags.filter) ?? 'active');
@@ -165,20 +179,16 @@ export async function cmdQuery(os, args, opts = {}) {
     const offset = intFlag(str(flags.offset), 'offset');
     const sortOpts = { sort_by: sortBy, sort_order: sortOrder, limit, offset };
     const timeOpts = { since, before, createdSince, createdBefore };
-    // --related-to: always returns both entities and knowledge
+    // --related-to: every kind linked to the slug, the sessions that touched
+    // an entity included; --kind narrows to one (the entity header's
+    // `--kind session --related-to` line)
     if (relatedTo) {
-        const result = await os.related_to(relatedTo);
+        const linked = await os.related_to(relatedTo);
+        const items = kindFlag && kindFlag !== 'all' ? linked.items.filter(i => i.kind === kindFlag) : linked.items;
+        const result = { items, total: items.length };
         if (opts.json)
             return jsonOut(result);
-        const { items: results, total } = result;
-        const entities = results.filter(r => r.kind === 'entity');
-        const knowledge = results.filter(r => r.kind === 'knowledge');
-        const sections = [];
-        if (entities.length > 0)
-            sections.push('## Entities\n\n' + formatQueryTable(entities, total));
-        if (knowledge.length > 0)
-            sections.push('## Knowledge\n\n' + formatKnowledgeTable(knowledge, total));
-        return sections.length > 0 ? sections.join('\n\n') : 'No results.';
+        return formatUnifiedSections(result.items, result.total);
     }
     const queryOpts = { filter, type, parent, domain, ...timeOpts, tags, ...sortOpts };
     // --kind knowledge: query knowledge only. The time window applies here too —
@@ -190,22 +200,19 @@ export async function cmdQuery(os, args, opts = {}) {
             return jsonOut(result);
         return formatKnowledgeTable(result.items, result.total);
     }
-    // --kind all: query both entities and knowledge via unified query
+    // --kind session: the session notes alone, newest first
+    if (branch === 'session') {
+        const result = await os.query_sessions({ ...timeOpts, ...sortOpts });
+        if (opts.json)
+            return jsonOut(result);
+        return formatSessionTable(result.items, result.total);
+    }
+    // --kind all: every kind via the unified query, sessions included
     if (branch === 'all') {
         const result = await os.queryUnified({ ...queryOpts, kind: 'all', confidence, subtype });
         if (opts.json)
             return jsonOut(result);
-        const { items, total } = result;
-        const entities = items.filter(i => i.kind === 'entity');
-        const knowledge = items.filter(i => i.kind === 'knowledge');
-        const sections = [];
-        if (entities.length > 0)
-            sections.push('## Entities\n\n' + formatQueryTable(entities));
-        if (knowledge.length > 0)
-            sections.push('## Knowledge\n\n' + formatKnowledgeTable(knowledge));
-        if (items.length < total)
-            sections.push(`\nShowing ${items.length} of ${total}`);
-        return sections.length > 0 ? sections.join('\n\n') : 'No results.';
+        return formatUnifiedSections(result.items, result.total);
     }
     // --kind entity (default): query entities
     const result = await os.query(queryOpts);
@@ -213,14 +220,38 @@ export async function cmdQuery(os, args, opts = {}) {
         return jsonOut(result);
     return formatQueryTable(result.items, result.total);
 }
-const SEARCH_USAGE = 'Usage: hafez search <terms> [--kind entity|knowledge|all]';
+/** One section per kind present, in the order entities, knowledge,
+ * sessions; a page line when the page is short of the total. */
+function formatUnifiedSections(items, total) {
+    const entities = items.filter((i) => i.kind === 'entity');
+    const knowledge = items.filter((i) => i.kind === 'knowledge');
+    const sessions = items.filter((i) => i.kind === 'session');
+    const sections = [];
+    if (entities.length > 0)
+        sections.push('## Entities\n\n' + formatQueryTable(entities));
+    if (knowledge.length > 0)
+        sections.push('## Knowledge\n\n' + formatKnowledgeTable(knowledge));
+    if (sessions.length > 0)
+        sections.push('## Sessions\n\n' + formatSessionTable(sessions));
+    if (items.length < total)
+        sections.push(`\nShowing ${items.length} of ${total}`);
+    return sections.length > 0 ? sections.join('\n\n') : 'No results.';
+}
+const SEARCH_USAGE = `Usage: hafez search <terms> [--kind entity|knowledge|session|all]
+
+  Without --kind, entities and knowledge notes are searched. --kind all adds
+  the session notes; --kind session searches them alone.`;
 const SEARCH_FLAGS = { kind: 'string' };
+const SEARCH_KINDS = ['entity', 'knowledge', 'session', 'all'];
 export async function cmdSearch(os, args, opts = {}) {
     const { flags, positionals } = parseArgs(args, SEARCH_FLAGS, SEARCH_USAGE);
     const terms = positionals.join(' ');
     if (!terms)
         throw new UsageError(SEARCH_USAGE);
-    const kind = (str(flags.kind) ?? 'all');
+    const kind = str(flags.kind);
+    if (kind !== undefined && !SEARCH_KINDS.includes(kind)) {
+        throw new UsageError(`--kind must be one of ${SEARCH_KINDS.join(', ')} (got "${kind}")\n${SEARCH_USAGE}`);
+    }
     const results = await os.search(terms, kind);
     if (opts.json)
         return jsonOut(results);
@@ -462,7 +493,14 @@ async function updateFailure(os, slug, err, opts) {
         return err;
     let retry;
     try {
-        retry = { footer: await footerFor(os, slug, await os.read(slug, 'full'), 'full') };
+        const file = await os.read(slug, 'full');
+        // The Op Spec resolves no session note, so the update missed; the slug
+        // names one all the same. Say what it is instead of offering a Footer
+        // it will never have.
+        if (file.kind === 'session') {
+            return new RenderedError('VALIDATION_FAILED', `'${slug}' is a session note: written once and read, never updated. What matters from it belongs on the entity it touched.`, 'stderr');
+        }
+        retry = { footer: footerFor(slug, file) };
     }
     catch (readErr) {
         if (!(readErr instanceof HafezError) || readErr.code !== 'NOT_FOUND')
@@ -542,6 +580,78 @@ export async function cmdValidate(os, args, opts = {}) {
         return jsonOut(report);
     return formatValidation(report);
 }
+export async function cmdHealth(os, args, opts = {}) {
+    helpIfAsked(args, 'Usage: hafez health  (what placement would change; applies nothing)');
+    const report = await os.health();
+    if (opts.json)
+        return jsonOut(report);
+    return formatHealth(report);
+}
+const GRAPH_USAGE = "Usage: hafez graph [slug] [--port N] [--no-open]  (serve the vault's graph on 127.0.0.1 and open it in the browser; a slug opens it focused on that note)\n       hafez graph --json [--layers tag,domain,session]  (the vault's structure as {nodes, edges})";
+const GRAPH_FLAGS = { layers: 'string', port: 'string', 'no-open': 'boolean' };
+/** The local-graph depth `hafez graph <slug>` opens at (#256). */
+const GRAPH_FOCUS_DEPTH = 2;
+export async function cmdGraph(os, args, opts = {}) {
+    const { flags, positionals } = parseArgs(args, GRAPH_FLAGS, GRAPH_USAGE);
+    if (positionals.length > 1)
+        throw new UsageError(GRAPH_USAGE);
+    const slug = positionals[0];
+    if (!opts.json) {
+        if (flags.layers !== undefined)
+            throw new UsageError('--layers requires --json', GRAPH_USAGE);
+        // A miss fails as `read` does, before any server starts.
+        if (slug !== undefined)
+            await os.read(slug, 'frontmatter').catch(err => { throw readMiss(err, slug, opts); });
+        return serveGraph(opts.vaultPath, flags, slug);
+    }
+    if (slug !== undefined)
+        throw new UsageError('a slug opens the page focused on it; --json prints the whole Graph', GRAPH_USAGE);
+    if (flags.port !== undefined || flags['no-open'])
+        throw new UsageError('--port and --no-open serve the page; --json prints the Graph and exits', GRAPH_USAGE);
+    const layers = splitList(flags.layers);
+    const unknown = layers?.find(l => !GRAPH_LAYERS.includes(l));
+    if (unknown !== undefined)
+        throw new UsageError(`Unknown layer: ${unknown}. Valid layers: ${GRAPH_LAYERS.join(', ')}`, GRAPH_USAGE);
+    return jsonOut(await os.graph(layers ? { layers: layers } : undefined));
+}
+const STOP_SIGNALS = ['SIGINT', 'SIGTERM'];
+/** `hafez graph` without --json: serve the page until Ctrl-C or SIGTERM, then close the
+ * server and the index. The server gets its own instance whose reads trust the
+ * index: it syncs the index when its poll sees a commit (#271). */
+async function serveGraph(vaultPath, flags, focus) {
+    const portFlag = str(flags.port);
+    if (portFlag !== undefined && !(/^\d+$/.test(portFlag) && Number(portFlag) <= 65535)) {
+        throw new UsageError(`--port takes a port number (0-65535), got "${portFlag}"`, GRAPH_USAGE);
+    }
+    const port = portFlag === undefined ? undefined : Number(portFlag);
+    const { startGraphServer, DEFAULT_PORT } = await import('../graph/server.js');
+    const { createInternalHafez } = await import('../internal.js');
+    const os = createInternalHafez({ vaultPath, git: { push: false }, indexSync: 'manual' });
+    const server = await startGraphServer({ os, port }).catch(err => {
+        os.close();
+        if (err.code !== 'EADDRINUSE' || port === undefined)
+            throw err;
+        throw new UsageError(`port ${port} is in use: pick another with --port, or leave it off for the first free port from ${DEFAULT_PORT}`);
+    });
+    // The page reads its view from the URL: a focus opens local-graph mode around it.
+    const url = focus === undefined ? server.url : `${server.url}/?focus=${encodeURIComponent(focus)}&depth=${GRAPH_FOCUS_DEPTH}`;
+    process.stdout.write(`Serving the graph at ${url}  (Ctrl-C to stop)\n`);
+    if (!flags['no-open'])
+        (await import('../graph/open.js')).openBrowser(url);
+    // SIGTERM (a supervisor's kill) stops it as Ctrl-C does, so the index is
+    // closed either way (#280). A second signal during the close is not caught.
+    await new Promise(resolve => {
+        const stop = () => {
+            for (const signal of STOP_SIGNALS)
+                process.off(signal, stop);
+            resolve();
+        };
+        for (const signal of STOP_SIGNALS)
+            process.on(signal, stop);
+    });
+    await server.close();
+    return 'Graph server stopped.';
+}
 export async function cmdIndexRebuild(os) {
     await os.rebuildIndex();
     return 'Index rebuilt.';

package/dist/cli/format.d.ts

@@ -1,13 +1,21 @@
-import type { QueryResult, KnowledgeQueryResult, ValidationReport, SearchResult, VaultStats, ChangelogEntry } from '../types.js';
+import type { QueryResult, KnowledgeQueryResult, SessionQueryResult, ValidationReport, HealthReport, SearchResult, VaultStats, ChangelogEntry } from '../types.js';
 /** `parent` is the rendered value of the `parent:` line (the slug with the
- * parent's description); absent, the slug alone. */
-export declare function formatEntityHeader(fm: Record<string, any>, body: string, parent?: string | undefined): string;
+ * parent's description); absent, the slug alone. `pointers` are the lines
+ * naming what hangs off the entity elsewhere (its sessions, its archive). */
+export declare function formatEntityHeader(fm: Record<string, any>, body: string, parent?: string | undefined, pointers?: string[]): string;
+/** A session note: its day, then the entities it touched. */
+export declare function formatSessionHeader(fm: Record<string, any>, body: string): string;
 export declare function formatKnowledgeHeader(fm: Record<string, any>, body: string): string;
 export type QueryTableRow = Pick<QueryResult, 'slug' | 'name' | 'type' | 'status' | 'next_action' | 'next_action_count'>;
 export declare function formatQueryTable(results: QueryTableRow[], total?: number): string;
 export type KnowledgeTableRow = Pick<KnowledgeQueryResult, 'slug' | 'name' | 'confidence' | 'domain' | 'reinforcement_count'>;
 export declare function formatKnowledgeTable(results: KnowledgeTableRow[], total?: number): string;
+export type SessionTableRow = Pick<SessionQueryResult, 'slug' | 'name' | 'session_date' | 'related'>;
+export declare function formatSessionTable(results: SessionTableRow[], total?: number): string;
 export declare function formatSearchResults(results: SearchResult[]): string;
 export declare function formatStats(stats: VaultStats): string;
 export declare function formatChangelog(entries: ChangelogEntry[]): string;
+/** The Health pass as markdown: one section per check, every section
+ * printed, so an empty report still shows what was checked. */
+export declare function formatHealth(report: HealthReport): string;
 export declare function formatValidation(report: ValidationReport): string;

package/dist/cli/format.js

@@ -1,6 +1,8 @@
+import { ITEMS } from '../surfaces/items.js';
 /** `parent` is the rendered value of the `parent:` line (the slug with the
- * parent's description); absent, the slug alone. */
-export function formatEntityHeader(fm, body, parent = fm.parent) {
+ * parent's description); absent, the slug alone. `pointers` are the lines
+ * naming what hangs off the entity elsewhere (its sessions, its archive). */
+export function formatEntityHeader(fm, body, parent = fm.parent, pointers = []) {
     const lines = [`# ${fm.name}`];
     if (fm.description)
         lines.push(`> ${fm.description}`);
@@ -29,6 +31,23 @@ export function formatEntityHeader(fm, body, parent = fm.parent) {
         lines.push(`tags: ${fm.tags.join(', ')}`);
     if (fm.resource)
         lines.push(`resource: ${fm.resource}`);
+    lines.push(...pointers);
+    lines.push('');
+    lines.push(body);
+    return lines.join('\n');
+}
+/** A session note: its day, then the entities it touched. */
+export function formatSessionHeader(fm, body) {
+    const lines = [`# ${fm.name}`];
+    const meta = [];
+    if (fm['session-date'])
+        meta.push(`session-date: ${fm['session-date']}`);
+    if (fm.created)
+        meta.push(`created: ${fm.created}`);
+    if (meta.length)
+        lines.push(meta.join(' | '));
+    if (fm.related?.length)
+        lines.push(`related: ${fm.related.join(', ')}`);
     lines.push('');
     lines.push(body);
     return lines.join('\n');
@@ -100,11 +119,24 @@ export function formatKnowledgeTable(results, total) {
     }
     return lines.join('\n');
 }
+export function formatSessionTable(results, total) {
+    if (results.length === 0)
+        return 'No results.';
+    const lines = ['| slug | name | session-date | related |', '|------|------|--------------|---------|'];
+    for (const r of results) {
+        lines.push(`| ${r.slug} | ${r.name} | ${r.session_date} | ${r.related.join(', ')} |`);
+    }
+    if (total != null && results.length < total) {
+        lines.push(`\nShowing ${results.length} of ${total}`);
+    }
+    return lines.join('\n');
+}
 export function formatSearchResults(results) {
     if (results.length === 0)
         return 'No results.';
     const entities = results.filter(r => r.kind === 'entity');
     const knowledge = results.filter(r => r.kind === 'knowledge');
+    const sessions = results.filter(r => r.kind === 'session');
     const sections = [];
     if (entities.length > 0) {
         const lines = ['## Entities', '', '| slug | name | type | match |', '|------|------|------|-------|'];
@@ -118,6 +150,12 @@ export function formatSearchResults(results) {
             lines.push(`| ${r.slug} | ${r.name} | ${r.confidence ?? ''} | ${r.snippet} |`);
         sections.push(lines.join('\n'));
     }
+    if (sessions.length > 0) {
+        const lines = ['## Sessions', '', '| slug | name | match |', '|------|------|-------|'];
+        for (const r of sessions)
+            lines.push(`| ${r.slug} | ${r.name} | ${r.snippet} |`);
+        sections.push(lines.join('\n'));
+    }
     return sections.join('\n\n');
 }
 export function formatStats(stats) {
@@ -159,13 +197,32 @@ export function formatChangelog(entries) {
     const rows = entries.map(e => `| ${e.slug} | ${e.kind} | ${e.operation} | ${e.timestamp.slice(0, 10)} | ${e.commit_message} |`);
     return [header, sep, ...rows].join('\n');
 }
+/** The Health pass as markdown: one section per check, every section
+ * printed, so an empty report still shows what was checked. */
+export function formatHealth(report) {
+    const out = ['## Health'];
+    const section = (title, items) => {
+        out.push('', `### ${title} (${items.length})`);
+        for (const item of items)
+            out.push(`- ${item}`);
+    };
+    // The workstream Item's own text (ADR 0001), prefixed with the entity.
+    section('Workstreams', report.workstreams.map(w => `${w.entity} ${ITEMS.workstreamLine.render(w)}`));
+    section('Recurring names', report.recurring_names.map(r => `${r.entity}: \`${r.term}\` in ${r.units} units across ${r.days.length} days (${r.days[0]} .. ${r.days[r.days.length - 1]})`));
+    section('Leakage', report.leakage.map(l => `${l.parent} → ${l.child} (${l.relation}): ${l.hits} of ${l.entries} entries (${Math.round(100 * l.hits / l.entries)}%)`));
+    section('One-way edges', report.one_way_edges.map(e => `${e.from} → ${e.to}: \`hafez link ${e.to} ${e.from} --relation related\``));
+    section('Unlinked mentions', report.unlinked_mentions.map(e => `${e.from} mentions [[${e.to}]]: \`hafez link ${e.from} ${e.to} --relation related\``));
+    section('Restated decisions', report.restated_decisions.map(r => `${r.day} ${r.entity} → ${r.note} (${Math.round(100 * r.share)}%): ${r.summary}`));
+    return out.join('\n');
+}
 export function formatValidation(report) {
     const issues = report.broken_slugs.length + report.orphaned_knowledge.length +
         report.missing_fields.length;
+    const counts = `${report.total_entities} entities, ${report.total_knowledge} knowledge, ${report.total_sessions} sessions`;
     if (issues === 0) {
-        return `Vault OK — ${report.total_entities} entities, ${report.total_knowledge} knowledge, 0 issues`;
+        return `Vault OK — ${counts}, 0 issues`;
     }
-    const sections = [`## Vault Validation — ${report.total_entities} entities, ${report.total_knowledge} knowledge`];
+    const sections = [`## Vault Validation — ${counts}`];
     const addSection = (title, items) => {
         if (items.length === 0)
             return;

package/dist/cli/index.js

@@ -41,6 +41,8 @@ export const COMMANDS = {
     delete: { phase: 'vault', mutating: true, run: lazy(m => m.cmdDelete) },
     batch: { phase: 'vault', mutating: true, run: lazy(m => m.cmdBatch) },
     validate: { phase: 'vault', run: lazy(m => m.cmdValidate) },
+    health: { phase: 'vault', run: lazy(m => m.cmdHealth) },
+    graph: { phase: 'vault', run: lazy(m => m.cmdGraph) },
     index: {
         phase: 'vault',
         run: async (os, args) => {
@@ -68,6 +70,7 @@ export const EXIT_TABLE = [
     { exit: 5, meaning: 'slug already exists', errorCodes: ['SLUG_EXISTS'] },
     { exit: 6, meaning: 'git commit failed — nothing was written to history', errorCodes: ['GIT_COMMIT_FAILED'] },
     { exit: 7, meaning: 'vault locked by another hafez process — retry when it finishes', errorCodes: ['VAULT_LOCKED'] },
+    { exit: 8, meaning: "git read failed (changelog, stats) — the vault's git is unusable", errorCodes: ['GIT_READ_FAILED'] },
 ];
 export const EXIT_CODES = Object.fromEntries(EXIT_TABLE.flatMap(row => (row.errorCodes ?? []).map(code => [code, row.exit])));
 /** Exported so a guard test can assert every registered command is documented
@@ -75,11 +78,14 @@ export const EXIT_CODES = Object.fromEntries(EXIT_TABLE.flatMap(row => (row.erro
 export const USAGE = `Usage: hafez <command> [args]
 
 Commands:
-  read <slug>                Read entity or knowledge note
+  read <slug>                Read an entity, knowledge note or session note
+    --archive                An entity's archived log entries
   query [--filter ...] ...   Filter entities/knowledge
-    --kind all               Both kinds; --filter matches entity status only,
-                             so knowledge notes (which have none) always show
-  search <terms>             Full-text search
+    --kind all               Every kind, sessions included; --filter matches
+                             entity status only, so the rest always show
+    --kind session           Session notes alone, newest first
+  search <terms>             Full-text search of entities and knowledge
+    --kind session|all       Session notes alone, or every kind
   create <kind> <name>       Create entity or knowledge note
   capture <name> [--notes]   Quick inbox capture
   promote <slug> <target>    Promote capture→entity/project/knowledge, entity→project
@@ -105,15 +111,24 @@ Commands:
   changelog --since <when>   Git-derived change history (e.g. --since 7.days.ago)
   schema [op] [--examples]   Machine-readable JSON schema for batch operations
   validate                   Check vault integrity
+  health                     The Health pass: what placement would change (applies nothing)
+  graph --json               The vault's structure: entities and knowledge, parent/related/wiki-link edges
+    --layers tag,domain,session  Add tag and domain nodes, and sessions
+  graph [slug] [--port N] [--no-open]
+                             Serve the graph on 127.0.0.1 (first free port from 4747) and open the browser;
+                             a slug opens it focused on that note, local graph at depth 2
   index rebuild              Rebuild the SQLite index
   init --register <path>     Register an existing vault
   init                       Show current vault resolution
   onboard                    Setup status, then the script your agent follows to set Hafez up
-    --install --mode <always-on|invoke-only> [--harness <h>] [--confirm]
+    --install --mode <always-on|invoke-only> [--harness <h>] [--vault-repo <o/r>] [--confirm]
                              Write both skills and, always-on, the Block
+                             (--vault-repo: the cloud Block, which attaches that repo)
     --remove [--confirm]     Remove the skills and the Block region
     --block [--harness <h>]  Print the Block and the entities matching this folder
                              (the SessionStart hook; prints nothing on any failure)
+    --cloud --vault-repo <o/r>
+                             Print the setup script for Claude Code cloud sessions
   upgrade                    Check whether hafez is outdated and print the update steps
   help --agent               The hafez skill body: the reference when the skill is not installed
 
@@ -278,22 +293,28 @@ export async function main(argv) {
         // First touch of the core — and so of the native SQLite binding. A
         // failure to load it lands in the catch below and is recognised by
         // isBindingsFailure, exactly as it was when this import was static.
-        const { createHafez } = await import('../index.js');
-        const os = createHafez({ vaultPath, git: { push: false } });
-        const result = await spec.run(os, args, { json, vaultPath });
-        // Auto-sync after mutating commands
-        if (spec.mutating) {
-            try {
-                await os.sync();
-            }
-            catch (syncErr) {
-                // Operation succeeded but sync failed — emit result with warning, exit 4
-                process.stdout.write(result + '\n');
-                process.stderr.write(`Warning: ${syncErr.message ?? syncErr.message}\n`);
-                process.exit(4);
+        const { createInternalHafez } = await import('../internal.js');
+        // One index scan per process (#269): the first read syncs, later reads trust it.
+        const os = createInternalHafez({ vaultPath, git: { push: false }, indexSync: 'once' });
+        try {
+            const result = await spec.run(os, args, { json, vaultPath });
+            // Auto-sync after mutating commands
+            if (spec.mutating) {
+                try {
+                    await os.sync();
+                }
+                catch (syncErr) {
+                    // Operation succeeded but sync failed — emit result with warning, exit 4
+                    process.stdout.write(result + '\n');
+                    process.stderr.write(`Warning: ${syncErr.message ?? syncErr.message}\n`);
+                    process.exit(4);
+                }
             }
+            process.stdout.write(result + '\n');
+        }
+        finally {
+            os.close();
         }
-        process.stdout.write(result + '\n');
     }
     catch (err) {
         if (hook)

package/dist/cli/install.d.ts

@@ -6,6 +6,8 @@ export declare const SKILL_DIRS: string[];
 export type HashState = 'absent' | 'current' | 'stale' | 'hand-edited';
 /** What to do about broken markers: a hand edit, then `rerun`. */
 export declare const fixBrokenMarkers: (path: string, rerun: string) => string;
+/** The flag that keeps an install a cloud one, for every printed install line. */
+export declare const vaultRepoFlag: (vaultRepo: string | undefined) => string;
 /** What to do about a 1.x section: Hafez cannot tell where it ends. */
 export declare const removeLegacy: (path: string, line: number) => string;
 /** The status line for a 1.x section. */
@@ -24,13 +26,18 @@ export interface InstallState {
     onboarded: boolean;
     /** The line of a 1.x section in the instructions file, else null. */
     legacy: number | null;
+    /** The Block is a cloud Block, for this vault repo. */
+    vaultRepo?: string;
 }
 export declare function installState(home: string, harness: HarnessId): InstallState;
+/** `vaultRepo`: the install is for a cloud container, whose Block carries
+ * the rule that attaches that repo as the vault (#160). */
 export declare function install(opts: {
     home: string;
     harness: HarnessId;
     mode: Mode;
     confirm: boolean;
+    vaultRepo?: string;
 }): string;
 export interface SkillCheck {
     path: string;
@@ -43,6 +50,8 @@ export interface BlockCheck {
     state: Exclude<HashState, 'absent'> | 'broken';
     /** The Block Hafez writes has changed since this one was written. */
     renderChanged: boolean;
+    /** A cloud Block: the vault repo it was written for. */
+    vaultRepo?: string;
 }
 export interface LegacyCheck {
     harness: HarnessId;