@jbarket/loomai 0.5.0

package/dist/cli/update.d.ts

@@ -0,0 +1,2 @@
+import type { IOStreams } from './io.js';
+export declare function run(argv: string[], io: IOStreams): Promise<number>;

package/dist/cli/update.js

@@ -0,0 +1,87 @@
+/**
+ * loom update — modify an existing memory.
+ */
+import { parseArgs } from 'node:util';
+import { update } from '../tools/update.js';
+import { createBackend } from '../backends/index.js';
+import { assertStackVersionCompatible } from '../config.js';
+import { extractGlobalFlags, resolveEnv } from './args.js';
+import { readBody, renderJson } from './io.js';
+const USAGE = `Usage: loom update <ref> [options]
+       loom update --category <cat> --title <exact> [options]
+
+Updates content (from stdin or \$EDITOR) and/or metadata on an existing
+memory.
+
+Options:
+  --category <name>      Identify by category (with --title)
+  --title <exact>        Identify by title (with --category)
+  --json                 Emit UpdateResult
+  --context-dir <path>   Agent context dir
+  --help, -h             Show this help
+`;
+export async function run(argv, io) {
+    const { flags: global, rest } = extractGlobalFlags(argv);
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest,
+            options: {
+                category: { type: 'string' },
+                title: { type: 'string' },
+                help: { type: 'boolean', short: 'h' },
+            },
+            strict: true,
+            allowPositionals: true,
+        });
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.values.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    const ref = parsed.positionals[0];
+    const hasIdentifier = ref || (parsed.values.category && parsed.values.title);
+    if (!hasIdentifier) {
+        io.stderr(`Provide a <ref> or --category+--title.\n${USAGE}`);
+        return 2;
+    }
+    const env = resolveEnv(global, io.env);
+    try {
+        assertStackVersionCompatible(env.contextDir);
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    let body;
+    try {
+        body = await readBody(io, 'update');
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    if (!body) {
+        io.stderr(`body cannot be empty\n`);
+        return 2;
+    }
+    const input = {
+        ref,
+        category: parsed.values.category,
+        title: parsed.values.title,
+        content: body,
+    };
+    if (env.json) {
+        const backend = createBackend(env.contextDir);
+        const result = await backend.update(input);
+        renderJson(io, result);
+        return result.updated ? 0 : 3;
+    }
+    const text = await update(env.contextDir, input);
+    io.stdout(text.endsWith('\n') ? text : text + '\n');
+    return /not found/i.test(text) ? 3 : 0;
+}

package/dist/cli/wake.d.ts

@@ -0,0 +1,2 @@
+import type { IOStreams } from './io.js';
+export declare function run(argv: string[], io: IOStreams): Promise<number>;

package/dist/cli/wake.js

@@ -0,0 +1,53 @@
+/**
+ * loom wake — prints agent identity markdown to stdout.
+ */
+import { parseArgs } from 'node:util';
+import { loadIdentity } from '../tools/identity.js';
+import { assertStackVersionCompatible } from '../config.js';
+import { extractGlobalFlags, resolveEnv } from './args.js';
+const USAGE = `Usage: loom wake [options]
+
+Prints the agent's wake output (identity, preferences, self-model,
+harness manifest, model manifest) to stdout.
+
+Options:
+  --project <name>       Load projects/<name>.md as additional context
+  --context-dir <path>   Agent context dir
+  --client <name>        Harness adapter hint
+  --model <name>         Model manifest hint
+  --help, -h             Show this help
+`;
+export async function run(argv, io) {
+    const { flags: global, rest } = extractGlobalFlags(argv);
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: rest,
+            options: {
+                project: { type: 'string' },
+                help: { type: 'boolean', short: 'h' },
+            },
+            strict: true,
+            allowPositionals: false,
+        });
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n${USAGE}`);
+        return 2;
+    }
+    if (parsed.values.help) {
+        io.stdout(USAGE);
+        return 0;
+    }
+    const env = resolveEnv(global, io.env);
+    try {
+        assertStackVersionCompatible(env.contextDir);
+    }
+    catch (err) {
+        io.stderr(`${err.message}\n`);
+        return 1;
+    }
+    const md = await loadIdentity(env.contextDir, parsed.values.project, env.client, env.model);
+    io.stdout(md.endsWith('\n') ? md : md + '\n');
+    return 0;
+}

package/dist/clients.d.ts

@@ -0,0 +1,8 @@
+export declare const TOOLS: string[];
+export declare function getBuiltInAdapter(client: string): string | null;
+/**
+ * Load the adapter for a given client name.
+ * Checks <contextDir>/clients/<client>.md first (user override),
+ * then falls back to the built-in adapter.
+ */
+export declare function loadClientAdapter(contextDir: string, client: string): Promise<string | null>;

package/dist/clients.js

@@ -0,0 +1,63 @@
+/**
+ * Client adapters — runtime-specific context injected into identity loads.
+ *
+ * When `identity` is called with a `client` param (or LOOM_CLIENT env var),
+ * the corresponding adapter is appended to the identity response. This tells
+ * the agent how loom tools are named in its specific runtime.
+ *
+ * Built-in adapters ship with loom. User overrides live in
+ * `<contextDir>/clients/<client>.md` and take precedence.
+ *
+ * Supported clients: claude-code, gemini-cli. Any other runtime can drop a
+ * user override at `<contextDir>/clients/<name>.md`.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { assertSafePathSegment } from './path-safety.js';
+// ─── Tool list ────────────────────────────────────────────────────────────────
+// Canonical tool names — used to generate the prefix-specific list per client
+export const TOOLS = [
+    'identity', 'dossier', 'remember', 'recall', 'update', 'forget',
+    'memory_list', 'memory_prune', 'find_similar', 'memory_audit', 'episodes',
+    'memory_archive', 'memory_restore',
+    'memory_propose', 'memory_proposals', 'memory_ratify', 'memory_reject',
+    'update_identity', 'bootstrap', 'harness_init', 'harness_describe',
+    'knowledge_write', 'knowledge_recall', 'knowledge_maintain',
+    'knowledge_archive', 'knowledge_restore', 'knowledge_supersede', 'knowledge_move', 'knowledge_merge',
+    'knowledge_purge', 'knowledge_verify', 'knowledge_history',
+];
+function toolList(prefix) {
+    return TOOLS.map((t) => `\`${prefix}${t}\``).join(', ');
+}
+// ─── Built-in adapters ────────────────────────────────────────────────────────
+const ADAPTERS = {
+    'claude-code': `## Runtime: Claude Code
+
+You are running in Claude Code (Anthropic CLI). Loom tools use double-underscore prefix:
+${toolList('mcp__loom__')}`,
+    'gemini-cli': `## Runtime: Gemini CLI
+
+You are running in Gemini CLI (Google). Loom tools use double-underscore prefix:
+${toolList('mcp__loom__')}`,
+};
+// ─── Loader ──────────────────────────────────────────────────────────────────
+export function getBuiltInAdapter(client) {
+    return ADAPTERS[client] ?? null;
+}
+/**
+ * Load the adapter for a given client name.
+ * Checks <contextDir>/clients/<client>.md first (user override),
+ * then falls back to the built-in adapter.
+ */
+export async function loadClientAdapter(contextDir, client) {
+    assertSafePathSegment(client, 'client name');
+    const overridePath = join(contextDir, 'clients', `${client}.md`);
+    try {
+        const content = await readFile(overridePath, 'utf-8');
+        return content.trim();
+    }
+    catch {
+        // no override, use built-in
+    }
+    return getBuiltInAdapter(client);
+}

