hafez 2.1.0 → 2.2.0

package/dist/cli/format.js

@@ -1,6 +1,7 @@
 /** `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 +30,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 +118,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 +149,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) {
@@ -162,10 +199,11 @@ export function formatChangelog(entries) {
 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

@@ -68,6 +68,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 +76,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
@@ -109,11 +113,14 @@ Commands:
   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
 
@@ -280,20 +287,25 @@ export async function main(argv) {
         // 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);
+        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;

package/dist/cli/install.js

@@ -14,6 +14,7 @@ import { dirname, join } from 'path';
 import { HafezError } from '../types.js';
 import { HARNESSES } from '../harness.js';
 import { contentHash, renderBlock, renderHafezSaveSkill, renderHafezSkill } from '../surfaces/surfaces.js';
+import { isVaultRepo } from '../surfaces/items.js';
 export const MODES = ['always-on', 'invoke-only'];
 export const isMode = (value) => MODES.includes(value);
 export const SKILL_DIRS = ['.claude/skills', '.agents/skills'];
@@ -36,7 +37,8 @@ function hashState(found, rendered) {
     return 'stale';
 }
 // --- The Block region ---
-const BEGIN = /^<!-- hafez:begin ([0-9a-f]{12}) -->$/;
+/** The hash, then a cloud Block's vault repo (#160). */
+const BEGIN = /^<!-- hafez:begin ([0-9a-f]{12})(?: vault-repo=(\S+))? -->$/;
 const END = '<!-- hafez:end -->';
 /** What broken markers are, for a refusal or a report about `path`. */
 const brokenMarkers = (path) => `The Hafez markers in ${path} are broken: expected one "<!-- hafez:begin <hash> -->" line followed by one "${END}" line.`;
@@ -62,8 +64,9 @@ function findRegion(file, displayPath) {
         return null;
     const [begin] = begins;
     const [end] = ends;
-    const hash = begin ? BEGIN.exec(begin.line)?.[1] : undefined;
-    if (begins.length !== 1 || ends.length !== 1 || end.start < begin.start || !hash || end.line !== END) {
+    const [, hash, vaultRepo] = (begin && BEGIN.exec(begin.line)) || [];
+    if (begins.length !== 1 || ends.length !== 1 || end.start < begin.start || !hash || end.line !== END
+        || (vaultRepo !== undefined && !isVaultRepo(vaultRepo))) {
         throw new HafezError('VALIDATION_FAILED', `${brokenMarkers(displayPath)} Fix or delete them by hand, then re-run.`);
     }
     return {
@@ -73,8 +76,11 @@ function findRegion(file, displayPath) {
         hash,
         body: file.slice(begin.next, end.start),
         text: file.slice(begin.start, end.start + END.length),
+        ...(vaultRepo !== undefined && { vaultRepo }),
     };
 }
+/** The flag that keeps an install a cloud one, for every printed install line. */
+export const vaultRepoFlag = (vaultRepo) => (vaultRepo === undefined ? '' : ` --vault-repo ${vaultRepo}`);
 // --- The 1.x section ---
 /** The heading 1.2–1.4 `onboard` had the agent paste, with no markers (#157). */
 const LEGACY_HEADING = '## Hafez — Session Memory';
@@ -169,14 +175,22 @@ function skillSteps(home, want) {
         return { line: `~/${rel}: ${state === 'absent' ? 'written' : `replaced (was ${state})`}`, write: () => write(path, rendered) };
     });
 }
