hafez 2.0.0 → 2.2.0

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,31 @@ 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';
+/** The 1-based line of a 1.x section outside the Block region, or null. With
+ * broken markers (`region` undefined) the region is unknown: every line is read. */
+function findLegacy(file, region) {
+    let offset = 0;
+    const lines = file.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const inside = region != null && offset >= region.start && offset < region.next;
+        if (!inside && lines[i].trimEnd() === LEGACY_HEADING)
+            return i + 1;
+        offset += lines[i].length + 1;
+    }
+    return null;
+}
+/** What to do about a 1.x section: Hafez cannot tell where it ends. */
+export const removeLegacy = (path, line) => `Remove the Hafez 1.x section in ${path}, from its heading \`${LEGACY_HEADING}\` (line ${line}) to the end of that section, after the user's yes. It has no markers, so Hafez does not delete it.`;
+/** The status line for a 1.x section. */
+export const legacyLine = (path, line) => `Legacy section in ${path}, line ${line}: \`${LEGACY_HEADING}\``;
 /** A line diff of the user's Block against the render: ` ` both, `-` theirs
  * only, `+` the render only. */
 function lineDiff(theirs, ours) {
@@ -149,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`,
@@ -166,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'),
         };
@@ -180,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
@@ -207,14 +241,21 @@ function run({ header, steps, tail = [], unchanged, listAll }) {
 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 {
-            block = hashState(findRegion(readInstalled(join(home, rel)) ?? '', `~/${rel}`), RENDERED.text);
+            region = findRegion(text, `~/${rel}`);
+            vaultRepo = region?.vaultRepo;
+            block = hashState(region, rendered(vaultRepo).text);
         }
         catch {
             block = 'broken';
         }
+        legacy = findLegacy(text, region);
     }
     const skills = SKILL_DIRS.flatMap(dir => SKILLS.map(({ name, render }) => {
         const text = readInstalled(join(home, dir, name, 'SKILL.md'));
@@ -224,15 +265,18 @@ 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) };
+    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 = [];
-    if (instructions === null) {
+    const rel = instructions === null ? null : instructionsFile(home, instructions);
+    if (rel === null) {
         if (mode === 'always-on') {
             steps.push({ line: `Block: printed below, for ${label}'s User Rules` });
             tail.push(`${label} keeps its User Rules in Settings, not a file, so the Block was not written. Show the user the Block below and ask them to paste it into ${label} Settings → Rules → User Rules, marker lines included.`, `\`\`\`\`\n${renderBlock()}\`\`\`\``);
@@ -244,24 +288,33 @@ export function install(opts) {
     else {
         steps.push(blockStep({
             home,
-            rel: instructionsFile(home, instructions),
+            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,
         }));
     }
-    return run({ header: `${label}, ${mode}:`, steps, tail, unchanged: 'Nothing changed: the install is current.', listAll: true });
+    const out = run({ header: `${label}, ${mode}:`, steps, tail, unchanged: 'Nothing changed: the install is current.', listAll: true });
+    if (rel === null)
+        return out;
+    // A 1.x section loads beside the Block, or in place of invoke-only: named,
+    // never touched (#162). Read after the writes, so its line is where it is now.
+    const text = readInstalled(join(home, rel)) ?? '';
+    const line = findLegacy(text, findRegion(text, `~/${rel}`));
+    return line === null ? out : `${out}\n\n${removeLegacy(`~/${rel}`, line)}`;
 }
 /** Both skills in both directories, and the Block in the instructions file
  * each Harness reads — the one `--install` would write. Only Blocks that are
- * there are listed: none means invoke-only. */
+ * there are listed: none, and no 1.x section, means invoke-only. */
 export function checkInstall(home) {
     const skills = skillFiles(home).map(({ rel, render, text }) => ({
         path: `~/${rel}`,
         state: hashState(text === null ? null : parseSkill(text), render()),
     }));
     const blocks = [];
+    const legacy = [];
     for (const [harness, { instructions }] of Object.entries(HARNESSES)) {
         if (instructions === null)
             continue;
@@ -276,14 +329,18 @@ export function checkInstall(home) {
         }
         catch {
             blocks.push({ harness, path, state: 'broken', renderChanged: false });
-            continue;
         }
+        const line = findLegacy(text, region);
+        if (line !== null)
+            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 };
+    return { skills, blocks, legacy };
 }
 /** Remove everything Hafez wrote: both skills from both directories, and the
  * Block region from every instructions file a Harness reads. Nothing else. */

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, remove } 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')})`,
@@ -159,6 +180,9 @@ export function renderOnboard({ home, harness, vault }) {
         ...[{ ...HARNESSES[harness], state }, ...others]
             .filter(h => h.state.block === 'broken')
             .map(h => fixBrokenMarkers(`~/${instructionsFile(home, h.instructions)}`, 'hafez onboard')),
+        ...[{ ...HARNESSES[harness], state }, ...others]
+            .filter(h => h.state.legacy !== null)
+            .map(h => `${legacyLine(`~/${instructionsFile(home, h.instructions)}`, h.state.legacy)}, from Hafez 1.x, with no markers.`),
     ];
     // With the install current there is no install step: switching the Mode is
     // walked here, and re-running `onboard` afterwards walks what it changed.