package/dist/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The single canonical helper for the default context path. Every call
+ * site that needs `~/.config/loom/default` must go through this —
+ * no more duplicated literals in config.ts / args.ts / doctor.ts.
+ */
+export declare function resolveDefaultContextPath(home?: string): string;
+export declare function resolveContextDir(): string;
+/**
+ * Throws if the context dir is the default fallback path AND it has no
+ * IDENTITY.md. This is the "fail loud instead of silent fallback" guard —
+ * a blank-identity boot is only permitted when the caller explicitly opted
+ * in via LOOM_CONTEXT_DIR or --context-dir pointing at a real (even empty)
+ * dir. A missing/dangling/empty default must never silently serve a fresh-
+ * agent skeleton.
+ *
+ * @param contextDir  The resolved context dir to validate.
+ * @param defaultPath Override the default path (used in unit tests to avoid
+ *                    depending on the real homedir).
+ */
+export declare function assertContextBootable(contextDir: string, defaultPath?: string): void;
+/**
+ * Resolve the loom repo root from the running module location.
+ * Works from both src/ (dev via tsx) and dist/ (production).
+ */
+export declare function resolveRepoRoot(): string;
+export declare function resolveSqliteDbPath(contextDir: string): string;
+export declare function resolveKnowledgeDbPath(contextDir: string): string;
+/**
+ * Local-only observation logs (e.g. `telemetry/recall.jsonl`). Lives inside
+ * the context dir so it travels with the agent and never leaves the machine.
+ */
+export declare function resolveTelemetryDir(contextDir: string): string;
+/**
+ * Assert that the knowledge database path does not co-locate with the memory
+ * database path. If they resolve to the same file (or inode), throw.
+ */
+export declare function assertKnowledgePathsNotCoLocated(contextDir: string): void;
+export declare function resolveFastEmbedModel(): string;
+export declare function resolveFastEmbedCacheDir(): string | undefined;
+/** The stack schema version this loom build understands. */
+export declare const CURRENT_STACK_VERSION = 2;
+/** The filename at the stack root that records the on-disk schema version. */
+export declare const STACK_VERSION_FILE = "LOOM_STACK_VERSION";
+/**
+ * Read the stack version stamp at `<contextDir>/LOOM_STACK_VERSION`.
+ * Returns null if the file is missing, or NaN if the content doesn't parse.
+ */
+export declare function readStackVersion(contextDir: string): number | null;
+/**
+ * Lazy-write the current stack version if the stamp is missing. Does not
+ * overwrite an existing file; the caller is responsible for validating
+ * (and refusing) versions ahead of CURRENT_STACK_VERSION.
+ */
+export declare function ensureStackVersion(contextDir: string): void;
+/**
+ * Refuse to operate against a stack at a higher version than this build
+ * understands; stamp the current version if the file is missing.
+ */
+export declare function assertStackVersionCompatible(contextDir: string): void;