-const RENDERED = findRegion(renderBlock(), 'the render');
-function blockStep({ home, rel, want, confirm, rerun, suffix = '' }) {
+const RENDERS = new Map();
+/** The Block Hafez writes, as a region; with `vaultRepo`, the cloud Block. A
+ * found Block is checked against the render for its own marker's repo. */
+function rendered(vaultRepo) {
+    if (!RENDERS.has(vaultRepo))
+        RENDERS.set(vaultRepo, findRegion(renderBlock(vaultRepo), 'the render'));
+    return RENDERS.get(vaultRepo);
+}
+function blockStep({ home, rel, want, confirm, rerun, suffix = '', vaultRepo }) {
     const path = join(home, rel);
     const label = `Block in ~/${rel}`;
     const file = readInstalled(path);
     const text = file ?? '';
     const region = findRegion(text, `~/${rel}`);
-    const state = hashState(region, RENDERED.text);
+    const target = rendered(want === 'write' ? vaultRepo : region?.vaultRepo);
+    const state = hashState(region, target.text);
     if (region && state === 'hand-edited' && !confirm) {
         return {
             line: `${label}: hand-edited, left alone`,
@@ -186,7 +200,7 @@ function blockStep({ home, rel, want, confirm, rerun, suffix = '' }) {
                 rerun,
                 '',
                 '````diff',
-                lineDiff(region.body, RENDERED.body),
+                lineDiff(region.body, target.body),
                 '````',
             ].join('\n'),
         };
@@ -200,11 +214,11 @@ function blockStep({ home, rel, want, confirm, rerun, suffix = '' }) {
         return { line: `${label}: current` };
     if (!region) {
         const before = text === '' || text.endsWith('\n') ? text : `${text}\n`;
-        return { line: `${label}: written`, write: () => write(path, before + renderBlock()) };
+        return { line: `${label}: written`, write: () => write(path, before + renderBlock(vaultRepo)) };
     }
     return {
         line: `${label}: replaced (was ${state})`,
-        write: () => write(path, text.slice(0, region.start) + RENDERED.text + text.slice(region.end)),
+        write: () => write(path, text.slice(0, region.start) + target.text + text.slice(region.end)),
     };
 }
 /** Codex reads an `AGENTS.override.md` in place of `AGENTS.md` when one
@@ -228,13 +242,15 @@ export function installState(home, harness) {
     const { instructions } = HARNESSES[harness];
     let block = null;
     let legacy = null;
+    let vaultRepo;
     if (instructions !== null) {
         const rel = instructionsFile(home, instructions);
         const text = readInstalled(join(home, rel)) ?? '';
         let region;
         try {
             region = findRegion(text, `~/${rel}`);
-            block = hashState(region, RENDERED.text);
+            vaultRepo = region?.vaultRepo;
+            block = hashState(region, rendered(vaultRepo).text);
         }
         catch {
             block = 'broken';
@@ -249,11 +265,13 @@ export function installState(home, harness) {
     const states = new Set(skills.map(s => s.state));
     const [only] = states;
     const merged = states.size === 1 ? only : states.has('hand-edited') ? 'hand-edited' : 'stale';
-    return { block, skills: merged, onboarded: skills.some(s => s.hashed), legacy };
+    return { block, skills: merged, onboarded: skills.some(s => s.hashed), legacy, ...(vaultRepo !== undefined && { vaultRepo }) };
 }
 // --- The two commands ---
+/** `vaultRepo`: the install is for a cloud container, whose Block carries
+ * the rule that attaches that repo as the vault (#160). */
 export function install(opts) {
-    const { home, harness, mode, confirm } = opts;
+    const { home, harness, mode, confirm, vaultRepo } = opts;
     const { label, instructions } = HARNESSES[harness];
     const steps = skillSteps(home, 'write');
     const tail = [];
@@ -273,8 +291,9 @@ export function install(opts) {
             rel,
             want: mode === 'always-on' ? 'write' : 'remove',
             confirm,
-            rerun: `hafez onboard --install --harness ${harness} --mode ${mode} --confirm`,
+            rerun: `hafez onboard --install --harness ${harness} --mode ${mode}${vaultRepoFlag(vaultRepo)} --confirm`,
             suffix: mode === 'invoke-only' ? ' (invoke-only)' : '',
+            vaultRepo,
         }));
     }
     const out = run({ header: `${label}, ${mode}:`, steps, tail, unchanged: 'Nothing changed: the install is current.', listAll: true });
@@ -316,8 +335,10 @@ export function checkInstall(home) {
             legacy.push({ harness, path, line });
         if (!region)
             continue;
-        const state = hashState(region, RENDERED.text);
-        blocks.push({ harness, path, state, renderChanged: region.hash !== RENDERED.hash });
+        const { vaultRepo } = region;
+        const render = rendered(vaultRepo);
+        const state = hashState(region, render.text);
+        blocks.push({ harness, path, state, renderChanged: region.hash !== render.hash, ...(vaultRepo !== undefined && { vaultRepo }) });
     }
     return { skills, blocks, legacy };
 }

package/dist/cli/onboard.js

@@ -9,33 +9,36 @@
 // `--install` and `--remove` write the files Hafez owns outside the vault
 // (install.ts). The binary has no interactive prompts: the agent asks, then
 // passes the answer as a flag. `--block` is the SessionStart hook's render
