hafez 2.0.0 → 2.2.0

package/README.md

@@ -1,5 +1,7 @@
 # Hafez
 
+[![CI](https://github.com/shrvn-r/hafez/actions/workflows/public.yml/badge.svg?branch=main)](https://github.com/shrvn-r/hafez/actions/workflows/public.yml)
+
 **A knowledge and project vault shared between you and your agents.** *Hafez* (حافظ) is Persian for "the keeper — the one who memorizes," after the poet. Plain markdown files you own, backed by SQLite full-text search and git.
 
 ## Why
@@ -77,6 +79,23 @@ plus `--allow-remote=root`, which npm 12+ requires for a remote URL:
 npm install -g https://github.com/shrvn-r/hafez/releases/latest/download/hafez.tgz --allow-scripts=better-sqlite3 --allow-remote=root
 ```
 
+### Cloud sessions
+
+A Claude Code cloud session (claude.ai/code, the mobile app) starts in a fresh
+container: no `hafez`, no vault, no Block. Keep the vault in a private GitHub
+repo and print the environment's setup script for it:
+
+```bash
+hafez onboard --cloud --vault-repo <owner>/<vault-repo>
+```
+
+Paste the script into the cloud environment's Setup script; the Trusted network
+policy is enough. It installs Hafez, registers the vault when it is attached to
+the session, and writes a Block with one rule more: a session started without
+the vault attached attaches it, clones it and registers it, with one approval
+from you. The script never clones the vault itself, because it runs without
+GitHub credentials. Writes push to the vault's `main` like anywhere else.
+
 ## Updating
 
 Tell your agent: **update hafez**. Or paste: "Run `hafez upgrade` and follow
@@ -161,7 +180,7 @@ Three kinds of documents, all markdown + YAML frontmatter:
 
 - **Entities** (`entities/*.md`) — the things you're working on. Types: `capture` (inbox item), `entity` (anything worth tracking), `project` (has outcomes). Statuses: `active | paused | done`. Bodies start from a per-type template (capture: `## Notes`; entity: `## Context`; project: `## Purpose` + `## Goals`) plus a `## Session Log` of dated agent entries; `## Brief` (freeform handoff context) and `## Next Actions` (checkbox list) appear when first written to.
 - **Knowledge** (`knowledge/*.md`) — durable insights that outlive any one project. Subtypes `insight | plan`; confidence levels `observation → pattern → principle` (promoted manually). Bodies hold `## Synthesis`, `## Evidence`, and `## Sources` — evidence accumulates over time via `--add-evidence`.
-- **Sessions** (`sessions/*.md`) — session summaries written via `batch`, kept as history, not indexed.
+- **Sessions** (`sessions/*.md`) — session summaries written at save time, never updated. Readable (`hafez read <slug>`), listed newest first (`hafez query --kind session`), and the look back from an entity (`hafez query --related-to <slug>`); search and query reach them only under `--kind session` or `--kind all`.
 
 Frontmatter at a glance:
 
@@ -181,9 +200,9 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 
 | Command | What it does |
 |---|---|
-| `hafez read <slug> [--depth frontmatter\|summary\|full]` | Read an entity or knowledge note |
-| `hafez query [--filter active\|paused\|done\|stale\|capture\|all] [--type] [--kind entity\|knowledge\|all] [--domain] [--tag] [--parent] [--related-to] [--limit]` | Filter and list |
-| `hafez search <terms> [--kind ...]` | FTS5 full-text search |
+| `hafez read <slug> [--depth frontmatter\|summary\|full] [--archive]` | Read an entity, knowledge or session note; `--archive` an entity's archived log entries |
+| `hafez query [--filter active\|paused\|done\|stale\|capture\|all] [--type] [--kind entity\|knowledge\|session\|all] [--domain] [--tag] [--parent] [--related-to] [--limit]` | Filter and list |
+| `hafez search <terms> [--kind entity\|knowledge\|session\|all]` | FTS5 full-text search (default: entities and knowledge) |
 | `hafez create <entity\|knowledge> <name> [flags]` | Create a document |
 | `hafez capture <name> [--notes]` | Quick inbox capture |
 | `hafez promote <slug> <entity\|project\|knowledge>` | Promote a capture upward |
@@ -197,6 +216,7 @@ Links (`parent`, `related`) are validated — they must point at slugs that exis
 | `hafez validate` / `hafez index rebuild` | Integrity check / rebuild the read index |
 | `hafez onboard` | Setup status, then the script your agent follows: Mode, install, permissions, seeding |
 | `hafez onboard --install --mode <always-on\|invoke-only>` / `--remove` | Write (or remove) the two skills and, always-on, the marked Block in the harness's instructions file |
+| `hafez onboard --cloud --vault-repo <owner>/<repo>` | Print the setup script for Claude Code cloud sessions |
 | `hafez schema [op] [--examples]` | Machine-readable JSON schema for every operation |
 | `hafez export --okf [--out <dir>]` | Read-only OKF v0.1 bundle export |
 

package/dist/apply.d.ts

@@ -1,3 +1,4 @@
+import { type VaultKind } from './vault.js';
 import type { BatchOperation, BatchResult, CreateEntityFields, DeletableKind, CreateKnowledgeFields, KnowledgeSubtype, UpdateFields, UpdateResult } from './types.js';
 export interface AppliedOp {
     filesWritten: string[];
@@ -7,7 +8,7 @@ export interface AppliedOp {
     indexRemovals: string[];
     indexUpserts: Array<{
         slug: string;
-        kind: 'entity' | 'knowledge';
+        kind: VaultKind;
     }>;
     /** Set by the update arm: the line each Next Actions query matched. */
     updateResult?: UpdateResult;

package/dist/apply.js

@@ -18,8 +18,8 @@
 // pure (no filesystem access); the frontmatter builders live here and are
 // exported so the batch validate phase can run them against a simulated vault.
 import { writeFileSync, existsSync, mkdirSync, appendFileSync, unlinkSync } from 'fs';
-import { join, relative, dirname } from 'path';
-import { parseFilePath, serializeFile, slugify, resolveFilePath, kindFromPath, kindDir, archiveLogPath, findVaultFile, vaultFileExists } from './vault.js';
+import { join, dirname } from 'path';
+import { parseFilePath, serializeFile, slugify, resolveFilePath, vaultRel, kindFromPath, kindDir, archiveLogPath, findVaultFile, vaultFileExists } from './vault.js';
 import { validateEntityFrontmatter, validateKnowledgeFrontmatter } from './schema.js';
 import { bodyTemplate, knowledgeBodyTemplate, sessionBodyTemplate } from './templates.js';
 import { formatSessionLogEntry, stampAction, documentFor, documentForFile } from './document.js';
@@ -50,7 +50,7 @@ function entityPath(vaultPath, slug) { return resolveFilePath(vaultPath, slug, '
 function knowledgePath(vaultPath, slug) { return resolveFilePath(vaultPath, slug, 'knowledge'); }
 function today() { return localDay(); }
 // --- Field policy ---
-const ENTITY_ONLY_FIELDS = ['status', 'add_action', 'add_actions', 'complete_action', 'remove_action', 'clear_actions', 'brief', 'current_state', 'session_log', 'agent', 'resource', 'parent'];
+const ENTITY_ONLY_FIELDS = ['status', 'add_action', 'add_actions', 'complete_action', 'complete_actions', 'remove_action', 'remove_actions', 'clear_actions', 'brief', 'current_state', 'session_log', 'agent', 'resource', 'parent'];
 const KNOWLEDGE_ONLY_FIELDS = ['confidence', 'synthesis', 'add_evidence', 'add_source'];
 // An entity-only field is still reachable on a knowledge note when THAT
 // note's contract declares the capability the field needs. The gate asks the
@@ -185,8 +185,8 @@ export function buildKnowledgeFrontmatter(name, kf, existsFn) {
 }
 // The Next Actions fields are the one group in UpdateFields that all touch
 // the same section, so their order within an op IS their meaning. The
-// contract: prune, tick, add — clear_actions → remove_action →
-// complete_action → add_action → add_actions. Every query is resolved
+// contract: prune, tick, add — clear_actions → remove_action(s) →
+// complete_action(s) → add_action → add_actions. Every query is resolved
 // against the list as it stands after the clear and before any edit, so a
 // query never sees a line another field of the same op removed or added;
 // two queries naming one line is a collision, not a silent overwrite. The
@@ -207,27 +207,51 @@ const ARCHIVE_LIMIT = 10;
 function applyNextActionFields(doc, body, fields) {
     const result = {};
     const cleared = fields.clear_actions ? doc.actionLines(body) : [];
-    let removedLine;
     if (fields.clear_actions)
         body = doc.clearNextActions(body);
-    const removed = fields.remove_action !== undefined ? doc.matchNextAction(body, fields.remove_action) : undefined;
-    const completed = fields.complete_action !== undefined ? doc.matchNextAction(body, fields.complete_action) : undefined;
+    const match = (field, query) => ({ field, match: doc.matchNextAction(body, query) });
+    const removes = [
+        ...(fields.remove_action !== undefined ? [match('remove_action', fields.remove_action)] : []),
+        ...(fields.remove_actions ?? []).map(q => match('remove_actions', q)),
+    ];
+    const completes = [
+        ...(fields.complete_action !== undefined ? [match('complete_action', fields.complete_action)] : []),
+        ...(fields.complete_actions ?? []).map(q => match('complete_actions', q)),
+    ];
     // Caller misuse, not a Spine bug: like no-match and ambiguous (matchNextAction),
     // it depends on the list as the earlier ops of a batch leave it, so it is
     // resolved here rather than in the validate phase.
-    if (removed && completed && removed.line === completed.line) {
-        throw new HafezError('VALIDATION_FAILED', `remove_action and complete_action both match "${removed.text}" — one line, one field`);
+    const seen = new Map();
+    for (const { field, match: m } of [...removes, ...completes]) {
+        const first = seen.get(m.line);
+        if (first !== undefined) {
+            throw new HafezError('VALIDATION_FAILED', first === field
+                ? `${field} matches "${m.text}" twice — one line, one query`
+                : `${first} and ${field} both match "${m.text}" — one line, one field`);
+        }
+        seen.set(m.line, field);
+    }
+    // The singular query, when sent, is first in its list; the array form is the rest.
+    const texts = (list) => list.map(q => q.match.text);
+    const removeOffset = fields.remove_action !== undefined ? 1 : 0;
+    const completeOffset = fields.complete_action !== undefined ? 1 : 0;
+    if (removeOffset)
+        result.removed_action = removes[0].match.text;
+    if (fields.remove_actions !== undefined)
+        result.removed_actions = texts(removes.slice(removeOffset));
+    if (completeOffset)
+        result.completed_action = completes[0].match.text;
+    if (fields.complete_actions !== undefined)
+        result.completed_actions = texts(completes.slice(completeOffset));
+    // Every match is a line position in the pre-edit list. A tick leaves every
+    // position where it was; a removal shifts the lines below it — so tick
+    // first, then remove bottom-up. The archive keeps query order.
+    for (const { match: m } of completes)
+        body = doc.completeNextAction(body, m).body;
+    const removed = [];
+    for (const i of removes.map((_, i) => i).sort((x, y) => removes[y].match.line - removes[x].match.line)) {
+        ({ body, line: removed[i] } = doc.removeNextAction(body, removes[i].match));
     }
-    if (removed)
-        result.removed_action = removed.text;
-    if (completed)
-        result.completed_action = completed.text;
-    // Both matches are line positions in the pre-edit list. A tick leaves every
-    // position where it was; a removal shifts the lines below it — so tick first.
-    if (completed)
-        body = doc.completeNextAction(body, completed).body;
-    if (removed)
-        ({ body, line: removedLine } = doc.removeNextAction(body, removed));
     if (fields.add_action !== undefined)
         body = addStampedAction(doc, body, fields.add_action);
     if (fields.add_actions !== undefined) {
@@ -241,7 +265,7 @@ function applyNextActionFields(doc, body, fields) {
     return {
         body: doc.pruneNextActions(overflow.body),
         result,
-        archived: { cleared, removed: removedLine, ticked: [...overflow.lines, ...pruned] },
+        archived: { cleared, removed, ticked: [...overflow.lines, ...pruned] },
     };
 }
 // Pure field application, like every arm above it: the Spine has already run
@@ -317,8 +341,8 @@ function archivedActionEntries(archived) {
         const n = archived.cleared.length;
         entries.push(formatSessionLogEntry({ type: 'progress', agent: 'system', summary: `Cleared ${n} action${plural(n)}`, body: archived.cleared.join('\n') }));
     }
-    if (archived.removed !== undefined) {
-        entries.push(formatSessionLogEntry({ type: 'progress', agent: 'system', summary: 'Removed action', body: archived.removed }));
+    for (const line of archived.removed) {
+        entries.push(formatSessionLogEntry({ type: 'progress', agent: 'system', summary: 'Removed action', body: line }));
     }
     const n = archived.ticked.length;
     if (n > 0) {
@@ -379,9 +403,9 @@ function applyUpdate(op, ctx) {
     // Only the files THIS update wrote. Keying off the archive file merely
     // existing swept any external hand-edit sitting in entities/archive/
     // into an unrelated commit.
-    const files = [relative(vaultPath, filePath)];
+    const files = [vaultRel(vaultPath, filePath)];
     if (wroteArchive)
-        files.push(relative(vaultPath, archivePath));
+        files.push(vaultRel(vaultPath, archivePath));
     return {
         filesWritten: files,
         filesDeleted: [],
@@ -409,7 +433,7 @@ function applyCreateEntity(op, ctx) {
     body = documentFor({ kind: 'entity' }).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
@@ -431,7 +455,7 @@ function applyCreateKnowledge(op, ctx) {
     body = documentFor({ kind: 'knowledge' }).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
@@ -466,15 +490,13 @@ function applyCreateSession(op, ctx) {
     let sessionBody = sessionBodyTemplate({ synthesis: kf.synthesis });
     sessionBody = documentFor({ kind: 'session' }).syncRelatedSection(sessionBody, fm);
     writeFileSync(filePath, serializeFile(fm, sessionBody));
-    // Sessions are not indexed (db.ts only scans entities/ and knowledge/).
-    // They ARE included in git semantic merge (git.ts VAULT_FILE_RE).
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'create', slug, status: 'ok', created: true },
         commitMessage: `create: ${op.name}`,
         indexRemovals: [],
-        indexUpserts: [],
+        indexUpserts: [{ slug, kind: 'session' }],
     };
 }
 function applyCapture(op, ctx) {
@@ -494,7 +516,7 @@ function applyCapture(op, ctx) {
     mkdirSync(join(vaultPath, kindDir('entity')), { recursive: true });
     writeFileSync(filePath, serializeFile(fm, bodyTemplate('capture', { notes: op.notes })));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'capture', slug, status: 'ok', created: true },
         commitMessage: `capture: ${op.name}`,
@@ -521,7 +543,7 @@ function applyLink(op, ctx) {
     body = documentForFile(parsedFile).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'link', slug: op.slug, status: 'ok' },
         commitMessage: `link: ${op.slug} → ${op.target} (${op.relation})`,
@@ -547,7 +569,7 @@ function applyUnlink(op, ctx) {
     body = documentForFile(parsedFile).syncRelatedSection(body, fm);
     writeFileSync(filePath, serializeFile(fm, body));
     return {
-        filesWritten: [relative(vaultPath, filePath)],
+        filesWritten: [vaultRel(vaultPath, filePath)],
         filesDeleted: [],
         result: { op: 'unlink', slug: op.slug, status: 'ok' },
         commitMessage: `unlink: ${op.slug} ✕ ${op.target} (${op.relation})`,
@@ -607,10 +629,10 @@ function applyPromote(op, ctx) {
         catch (err) {
             throw new HafezError('VALIDATION_FAILED', `Failed to promote '${op.slug}' to knowledge: ${err instanceof Error ? err.message : String(err)}`);
         }
-        modifiedFiles.push(relative(vaultPath, newPath));
+        modifiedFiles.push(vaultRel(vaultPath, newPath));
         // The deletion must be staged too — `git add` of a removed path stages
         // the removal; omitting it leaves the vault permanently dirty.
-        deletedFiles.push(relative(vaultPath, filePath));
+        deletedFiles.push(vaultRel(vaultPath, filePath));
     }
     else {
         // Same-kind: capture→entity, capture→project, entity→project
@@ -637,7 +659,7 @@ function applyPromote(op, ctx) {
         }));
         newBody = doc.syncRelatedSection(newBody, fm);
         writeFileSync(filePath, serializeFile(fm, newBody));
-        modifiedFiles.push(relative(vaultPath, filePath));
+        modifiedFiles.push(vaultRel(vaultPath, filePath));
     }
     return {
         filesWritten: modifiedFiles,
@@ -662,11 +684,10 @@ function applyDelete(op, ctx) {
     unlinkSync(filePath);
     return {
         filesWritten: [],
-        filesDeleted: [relative(vaultPath, filePath)],
+        filesDeleted: [vaultRel(vaultPath, filePath)],
         result: { op: 'delete', slug: op.slug, status: 'ok' },
         commitMessage: `delete: ${op.slug} (${kind})`,
-        // Sessions are not indexed; a knowledge row goes with its file.
-        indexRemovals: kind === 'knowledge' ? [op.slug] : [],
+        indexRemovals: [op.slug],
         indexUpserts: [],
         deletedKind: kind,
     };

package/dist/batch-ops.d.ts

@@ -27,7 +27,9 @@ export declare const UpdateFieldsSchema: z.ZodObject<{
     add_action: z.ZodOptional<z.ZodString>;
     add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     complete_action: z.ZodOptional<z.ZodString>;
+    complete_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     remove_action: z.ZodOptional<z.ZodString>;
+    remove_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
     clear_actions: z.ZodOptional<z.ZodBoolean>;
     parent: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -110,7 +112,9 @@ export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         add_action: z.ZodOptional<z.ZodString>;
         add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
         complete_action: z.ZodOptional<z.ZodString>;
+        complete_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
         remove_action: z.ZodOptional<z.ZodString>;
+        remove_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
         clear_actions: z.ZodOptional<z.ZodBoolean>;
         parent: z.ZodOptional<z.ZodString>;
         description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -279,7 +283,9 @@ declare const OP_SPEC_ROWS: readonly [{
             add_action: z.ZodOptional<z.ZodString>;
             add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             complete_action: z.ZodOptional<z.ZodString>;
+            complete_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             remove_action: z.ZodOptional<z.ZodString>;
+            remove_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             clear_actions: z.ZodOptional<z.ZodBoolean>;
             parent: z.ZodOptional<z.ZodString>;
             description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -296,7 +302,7 @@ declare const OP_SPEC_ROWS: readonly [{
             add_source: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>;
     }, z.core.$strict>;
-    readonly description: "Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). Next Actions fields compose within one op as prune, tick, add: `clear_actions` → `remove_action` → `complete_action` → `add_action(s)` — queries match the list as it was before the op (two queries naming one line is an error), added lines land last, so `clear_actions` + `add_actions` rebuilds the list; `clear_actions` with a query field is rejected. Lines leaving the list (removed, cleared, pruned with an emptied section, ticked past nine, oldest first) move to the entity's archive log. A Handle of an open action (as `read` shows it, or any longer or shorter prefix of four or more hex that names only that line) names that line; anything else is a case-insensitive substring of the text. `parent` sets the parent link (entity-only; the slug must exist, and the parent chain must not lead back to the entity). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). An entity update with no `session_log` gets a `progress` entry naming the fields written, unless its only fields are action fields; `agent` names the agent on it (entity-only, detected from the Harness when absent, rejected alongside `session_log`). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.";
+    readonly description: "Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). Next Actions fields compose within one op as prune, tick, add: `clear_actions` → `remove_action(s)` → `complete_action(s)` → `add_action(s)` — queries match the list as it was before the op (two queries naming one line is an error), added lines land last, so `clear_actions` + `add_actions` rebuilds the list; `clear_actions` with a query field is rejected. Lines leaving the list (removed, cleared, pruned with an emptied section, ticked past nine, oldest first) move to the entity's archive log. A Handle of an open action (as `read` shows it, or any longer or shorter prefix of four or more hex that names only that line) names that line; anything else is a case-insensitive substring of the text. `parent` sets the parent link (entity-only; the slug must exist, and the parent chain must not lead back to the entity). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). An entity update with no `session_log` gets a `progress` entry naming the fields written, unless its only fields are action fields; `agent` names the agent on it (entity-only, detected from the Harness when absent, rejected alongside `session_log`). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.";
     readonly exampleInclude: readonly ["status"];
     readonly check: (op: Extract<BatchOperation, {
         op: "update";

package/dist/batch-ops.js

@@ -52,7 +52,9 @@ export const UpdateFieldsSchema = z.object({
     add_action: nonEmptyText.optional(),
     add_actions: z.array(nonEmptyText).optional(),
     complete_action: nonEmptyText.optional(),
+    complete_actions: z.array(nonEmptyText).min(1).optional(),
     remove_action: nonEmptyText.optional(),
+    remove_actions: z.array(nonEmptyText).min(1).optional(),
     clear_actions: z.boolean().optional(),
     parent: z.string().optional(), // entity-only; the slug must exist, no cycle
     // Knowledge metadata
@@ -120,7 +122,7 @@ const CreateSessionBranch = z.object({
 }).strict();
 /** Update fields the mechanised session log neither counts nor names:
  * ticking a box is not history worth an entry, and `agent` only names it. */
-const UNLOGGED_FIELDS = new Set(['add_action', 'add_actions', 'complete_action', 'remove_action', 'clear_actions', 'agent']);
+const UNLOGGED_FIELDS = new Set(['add_action', 'add_actions', 'complete_action', 'complete_actions', 'remove_action', 'remove_actions', 'clear_actions', 'agent']);
 /** The fields an update's mechanised session log entry names — empty when
  * the update earns none. Shared by the update check (which rejects an
  * `agent` with no entry to name) and the Apply update arm (which writes it). */
@@ -262,7 +264,9 @@ export function duplicateSessionWarning(slug) {
  * batch). The builder runs before the claim — it must see the pre-claim
  * world so a self-referencing parent still fails. */
 function claimNew(ctx, errors, slug, info, build) {
-    const taken = ctx.existsAnywhere(slug);
+    // A session note holds its slug too: every kind shares one index row per
+    // slug, so a create must not take one a session already has.
+    const taken = ctx.existsAnywhere(slug) || ctx.sessionExists(slug);
     if (taken)
         errors.push(`Slug '${slug}' already exists`);
     if (build) {
@@ -316,7 +320,7 @@ const OP_SPEC_ROWS = [
         name: 'update',
         op: 'update',
         schema: UpdateBranch,
-        description: 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). Next Actions fields compose within one op as prune, tick, add: `clear_actions` → `remove_action` → `complete_action` → `add_action(s)` — queries match the list as it was before the op (two queries naming one line is an error), added lines land last, so `clear_actions` + `add_actions` rebuilds the list; `clear_actions` with a query field is rejected. Lines leaving the list (removed, cleared, pruned with an emptied section, ticked past nine, oldest first) move to the entity\'s archive log. A Handle of an open action (as `read` shows it, or any longer or shorter prefix of four or more hex that names only that line) names that line; anything else is a case-insensitive substring of the text. `parent` sets the parent link (entity-only; the slug must exist, and the parent chain must not lead back to the entity). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). An entity update with no `session_log` gets a `progress` entry naming the fields written, unless its only fields are action fields; `agent` names the agent on it (entity-only, detected from the Harness when absent, rejected alongside `session_log`). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.',
+        description: 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). Next Actions fields compose within one op as prune, tick, add: `clear_actions` → `remove_action(s)` → `complete_action(s)` → `add_action(s)` — queries match the list as it was before the op (two queries naming one line is an error), added lines land last, so `clear_actions` + `add_actions` rebuilds the list; `clear_actions` with a query field is rejected. Lines leaving the list (removed, cleared, pruned with an emptied section, ticked past nine, oldest first) move to the entity\'s archive log. A Handle of an open action (as `read` shows it, or any longer or shorter prefix of four or more hex that names only that line) names that line; anything else is a case-insensitive substring of the text. `parent` sets the parent link (entity-only; the slug must exist, and the parent chain must not lead back to the entity). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). An entity update with no `session_log` gets a `progress` entry naming the fields written, unless its only fields are action fields; `agent` names the agent on it (entity-only, detected from the Harness when absent, rejected alongside `session_log`). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.',
         exampleInclude: ['status'],
         check(op, ctx) {
             const errors = [];
@@ -341,9 +345,9 @@ const OP_SPEC_ROWS = [
             // only — on a knowledge note validateKindFields has already rejected
             // the fields themselves, and a second error about their order is noise.
             if (target?.kind === 'entity' && op.fields.clear_actions) {
-                const queries = ['remove_action', 'complete_action'].filter(f => op.fields[f] !== undefined);
+                const queries = ['remove_action', 'remove_actions', 'complete_action', 'complete_actions'].filter(f => op.fields[f] !== undefined);
                 if (queries.length > 0) {
-                    errors.push(`clear_actions empties the list before ${queries.join(' and ')} would run — drop the clear or use a separate op`);
+                    errors.push(`clear_actions empties the list before ${queries.slice(0, -1).join(', ')}${queries.length > 1 ? ' and ' : ''}${queries.at(-1)} would run — drop the clear or use a separate op`);
                 }
             }
             // `agent` names the entry the Spine adds; with nothing added it would be

package/dist/cli/block-hook.js

@@ -26,11 +26,16 @@ export async function blockHook(ctx) {
         // leave an index file in it.
         if (typeof vaultPath !== 'string' || !isVault(vaultPath))
             return null;
-        const cwd = realpathSync(ctx.cwd ?? process.cwd());
+        const dir = ctx.cwd ?? process.cwd();
+        // A deleted working directory: no folder to match.
+        if (!existsSync(dir))
+            return null;
+        const cwd = canonical(dir);
         const folders = foldersOf(cwd);
         const remotes = remoteUrls(cwd);
         const { createHafez } = await import('../index.js');
-        const { items } = await createHafez({ vaultPath, git: { push: false } }).query({ filter: 'all' });
+        const os = createHafez({ vaultPath, git: { push: false } });
+        const { items } = await os.query({ filter: 'all' }).finally(() => os.close());
         const matches = items
             .filter(e => folders.some(f => basename(f) === e.slug) || (e.resource !== null && resourceMatches(e.resource, folders, remotes)))
             // Active first: the status tuple is ordered active, paused, done.
@@ -59,13 +64,25 @@ function foldersOf(cwd) {
     const [top, common] = out?.split('\n') ?? [];
     // Before git 2.31 `--path-format` is echoed back, not obeyed: no git root.
     if (top && common && isAbsolute(top) && isAbsolute(common)) {
-        folders.push(top);
+        const root = canonical(top);
+        folders.push(root);
         // A linked worktree shares the main checkout's `.git` as its common dir.
-        if (basename(common) === '.git' && dirname(common) !== top)
-            folders.push(dirname(common));
+        // The shape is read off git's own path: a symlinked `.git` resolves to a
+        // directory with some other name.
+        const main = canonical(dirname(common));
+        if (basename(common) === '.git' && main !== root)
+            folders.push(main);
     }
     return [...new Set(folders)];
 }
+/** One spelling per folder, so paths from git, the working directory and a
+ * `resource` compare equal: git prints `C:/…` on Windows, realpath `C:\…`.
+ * The native realpath, since only it returns the filesystem's own letter case
+ * (`c:\users\…` is `C:\Users\…`) and long names for 8.3 ones. */
+function canonical(path) {
+    const abs = resolve(path);
+    return existsSync(abs) ? realpathSync.native(abs) : abs;
+}
 /** Every remote's URL, normalised. */
 function remoteUrls(cwd) {
     const out = git(cwd, 'config', '--get-regexp', '^remote\\..*\\.url$');
@@ -82,9 +99,7 @@ function normaliseUrl(url) {
         .replace(/\.git$/, '');
 }
 function resourceMatches(resource, folders, remotes) {
-    if (isAbsolute(resource)) {
-        const path = resolve(resource);
-        return folders.includes(existsSync(path) ? realpathSync(path) : path);
-    }
+    if (isAbsolute(resource))
+        return folders.includes(canonical(resource));
     return remotes.includes(normaliseUrl(resource));
 }

package/dist/cli/commands.d.ts

@@ -9,7 +9,7 @@ export interface CommandOpts {
 export declare function cmdRead(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 /** Every flag the query parser accepts, for the branch-support matrix. */
 export declare const QUERY_FLAG_NAMES: string[];
-export type QueryBranch = 'entity' | 'knowledge' | 'all' | 'related-to';
+export type QueryBranch = 'entity' | 'knowledge' | 'session' | 'all' | 'related-to';
 /** Which flags each kind branch actually applies. A branch that cannot honour
  * a flag rejects it (below) instead of dropping it: `--kind knowledge --filter
  * stale` used to return every knowledge note with exit 0, and `--confidence`