package/dist/config.js

@@ -0,0 +1,160 @@
+/**
+ * Configuration — resolves directories and backend settings for a
+ * given loom agent.
+ *
+ * The context directory is the agent's brain — everything
+ * agent-specific lives here:
+ *   IDENTITY.md       — the terminal creed (who this agent is)
+ *   preferences.md    — user preferences and working style
+ *   self-model.md     — agent capability tracking
+ *   memories.db       — sqlite + sqlite-vec memory store (pursuits live here too, as category=pursuit)
+ *
+ * Context dir resolution order:
+ *   1. LOOM_CONTEXT_DIR environment variable
+ *   2. --context-dir CLI argument
+ *   3. ~/.config/loom/default (fallback)
+ */
+import { resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { existsSync, readFileSync, writeFileSync, statSync } from 'node:fs';
+/**
+ * The single canonical helper for the default context path. Every call
+ * site that needs `~/.config/loom/default` must go through this —
+ * no more duplicated literals in config.ts / args.ts / doctor.ts.
+ */
+export function resolveDefaultContextPath(home) {
+    return resolve(home ?? homedir(), '.config', 'loom', 'default');
+}
+export function resolveContextDir() {
+    if (process.env.LOOM_CONTEXT_DIR) {
+        return resolve(process.env.LOOM_CONTEXT_DIR);
+    }
+    const argIdx = process.argv.indexOf('--context-dir');
+    if (argIdx !== -1 && process.argv[argIdx + 1]) {
+        return resolve(process.argv[argIdx + 1]);
+    }
+    return resolveDefaultContextPath();
+}
+/**
+ * Throws if the context dir is the default fallback path AND it has no
+ * IDENTITY.md. This is the "fail loud instead of silent fallback" guard —
+ * a blank-identity boot is only permitted when the caller explicitly opted
+ * in via LOOM_CONTEXT_DIR or --context-dir pointing at a real (even empty)
+ * dir. A missing/dangling/empty default must never silently serve a fresh-
+ * agent skeleton.
+ *
+ * @param contextDir  The resolved context dir to validate.
+ * @param defaultPath Override the default path (used in unit tests to avoid
+ *                    depending on the real homedir).
+ */
+export function assertContextBootable(contextDir, defaultPath = resolveDefaultContextPath()) {
+    if (contextDir !== defaultPath)
+        return;
+    if (!existsSync(resolve(contextDir, 'IDENTITY.md'))) {
+        throw new Error('no loom context configured — refusing to serve a blank identity. ' +
+            'Set LOOM_CONTEXT_DIR or run `loom bootstrap` to initialize an agent.');
+    }
+}
+/**
+ * Resolve the loom repo root from the running module location.
+ * Works from both src/ (dev via tsx) and dist/ (production).
+ */
+export function resolveRepoRoot() {
+    const thisFile = fileURLToPath(import.meta.url);
+    return resolve(dirname(thisFile), '..');
+}
+export function resolveSqliteDbPath(contextDir) {
+    return process.env.LOOM_SQLITE_DB_PATH ?? resolve(contextDir, 'memories.db');
+}
+export function resolveKnowledgeDbPath(contextDir) {
+    return process.env.LOOM_KNOWLEDGE_DB_PATH ?? resolve(contextDir, 'knowledge.db');
+}
+/**
+ * Local-only observation logs (e.g. `telemetry/recall.jsonl`). Lives inside
+ * the context dir so it travels with the agent and never leaves the machine.
+ */
+export function resolveTelemetryDir(contextDir) {
+    return resolve(contextDir, 'telemetry');
+}
+/**
+ * Assert that the knowledge database path does not co-locate with the memory
+ * database path. If they resolve to the same file (or inode), throw.
+ */
+export function assertKnowledgePathsNotCoLocated(contextDir) {
+    const memPath = resolveSqliteDbPath(contextDir);
+    const knPath = resolveKnowledgeDbPath(contextDir);
+    if (memPath === knPath) {
+        throw new Error(`Knowledge database path is the same as memory database path (${memPath}). ` +
+            `This violates the isolation invariant. Set LOOM_SQLITE_DB_PATH or LOOM_KNOWLEDGE_DB_PATH to different files.`);
+    }
+    // Also check inode-level co-location (hard links)
+    let memStat = null;
+    let knStat = null;
+    try {
+        memStat = statSync(memPath);
+    }
+    catch {
+        // File doesn't exist yet
+    }
+    try {
+        knStat = statSync(knPath);
+    }
+    catch {
+        // File doesn't exist yet
+    }
+    if (memStat && knStat && memStat.ino === knStat.ino && memStat.dev === knStat.dev) {
+        throw new Error(`Knowledge database (${knPath}) and memory database (${memPath}) ` +
+            `are hard-linked to the same inode (${memStat.ino}). This violates the isolation invariant.`);
+    }
+}
+export function resolveFastEmbedModel() {
+    return process.env.LOOM_FASTEMBED_MODEL ?? 'fast-bge-small-en-v1.5';
+}
+export function resolveFastEmbedCacheDir() {
+    return process.env.LOOM_FASTEMBED_CACHE_DIR || undefined;
+}
+// ─── Stack version ────────────────────────────────────────────────────────────
+/** The stack schema version this loom build understands. */
+export const CURRENT_STACK_VERSION = 2;
+/** The filename at the stack root that records the on-disk schema version. */
+export const STACK_VERSION_FILE = 'LOOM_STACK_VERSION';
+/**
+ * Read the stack version stamp at `<contextDir>/LOOM_STACK_VERSION`.
+ * Returns null if the file is missing, or NaN if the content doesn't parse.
+ */
+export function readStackVersion(contextDir) {
+    const path = resolve(contextDir, STACK_VERSION_FILE);
+    if (!existsSync(path))
+        return null;
+    return Number.parseInt(readFileSync(path, 'utf-8').trim(), 10);
+}
+/**
+ * Lazy-write the current stack version if the stamp is missing. Does not
+ * overwrite an existing file; the caller is responsible for validating
+ * (and refusing) versions ahead of CURRENT_STACK_VERSION.
+ */
+export function ensureStackVersion(contextDir) {
+    const path = resolve(contextDir, STACK_VERSION_FILE);
+    if (existsSync(path))
+        return;
+    writeFileSync(path, `${CURRENT_STACK_VERSION}\n`, 'utf-8');
+}
+/**
+ * Refuse to operate against a stack at a higher version than this build
+ * understands; stamp the current version if the file is missing.
+ */
+export function assertStackVersionCompatible(contextDir) {
+    const onDisk = readStackVersion(contextDir);
+    if (onDisk !== null) {
+        if (Number.isNaN(onDisk)) {
+            throw new Error(`LOOM_STACK_VERSION unparseable at ${contextDir}/${STACK_VERSION_FILE}. ` +
+                `Expected an integer; got raw content.`);
+        }
+        if (onDisk > CURRENT_STACK_VERSION) {
+            throw new Error(`Stack at ${contextDir} is version ${onDisk}; ` +
+                `this loom build understands up to v${CURRENT_STACK_VERSION}. Upgrade loom.`);
+        }
+    }
+    ensureStackVersion(contextDir);
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+declare function isCliInvocation(argv: string[]): boolean;
+export { isCliInvocation };
+/**
+ * True when this module is the process entry point.
+ *
+ * `process.argv[1]` is whatever path the shell invoked, which for every
+ * packaged install (`npm i -g`, `npm link`, `npx`) is a SYMLINK in a bin
+ * directory, while `import.meta.url` always resolves to the real file. A
+ * raw string compare is false in exactly those cases, so `main()` never
+ * runs: no CLI dispatch, no MCP server, exit 0 with no output. Resolve
+ * both sides before comparing.
+ */
+declare function isEntryPoint(): boolean;
+export { isEntryPoint };

package/dist/index.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * Loom — CLI + stdio MCP entry point.
+ *
+ * When argv[2] is a known CLI subcommand or --help/--version, routes to
+ * src/cli/index.ts. Otherwise (or if argv is empty / only flags), falls
+ * through to the MCP stdio server so existing .mcp.json configs keep
+ * working.
+ *
+ * Configure via environment variables:
+ *   LOOM_CONTEXT_DIR         — path to identity/memory directory (required)
+ *   LOOM_SQLITE_DB_PATH      — override memories.db location (optional)
+ *   LOOM_FASTEMBED_MODEL     — embedding model (default fast-bge-small-en-v1.5)
+ *   LOOM_FASTEMBED_CACHE_DIR — ONNX cache (default ~/.cache/loom/fastembed)
+ *   LOOM_CLIENT              — runtime client adapter name (optional)
+ */
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createLoomServer } from './server.js';
+import { resolveContextDir } from './config.js';
+import { SUBCOMMANDS } from './cli/subcommands.js';
+const CLI_KEYWORDS = new Set(SUBCOMMANDS);
+function isCliInvocation(argv) {
+    const first = argv[2];
+    if (first === undefined)
+        return false;
+    if (first === '--help' || first === '-h')
+        return true;
+    if (first === '--version' || first === '-V')
+        return true;
+    return CLI_KEYWORDS.has(first);
+}
+export { isCliInvocation };
+async function main() {
+    if (isCliInvocation(process.argv)) {
+        const { runCli } = await import('./cli/index.js');
+        process.exit(await runCli(process.argv.slice(2)));
+    }
+    const contextDir = resolveContextDir();
+    const { server } = createLoomServer({ contextDir });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+/**
+ * True when this module is the process entry point.
+ *
+ * `process.argv[1]` is whatever path the shell invoked, which for every
+ * packaged install (`npm i -g`, `npm link`, `npx`) is a SYMLINK in a bin
+ * directory, while `import.meta.url` always resolves to the real file. A
+ * raw string compare is false in exactly those cases, so `main()` never
+ * runs: no CLI dispatch, no MCP server, exit 0 with no output. Resolve
+ * both sides before comparing.
+ */
+function isEntryPoint() {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined)
+        return false;
+    const self = fileURLToPath(import.meta.url);
+    if (argv1 === self)
+        return true;
+    try {
+        return realpathSync(argv1) === realpathSync(self);
+    }
+    catch {
+        return false;
+    }
+}
+export { isEntryPoint };
+if (isEntryPoint()) {
+    main().catch((err) => {
+        console.error('Loom failed to start:', err);
+        process.exit(1);
+    });
+}

package/dist/injection/harnesses.d.ts

@@ -0,0 +1,17 @@
+export type HarnessKey = 'claude-code' | 'codex' | 'gemini-cli';
+export interface HarnessPreset {
+    readonly key: HarnessKey;
+    readonly display: string;
+    readonly defaultPath: string;
+    readonly toolPrefix: string;
+}
+export declare const HARNESS_KEYS: readonly HarnessKey[];
+export declare const HARNESSES: Readonly<Record<HarnessKey, HarnessPreset>>;
+export declare function isHarnessKey(s: string): s is HarnessKey;
+/**
+ * Resolve the injection path for a harness given an optional HOME override.
+ * Default path is cached from homedir() at module load; this resolver
+ * lets callers (CLI args, tests passing { HOME }) redirect the base
+ * without mutating the frozen preset.
+ */
+export declare function resolveHarnessPath(harness: HarnessPreset, home?: string): string;

package/dist/injection/harnesses.js

@@ -0,0 +1,51 @@
+/**
+ * Harness preset table for `loom inject`. Each entry names a target
+ * harness, its canonical default path, and the MCP tool prefix to emit
+ * in the injected instruction block.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const HARNESS_KEYS = [
+    'claude-code',
+    'codex',
+    'gemini-cli',
+];
+export const HARNESSES = {
+    'claude-code': {
+        key: 'claude-code',
+        display: 'Claude Code',
+        defaultPath: join(homedir(), '.claude', 'CLAUDE.md'),
+        toolPrefix: 'mcp__loom__',
+    },
+    'codex': {
+        key: 'codex',
+        display: 'Codex',
+        defaultPath: join(homedir(), '.codex', 'AGENTS.md'),
+        toolPrefix: 'mcp__loom__',
+    },
+    'gemini-cli': {
+        key: 'gemini-cli',
+        display: 'Gemini CLI',
+        defaultPath: join(homedir(), '.gemini', 'GEMINI.md'),
+        toolPrefix: 'mcp__loom__',
+    },
+};
+export function isHarnessKey(s) {
+    return HARNESS_KEYS.includes(s);
+}
+/**
+ * Resolve the injection path for a harness given an optional HOME override.
+ * Default path is cached from homedir() at module load; this resolver
+ * lets callers (CLI args, tests passing { HOME }) redirect the base
+ * without mutating the frozen preset.
+ */
+export function resolveHarnessPath(harness, home) {
+    const base = home ?? homedir();
+    if (base === homedir())
+        return harness.defaultPath;
+    switch (harness.key) {
+        case 'claude-code': return join(base, '.claude', 'CLAUDE.md');
+        case 'codex': return join(base, '.codex', 'AGENTS.md');
+        case 'gemini-cli': return join(base, '.gemini', 'GEMINI.md');
+    }
+}

package/dist/injection/render.d.ts

@@ -0,0 +1,17 @@
+import type { HarnessPreset } from './harnesses.js';
+/**
+ * The subset of a harness that rendering actually needs: the tool prefix
+ * (used throughout the block body) and the key (stamped into the start
+ * marker). Widened from HarnessPreset so harness_init can render a block
+ * for a harness name that is not one of the built-in presets.
+ */
+export type RenderableHarness = Pick<HarnessPreset, 'toolPrefix'> & {
+    readonly key: string;
+};
+/**
+ * Compute the truncated SHA-256 that appears in the `<!-- loom:hash … -->`
+ * line. Input is the raw inner content (between start marker and hash line).
+ * Exported so callers can verify a block without re-rendering it.
+ */
+export declare function hashBlockContent(inner: string): string;
+export declare function renderBlock(harness: RenderableHarness, contextDir: string): string;

package/dist/injection/render.js

@@ -0,0 +1,50 @@
+/**
+ * Renders the marker-bounded managed section that `loom inject` writes
+ * into each harness dotfile. Pure: no I/O, no side effects, same input
+ * → same output.
+ *
+ * The block tells the agent *how* to load identity (prefer MCP, fall
+ * back to CLI) — it deliberately does not carry the identity body, so
+ * nothing here goes stale when the stack changes.
+ *
+ * A `<!-- loom:hash <hex> -->` line is embedded immediately before the
+ * end marker. The hex value is a truncated SHA-256 of the inner content
+ * (everything between the start and hash lines). This lets callers and
+ * humans verify at a glance whether the block is intact; harness_init
+ * uses it to detect corruption and reinstall.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * Compute the truncated SHA-256 that appears in the `<!-- loom:hash … -->`
+ * line. Input is the raw inner content (between start marker and hash line).
+ * Exported so callers can verify a block without re-rendering it.
+ */
+export function hashBlockContent(inner) {
+    return createHash('sha256').update(inner, 'utf-8').digest('hex').slice(0, 16);
+}
+export function renderBlock(harness, contextDir) {
+    const p = harness.toolPrefix;
+    // Inner content — everything between the start marker line and the hash line.
+    const inner = `## Persistent identity via loom\n` +
+        `\n` +
+        `You have durable identity and memory managed by loom. On session start,\n` +
+        `load your identity — prefer the MCP tool if available, fall back to the\n` +
+        `CLI if not:\n` +
+        `\n` +
+        `- **MCP (preferred):** call \`${p}identity\`. Also available:\n` +
+        `  \`${p}recall\`, \`${p}remember\`, \`${p}memory_list\`,\n` +
+        `  \`${p}update\`, \`${p}forget\`.\n` +
+        `- **Shell fallback:** run \`loom wake\`. Also: \`loom recall <query>\`,\n` +
+        `  \`echo <body> | loom remember <title> --category <cat>\`,\n` +
+        `  \`loom memory list\`.\n` +
+        `\n` +
+        `Context dir: ${contextDir}\n` +
+        `\n` +
+        `Treat the returned identity as authoritative — it overrides defaults\n` +
+        `where they conflict.\n`;
+    const hash = hashBlockContent(inner);
+    return (`<!-- loom:start v1 harness=${harness.key} -->\n` +
+        inner +
+        `<!-- loom:hash ${hash} -->\n` +
+        `<!-- loom:end -->\n`);
+}