-// (block-hook.ts) and writes nothing.
+// (block-hook.ts) and writes nothing. `--cloud` prints the setup script for a
+// Claude Code cloud environment, whose `--install --vault-repo` writes the
+// Block with the rule that attaches the vault repo (#160).
 import { existsSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { UsageError, parseArgs, str } from './args.js';
 import { HARNESSES, ONBOARD_HARNESSES, detectAgent, isHarness, isOnboardHarness } from '../harness.js';
-import { MODES, SKILL_DIRS, fixBrokenMarkers, install, installState, instructionsFile, isMode, legacyLine, remove, removeLegacy } from './install.js';
+import { MODES, SKILL_DIRS, fixBrokenMarkers, install, installState, instructionsFile, isMode, legacyLine, remove, removeLegacy, vaultRepoFlag } from './install.js';
 import { noVaultMessage, resolveVaultPath } from './resolve-vault.js';
 import { HafezError } from '../types.js';
 import { kindDir, scanVaultDir } from '../vault.js';
-import { ITEMS } from '../surfaces/items.js';
+import { ITEMS, isVaultRepo } from '../surfaces/items.js';
 import { renderBlock } from '../surfaces/surfaces.js';
 import { blockHook } from './block-hook.js';
 const HARNESS_IDS = Object.keys(HARNESSES).join('|');
 const MODE_IDS = MODES.join('|');
 const ONBOARD_USAGE = `Usage:
   hafez onboard
-  hafez onboard --install --mode <${MODE_IDS}> [--harness <${HARNESS_IDS}>] [--confirm]
+  hafez onboard --install --mode <${MODE_IDS}> [--harness <${HARNESS_IDS}>] [--vault-repo <owner>/<repo>] [--confirm]
   hafez onboard --remove [--confirm]
-  hafez onboard --block [--harness <${HARNESS_IDS}>]`;
+  hafez onboard --block [--harness <${HARNESS_IDS}>]
+  hafez onboard --cloud --vault-repo <owner>/<repo>`;
 /** `ctx` is the temp-home seam: tests pass a temporary home and environment;
  * the install functions are given the home, never read it. `vaultFlag` is the
  * global `--vault`; without it the bare form reports on the registered vault.
  * `--block` returns a promise of its render, or of null when it must print nothing. */
 export function cmdOnboard(args, ctx = {}) {
     const { home = homedir(), env = process.env, cwd, vaultFlag } = ctx;
-    const { flags, positionals } = parseArgs(args, { install: 'boolean', remove: 'boolean', block: 'boolean', mode: 'string', harness: 'string', confirm: 'boolean' }, ONBOARD_USAGE);
+    const { flags, positionals } = parseArgs(args, { install: 'boolean', remove: 'boolean', block: 'boolean', cloud: 'boolean', mode: 'string', harness: 'string', 'vault-repo': 'string', confirm: 'boolean' }, ONBOARD_USAGE);
     const fail = (why) => {
         throw new UsageError(`${why}\n${ONBOARD_USAGE}`);
     };
@@ -43,9 +46,22 @@ export function cmdOnboard(args, ctx = {}) {
         fail(`Unexpected argument: ${positionals[0]}`);
     const mode = str(flags.mode);
     const harnessFlag = str(flags.harness);
+    const vaultRepo = str(flags['vault-repo']);
     const confirm = flags.confirm === true;
     if (flags.install && flags.remove)
         fail('--install and --remove are separate commands');
+    if (vaultRepo !== undefined && !isVaultRepo(vaultRepo))
+        fail(`--vault-repo takes the vault's GitHub repo as <owner>/<repo>, got: ${vaultRepo}`);
+    if (vaultRepo !== undefined && !flags.cloud && !flags.install)
+        fail('--vault-repo goes with --cloud or --install');
+    if (flags.cloud) {
+        if (flags.install || flags.remove || flags.block || mode !== undefined || harnessFlag !== undefined || confirm) {
+            fail('--cloud takes only --vault-repo: it prints the setup script and writes nothing');
+        }
+        if (vaultRepo === undefined)
+            return fail('--cloud needs --vault-repo <owner>/<repo>, the vault\'s GitHub repo');
+        return ITEMS.cloudSetup.render({ vaultRepo });
+    }
     if (flags.block) {
         if (flags.install || flags.remove || mode !== undefined || confirm)
             fail('--block takes only --harness: it prints the Block and writes nothing');
@@ -67,7 +83,11 @@ export function cmdOnboard(args, ctx = {}) {
         if (!isHarness(harness)) {
             return fail(harnessFlag === undefined ? `No harness detected: pass --harness <${HARNESS_IDS}>` : `Unknown harness: ${harnessFlag}`);
         }
-        return install({ home, harness, mode, confirm });
+        // The cloud Block's rule is Claude Code's: cloud sessions attach repos there.
+        if (vaultRepo !== undefined && (mode !== 'always-on' || harness !== 'claude-code')) {
+            fail('--vault-repo is for a Claude Code cloud container: --mode always-on --harness claude-code');
+        }
+        return install({ home, harness, mode, confirm, vaultRepo });
     }
     if (mode !== undefined || harnessFlag !== undefined || confirm)
         fail('--mode, --harness and --confirm go with --install, --remove or --block');
@@ -149,7 +169,8 @@ export function renderOnboard({ home, harness, vault }) {
     const teaching = (m) => ITEMS.teachingLines.render({ harness, mode: m });
     const line2 = (m) => ITEMS.teachingLines.render({ harness, mode: m, line2Only: true });
     const instructionsRel = `~/${instructionsFile(home, instructions)}`;
-    const block = `\`\`\`\`\n${renderBlock()}\`\`\`\``;
+    // A cloud Block stays one: its install line and Block keep the vault repo.
+    const block = `\`\`\`\`\n${renderBlock(state.vaultRepo)}\`\`\`\``;
     const showBlock = `show the user the Block below word for word, not a summary, say it goes into ${instructionsRel} between two marker lines and nothing else in that file changes, and get a yes. Then run:`;
     const status = [
         `Vault: ${vault} (${plural(entities, 'entity', 'entities')}, ${plural(knowledge, 'knowledge note', 'knowledge notes')})`,
@@ -194,7 +215,7 @@ export function renderOnboard({ home, harness, vault }) {
                 ...(state.legacy === null ? [] : [`${removeLegacy(instructionsRel, state.legacy)} Do this before either install below.`, '']),
                 `Always-on: ${showBlock}`,
                 '',
-                'hafez onboard --install --mode always-on',
+                `hafez onboard --install --mode always-on${vaultRepoFlag(state.vaultRepo)}`,
                 '',
                 'Invoke-only: no file of theirs is edited. Run:',
                 '',

package/dist/cli/upgrade.js

@@ -29,7 +29,7 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { UsageError, helpIfAsked } from './args.js';
 import { HARNESSES, detectAgent, isHarness } from '../harness.js';
-import { checkInstall, fixBrokenMarkers, legacyLine, removeLegacy } from './install.js';
+import { checkInstall, fixBrokenMarkers, legacyLine, removeLegacy, vaultRepoFlag } from './install.js';
 const PLAIN_SEMVER = /^\d+\.\d+\.\d+$/;
 const REGISTRY_TIMEOUT_MS = 3000;
 const NPM_PROBE_TIMEOUT_MS = 3000;
@@ -179,7 +179,7 @@ function blockSteps({ blocks, skills }, upgrading, env) {
         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}`,
+            text: `hafez onboard --install --mode always-on --harness ${b.harness}${vaultRepoFlag(b.vaultRepo)}`,
         }));
     }
     const harness = detectAgent(env);
@@ -192,7 +192,8 @@ function blockSteps({ blocks, skills }, upgrading, env) {
 }
 /** The action list, in execution order. Every command is built from static
  * constants; the only interpolated values are the regex-validated version,
- * the quoted package root, and harness ids from the HARNESSES table. */
+ * the quoted package root, harness ids from the HARNESSES table, and a cloud
+ * Block's vault repo, which `findRegion` reads only when it passes `isVaultRepo`. */
 function deriveSteps(state, ctx) {
     const steps = [];
     let alternativeInstall = null;

package/dist/dates.d.ts

@@ -6,5 +6,9 @@ export declare function localDay(d?: Date): string;
  * now"), and any explicit instant must anchor to the same local day boundary
  * the stamps and query comparisons use. Relative forms (`7.days.ago`) are
  * already local and pass through untouched.
+ *
+ * The offset is spelled out: without one git applies its own idea of the
+ * local zone, and Git for Windows ignores an IANA `TZ` that Node honours,
+ * so the two disagreed about where the day starts.
  */
 export declare function normalizeSinceDate(since: string): string;

package/dist/dates.js

@@ -21,7 +21,18 @@ export function localDay(d = new Date()) {
  * now"), and any explicit instant must anchor to the same local day boundary
  * the stamps and query comparisons use. Relative forms (`7.days.ago`) are
  * already local and pass through untouched.
+ *
+ * The offset is spelled out: without one git applies its own idea of the
+ * local zone, and Git for Windows ignores an IANA `TZ` that Node honours,
+ * so the two disagreed about where the day starts.
  */
 export function normalizeSinceDate(since) {
-    return /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since}T00:00:00` : since;
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(since);
+    if (!m)
+        return since;
+    // The day's first instant: 01:00 where a DST jump skips midnight.
+    const start = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    const offset = -start.getTimezoneOffset();
+    const zone = `${offset < 0 ? '-' : '+'}${pad(Math.floor(Math.abs(offset) / 60))}${pad(Math.abs(offset) % 60)}`;
+    return `${localDay(start)}T${pad(start.getHours())}:${pad(start.getMinutes())}:00${zone}`;
 }

package/dist/db.d.ts

@@ -1,9 +1,10 @@
+import { type VaultKind } from './vault.js';
 import { type VaultIndexRow } from './knowledge-index.js';
-import type { SearchResult, VaultStats, QueryResult, KnowledgeQueryResult, UnifiedResult, EntityQueryOpts, KnowledgeQueryOpts, UnifiedQueryOpts, SortField } from './types.js';
-export declare const SCHEMA_VERSION = "11";
+import type { SearchResult, SearchKind, VaultStats, QueryResult, KnowledgeQueryResult, SessionQueryResult, UnifiedResult, EntityQueryOpts, KnowledgeQueryOpts, SessionQueryOpts, UnifiedQueryOpts, SortField } from './types.js';
+export declare const SCHEMA_VERSION = "12";
 interface IndexItem {
     slug: string;
-    kind: 'entity' | 'knowledge';
+    kind: VaultKind;
     name: string;
     type: string | null;
     status: string | null;
@@ -26,6 +27,7 @@ interface IndexItem {
     last_session_date: string | null;
     last_session_type: string | null;
     last_session_summary: string | null;
+    session_date: string | null;
 }
 export interface IndexQueryResult {
     items: IndexItem[];
@@ -34,10 +36,10 @@ export interface IndexQueryResult {
 export interface HafezIndex {
     rebuild(): void;
     syncIfStale(): void;
-    upsertFromFile(slug: string, kind: 'entity' | 'knowledge'): void;
+    upsertFromFile(slug: string, kind: VaultKind): void;
     removeItem(slug: string): void;
     queryItems(opts: QueryOpts): IndexQueryResult;
-    search(query: string, kind?: 'entity' | 'knowledge' | 'all'): SearchResult[];
+    search(query: string, kind?: SearchKind): SearchResult[];
     getStats(): VaultStats;
     /** Every indexed document, in the shape index.md is rendered from. */
     indexEntries(): VaultIndexRow[];
@@ -58,13 +60,18 @@ export interface HafezIndex {
         items: KnowledgeQueryResult[];
         total: number;
     };
+    querySessions(opts?: SessionQueryOpts): {
+        items: SessionQueryResult[];
+        total: number;
+    };
     queryUnified(opts?: UnifiedQueryOpts): {
         items: UnifiedResult[];
         total: number;
     };
 }
+/** `kind` unset is the working set, entity + knowledge; `all` is literal. */
 export interface QueryOpts {
-    kind?: 'entity' | 'knowledge' | 'all';
+    kind?: VaultKind | 'all';
     status?: string;
     type?: string;
     subtype?: string;
@@ -79,7 +86,7 @@ export interface QueryOpts {
     createdSince?: string;
     createdBefore?: string;
     tags?: string[];
-    sort_by?: 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
+    sort_by?: SortField;
     sort_order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
@@ -96,11 +103,14 @@ export declare function createIndex(vaultPath: string, opts: {
  * 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"];
+/** What a session query cannot map: both sides' opts, and the two every
+ * other kind shares — a session note carries no domain and no tags. */
+export declare const SESSION_REJECTED_OPTS: readonly ["filter", "type", "parent", "confidence", "subtype", "domain", "tags"];
 /** 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';
+    kind?: VaultKind | 'all';
     sort_by?: SortField;
 };
 export {};