hafez 2.1.0 → 2.3.0

package/dist/surfaces/items.js

@@ -162,6 +162,49 @@ function renderStaleMarker({ stale, age_days }) {
         return '';
     return age_days === null ? ' · stale, undated' : ` · stale ${age_days}d`;
 }
+/** The `read` header line naming the sessions that touched an entity, with
+ * the look back from it. None: no line. */
+function renderSessionsLine({ slug, count, latest }) {
+    if (count === 0)
+        return '';
+    return `sessions: ${count}${latest ? ` · latest ${latest}` : ''} · hafez query --kind session --related-to ${slug}`;
+}
+/** The `read` header line naming an entity's archived log entries, with the
+ * command that reads them. No archive: no line. */
+function renderArchivePointer({ slug, entries }) {
+    if (entries === 0)
+        return '';
+    return `archive: ${entries} older log ${entries === 1 ? 'entry' : 'entries'} · hafez read ${slug} --archive`;
+}
+/** How many children the header lists; the rest are one overflow line. */
+export const CHILDREN_SHOWN = 5;
+/** The `read` header's children block: the count line (children, open
+ * actions across all of them), one `hafez read` line per child (description,
+ * open count, last-touched day) for the first `CHILDREN_SHOWN`, and the
+ * overflow line naming the query that lists the rest. Children arrive sorted
+ * by last-touched descending. No children: no block. */
+function renderChildrenBlock({ slug, children }) {
+    if (children.length === 0)
+        return '';
+    const open = children.reduce((sum, c) => sum + c.open_actions, 0);
+    const shown = children.slice(0, CHILDREN_SHOWN);
+    const width = Math.max(...shown.map(c => c.slug.length));
+    const lines = [`children: ${children.length} · ${open} open action${open === 1 ? '' : 's'}`];
+    for (const c of shown) {
+        const facts = [c.description, `${c.open_actions} open`, c.last_touched].filter(Boolean).join(' · ');
+        lines.push(`  hafez read ${c.slug.padEnd(width)}  ${facts}`);
+    }
+    const rest = children.length - shown.length;
+    if (rest > 0)
+        lines.push(`  … and ${rest} more · hafez query --parent ${slug}`);
+    return lines.join('\n');
+}
+/** The `read` header's fact line for one unsplit prefix family (#230):
+ * its open-line count and the family, and that no child carries it. A
+ * fact, never a filled create line or a question. */
+function renderWorkstreamLine({ prefix, open_actions }) {
+    return `workstream: ${open_actions} open action${open_actions === 1 ? '' : 's'} with \`${prefix}\`; no child named it`;
+}
 /** The line after an update's success while Stale lines remain on the entity. */
 function renderStaleReminder({ handles }) {
     const n = handles.length;
@@ -179,7 +222,10 @@ function renderUpdateMisuse(input) {
 }
 const CREATE_TYPES = ['project', 'entity'];
 const RELATIONS = ['parent', 'related'];
-const createEntityLine = (name) => `hafez create entity "${name}" --type ${oneOf(CREATE_TYPES)} --description "<one sentence>" --brief "<where things stand>" --add-action "<next step>"`;
+/** The entity create line, one text everywhere: the Block, the skill body and
+ * the `read` miss. `--parent` carries the placement rule in its placeholder
+ * (#226, #230); at a miss with nothing read the agent drops it. */
+const createEntityLine = (name) => `hafez create entity "${name}" --type ${oneOf(CREATE_TYPES)} --parent <slug you read, or its parent> --description "<one sentence>" --brief "<where things stand>" --add-action "<next step>"`;
 const CREATE_LINES = fence([
     createEntityLine('<name>'),
     `hafez create knowledge "<name>" --synthesis "<the insight>" --confidence ${oneOf(CONFIDENCE_LEVELS)} --related <slug>`,
@@ -221,6 +267,38 @@ function renderTeachingLines({ harness, mode, line2Only = false }) {
         '4. If a hafez command ever asks for permission, setup is unfinished: run `hafez onboard` again.',
     ].join('\n');
 }
+/** A GitHub `<owner>/<repo>`, as one shell word safe to print in a command
+ * and to name a directory by: not `.` or `..`, not a clone URL's `.git`. */
+export const isVaultRepo = (value) => /^[A-Za-z0-9-]+\/[\w.-]+$/.test(value) && !/\/\.\.?$/.test(value) && !value.endsWith('.git');
+/** Where a cloud container clones a repo attached to the session. */
+const CLOUD_HOME = '/home/user';
+const repoName = (vaultRepo) => vaultRepo.slice(vaultRepo.indexOf('/') + 1);
+/** The Block's self-heal rule in a cloud container: a session started without
+ * the vault attached attaches, clones and registers it (verified, #160). */
+function renderCloudVault(vaultRepo) {
+    const path = `${CLOUD_HOME}/${repoName(vaultRepo)}`;
+    return `If \`hafez init\` shows no registered vault: attach \`${vaultRepo}\` to this session (add_repo, push access), clone it to ${path}, run \`hafez init --register ${path}\`, then continue. Never create a throwaway vault.`;
+}
+/** `onboard --cloud`: the cloud environment's setup script. It cannot clone
+ * (it runs without GitHub credentials) and no step may fail session start: a
+ * failed install exits 0, leaving a session without Hafez rather than none. */
+function renderCloudSetup({ vaultRepo }) {
+    return [
+        `Each Claude Code cloud session is a fresh container: no \`hafez\`, no vault, no Block. Paste this into the cloud environment's Setup script; the Trusted network policy is enough.`,
+        '',
+        fence([
+            '#!/bin/bash',
+            'npm install -g hafez --allow-scripts=better-sqlite3 || exit 0',
+            `VAULT=${CLOUD_HOME}/${repoName(vaultRepo)}`,
+            'if [ -d "$VAULT/.git" ]; then',
+            '  hafez init --register "$VAULT"',
+            'fi',
+            `hafez onboard --install --mode always-on --harness claude-code --vault-repo ${vaultRepo} || true`,
+        ].join('\n')),
+        '',
+        `Attach ${vaultRepo} when you start a session, with push access, and the script registers it. The script cannot clone it: it runs without GitHub credentials. A session started without it attached is told by the Block to attach, clone and register it.`,
+    ].join('\n');
+}
 const BATCH_EXAMPLE_OP = '{"op":"create","kind":"entity","name":"Token Rotation","fields":{"type":"entity"}}';
 export const ITEMS = {
     loadTriggers: {
@@ -259,14 +337,44 @@ export const ITEMS = {
          * in brackets when it has one. */
         render: ({ slug, description }) => description ? `${slug} (${description})` : slug,
     },
+    childrenBlock: {
+        label: 'Children block: the Hub\'s children as read lines',
+        owner: 'readHeader',
+        invokeOnly: 'same',
+        evidence: '#230',
+        render: renderChildrenBlock,
+    },
+    workstreamLine: {
+        label: 'Workstream fact line: an unsplit prefix family',
+        owner: 'readHeader',
+        invokeOnly: 'same',
+        evidence: '#230',
+        render: renderWorkstreamLine,
+    },
+    sessionsLine: {
+        label: 'Sessions line: the look back from an entity',
+        owner: 'readHeader',
+        invokeOnly: 'same',
+        evidence: '#35',
+        render: renderSessionsLine,
+    },
+    archivePointer: {
+        label: 'Archive pointer',
+        owner: 'readHeader',
+        invokeOnly: 'same',
+        evidence: '#34',
+        render: renderArchivePointer,
+    },
     writeTriggers: {
-        label: 'Write triggers: work landed, insight, weighing, "note this"',
+        label: 'Write triggers: work landed, a split, decision made, a lesson, weighing, "note this"',
         owner: 'block',
         invokeOnly: 'absent',
-        evidence: 'M11, M2, never-ask decision #42',
+        evidence: 'M11, M2, never-ask decision #42, decision-record miss #159; placement #226, #229',
         text: place => [
-            '- Work landed (a commit, a merged PR, CI green): update the entity you read. The end of its `read` output shows the command.',
-            `- An insight emerged that is useful beyond this repo: create a knowledge note. ${place('knowledgeBoundary')}`,
+            '- Work landed (a commit, a merged PR, CI green): update the entity that owns the work. That is the entity you read; the entity you read has a child that owns it: write there; the work belongs to another: read that one first. The end of its `read` output shows the command.',
+            '- A workstream your own actions or the user already name, too big for one action, gets a Child with that name under the entity you read: create it with `--parent`, move its open actions there (one `update` on the parent: `--remove-action` each, `--log "decision: split <child> out, open actions moved"`), and write there from now on.',
+            '- A decision was made: one `decision` log entry, now, on the entity that owns the work. The repo keeps its own decisions record: write it there and the log entry points at it (`hafez update <slug> --log "decision: <one line>, see decisions.md"`).',
+            `- A lesson that holds without this entity: create a knowledge note; what we chose is a decision entry, not a note. ${place('knowledgeBoundary')}`,
             '- The user says "note this" or "record that": write it.',
             `- You are weighing whether something is worth writing: write it, as knowledge with \`--confidence ${CONFIDENCE_LEVELS[0]}\`.`,
         ].join('\n'),
@@ -329,7 +437,7 @@ export const ITEMS = {
         owner: 'block',
         fallback: 'hafezSkillBody',
         invokeOnly: 'via the skill body',
-        evidence: 'fields: kind/name 18, synthesis 16, subtype 15',
+        evidence: 'fields: kind/name 18, synthesis 16, subtype 15; --parent #230',
         text: CREATE_LINES + '\n\nA plan is `--subtype plan` without `--synthesis`. Cannot tell entity from knowledge: `hafez capture "<name>"`.',
         /** The entity create line for one name: what the `read` miss places. */
         render: createEntityLine,
@@ -438,12 +546,14 @@ export const ITEMS = {
         evidence: 'help decision #49',
         text: fence([
             `hafez query --filter ${oneOf([...ENTITY_STATUSES, 'stale', 'capture'])}`,
-            'hafez search "<terms>" --kind <entity|knowledge>',
+            'hafez search "<terms>" --kind <entity|knowledge|session|all>',
+            'hafez query --kind session --related-to <slug>',
             'hafez stats',
-        ].join('\n')),
+        ].join('\n'))
+            + '\n\n`search` and `query` reach entities and knowledge notes; `--kind all` adds the session notes, `--kind session` lists them alone, newest first. `hafez read <slug> --archive` prints an entity\'s archived log entries.',
     },
     rareOps: {
-        label: 'Rare ops: promote, link, unlink, status, delete, validate',
+        label: 'Rare ops: promote, link, unlink, status, delete, validate, health',
         owner: 'hafezSkillBody',
         invokeOnly: 'same',
         evidence: 'help decision #49; owner decision #43',
@@ -454,8 +564,20 @@ export const ITEMS = {
             `hafez update <slug> --status ${oneOf(ENTITY_STATUSES)}`,
             'hafez delete <slug>',
             'hafez validate',
+            'hafez health',
         ].join('\n'))
-            + `\n\nA plan's status is \`${PLAN_STATUSES.join('|')}\`. \`delete\` removes a knowledge or session note only; an entity is retired with \`--status done\`.`,
+            + `\n\nA plan's status is \`${PLAN_STATUSES.join('|')}\`. \`delete\` removes a knowledge or session note only; an entity is retired with \`--status done\`. \`health\` lists what placement would change and applies nothing.`,
+    },
+    healthProcedure: {
+        label: 'Health procedure: run with --json, propose by kind, apply nothing unconfirmed',
+        owner: 'hafezSkillBody',
+        invokeOnly: 'same',
+        evidence: '#248; health is agent input, the owner never reads the raw report',
+        text: [
+            'A vault check ("check the vault", "clean up the vault", "what has drifted"): run `hafez health --json` and bring back proposals grouped by kind, never the rows. In a session that read an entity, lead with that entity\'s rows; the rest of the vault as counts.',
+            'One line per kind, with the count: the Workstreams to split (a `create entity … --parent` line each, named as the actions name it); the one-way edges and the unlinked mentions as one `hafez batch` of `link` ops, one commit; the restated decisions and the leakage pairs as a short list for the user to judge, nothing proposed.',
+            'Apply nothing until the user confirms a kind, not even a `link` line that looks safe; then one `batch` per kind.',
+        ].join('\n'),
     },
     batchShape: {
         label: 'Batch shape',
@@ -517,6 +639,22 @@ export const ITEMS = {
         evidence: 'never-ask decision #42; onboard decision #58',
         render: renderHarnessPermissions,
     },
+    cloudVault: {
+        label: 'Cloud session: no vault registered, attach the vault repo, clone, register',
+        owner: 'block',
+        invokeOnly: 'absent',
+        evidence: '#160, verified 2026-10-16',
+        // Placed only in a Block composed for a cloud container, whose begin
+        // marker names the repo (renderBlock).
+        text: (_place, _at, { vaultRepo = '<owner>/<repo>' }) => renderCloudVault(vaultRepo),
+    },
+    cloudSetup: {
+        label: 'The cloud environment\'s setup script',
+        owner: 'onboard',
+        invokeOnly: 'not offered',
+        evidence: '#160, verified 2026-10-16',
+        render: renderCloudSetup,
+    },
     teachingLines: {
         label: 'The four teaching lines (to the user, not the agent)',
         owner: 'onboard',

package/dist/surfaces/surfaces.d.ts

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

package/dist/surfaces/surfaces.js

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

package/dist/templates.d.ts

@@ -11,4 +11,6 @@ export declare function knowledgeBodyTemplate(subtype?: KnowledgeSubtype, fields
  * every other section set, and this renders it. */
 export declare function sessionBodyTemplate(fields?: {
     synthesis?: string;
+    decisions?: string[];
+    entities_touched?: string[];
 }): string;

package/dist/templates.js

@@ -35,5 +35,10 @@ export function knowledgeBodyTemplate(subtype, fields) {
  * structural for Document splitting — so the list lives in contracts with
  * every other section set, and this renders it. */
 export function sessionBodyTemplate(fields) {
-    return render([...SESSION_SECTIONS], { Summary: fields?.synthesis });
+    const bullets = (items) => items?.map(i => `- ${i}`).join('\n');
+    return render([...SESSION_SECTIONS], {
+        Summary: fields?.synthesis,
+        'Entities Touched': bullets(fields?.entities_touched?.map(slug => `[[${slug}]]`)),
+        Decisions: bullets(fields?.decisions),
+    });
 }