@@ -187,9 +211,11 @@ export function renderOnboard({ home, harness, vault }) {
         steps.push({
             title: 'Install',
             body: [
+                // Either install leaves the 1.x section in place, beside the Block or alone.
+                ...(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:',
                 '',
@@ -201,6 +227,9 @@ export function renderOnboard({ home, harness, vault }) {
             ].join('\n'),
         });
     }
+    if (installCurrent && state.legacy !== null) {
+        steps.push({ title: 'Remove the Hafez 1.x section', body: removeLegacy(instructionsRel, state.legacy) });
+    }
     if (!config.allowlist) {
         steps.push({ title: 'Allow the command', body: ITEMS.harnessPermissions.render({ harness, vault }) });
     }

package/dist/cli/upgrade.d.ts

@@ -1,4 +1,4 @@
-import { type BlockCheck, type SkillCheck } from './install.js';
+import { type BlockCheck, type LegacyCheck, type SkillCheck } from './install.js';
 export type Comparison = 'behind' | 'equal' | 'ahead' | 'unknown';
 /** `command` entries are directly executable (after user approval); `action`
  * entries are prose, so an agent that shells out every entry does not try to
@@ -21,11 +21,13 @@ export interface UpgradeState {
     alternativeInstall: string | null;
     steps: UpgradeStep[];
 }
-/** Mode is not stored: a Block present means always-on. */
+/** Mode is not stored: a Block present means always-on, and so does a 1.x
+ * section with no markers (`legacy`). */
 export interface Integration {
     mode: 'always-on' | 'invoke-only';
     blocks: BlockCheck[];
     skills: SkillCheck[];
+    legacy: LegacyCheck[];
 }
 export interface UpgradeDeps {
     fetch: typeof globalThis.fetch;

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 } 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;
@@ -131,8 +131,8 @@ function devCheckoutStep(packageRoot) {
 }
 function readIntegration(home) {
     try {
-        const { skills, blocks } = checkInstall(home);
-        return { mode: blocks.length > 0 ? 'always-on' : 'invoke-only', blocks, skills };
+        const { skills, blocks, legacy } = checkInstall(home);
+        return { mode: blocks.length > 0 || legacy.length > 0 ? 'always-on' : 'invoke-only', blocks, skills, legacy };
     }
     catch {
         return null;
@@ -155,7 +155,18 @@ function integrationSteps(integration, upgrading, env) {
             text: fixBrokenMarkers(b.path, 'hafez upgrade'),
         }));
     }
-    const { blocks, skills } = integration;
+    const { blocks, skills, legacy } = integration;
+    // The 1.x section goes first: the always-on install writes a Block beside
+    // it, and both would be loaded.
+    const removals = legacy.map(l => ({ kind: 'action', text: removeLegacy(l.path, l.line) }));
+    const unblocked = legacy
+        .filter(l => !blocks.some(b => b.harness === l.harness))
+        .map(l => ({ kind: 'command', text: `hafez onboard --install --mode always-on --harness ${l.harness}` }));
+    // With no Block, the always-on install refreshes the skills too.
+    const rest = blocks.length === 0 && legacy.length > 0 ? [] : blockSteps(integration, upgrading, env);
+    return [...removals, ...unblocked, ...rest];
+}
+function blockSteps({ blocks, skills }, upgrading, env) {
     const skillDrift = skills.some(s => s.state === 'stale' || s.state === 'hand-edited');
     const blockDrift = (b) => b.state === 'stale' || (b.state === 'hand-edited' && b.renderChanged);
     const installed = blocks.length > 0 || skills.some(s => s.state !== 'absent');
@@ -168,7 +179,7 @@ function integrationSteps(integration, 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);
@@ -181,7 +192,8 @@ function integrationSteps(integration, 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;
@@ -263,13 +275,15 @@ function integrationLines(integration) {
     if (integration === null)
         return ['Skills and Block: could not be read.'];
     const lines = integration.mode === 'always-on'
-        ? ['Mode: always-on (a Block is installed).']
+        ? [integration.blocks.length > 0 ? 'Mode: always-on (a Block is installed).' : 'Mode: always-on (legacy: a Hafez 1.x section with no markers).']
         : [
             'Mode: invoke-only (no Block in any instructions file Hafez writes); installing a Block is not offered.',
             "A Block pasted into Cursor's User Rules lives in its Settings and is not checked here.",
         ];
     for (const b of integration.blocks)
         lines.push(`- Block in ${b.path}: ${BLOCK_STATE[b.state](b)}`);
+    for (const l of integration.legacy)
+        lines.push(`- ${legacyLine(l.path, l.line)}, from Hafez 1.x, with no markers`);
     for (const s of integration.skills) {
         const lost = s.state === 'hand-edited' ? ' — `onboard --install` replaces it, and the edit is lost' : '';
         lines.push(`- ${s.path}: ${s.state}${lost}`);

package/dist/contracts.js

@@ -195,6 +195,8 @@ export const WRITE_LINE_OMITS = {
         status: 'a lifecycle change, not a write-back: the `hafez` skill\'s rare ops carry the status line',
         agent: 'detected from the Harness; the override is never shown',
         add_action: 'the one-line form of add_actions, written by the same flag',
+        complete_actions: 'the repeated form of complete_action, written by the same flag',
+        remove_actions: 'the repeated form of remove_action, written by the same flag',
         clear_actions: 'drops lines unseen; the Footer drops one line by its Handle',
         description: SET_AT_CREATE,
         resource: SET_AT_CREATE,

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 {};