@jitsusama/agentic-harness.core 0.1.0

package/dist/memory/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public API for the `memory` domain: durable, scoped facts with
+ * lifecycle-based retention, not age-based eviction.
+ *
+ * Deliberately not exported here: resolving which scope currently
+ * applies (see scope.ts) and presentation (formatting facts for a
+ * particular host's reply shape is the adapter's job).
+ */
+export { memoryDbPath } from "./paths.js";
+export { serializeScope } from "./scope.js";
+export { openMemoryStore } from "./store.js";
+export type { Fact, FactStatus, MemoryStore, RecallQuery, RetainInput, Scope, } from "./types.js";

package/dist/memory/index.js

@@ -0,0 +1,11 @@
+/**
+ * Public API for the `memory` domain: durable, scoped facts with
+ * lifecycle-based retention, not age-based eviction.
+ *
+ * Deliberately not exported here: resolving which scope currently
+ * applies (see scope.ts) and presentation (formatting facts for a
+ * particular host's reply shape is the adapter's job).
+ */
+export { memoryDbPath } from "./paths.js";
+export { serializeScope } from "./scope.js";
+export { openMemoryStore } from "./store.js";

package/dist/memory/paths.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where the shared memory database lives on disk.
+ *
+ * Deliberately one location for every adapter, not one per
+ * adapter: a fact retained while working through pi should be
+ * recallable when the same project is later worked on through
+ * Claude Code, and the reverse. The schema lives here in core, so
+ * there is exactly one schema in play regardless of which adapter
+ * opens the file, pinned by whatever core version each adapter's
+ * own lockfile resolves to.
+ *
+ * This intentionally does not reuse pi's own XDG path (which
+ * scopes everything pi stores under an `agentic-harness.pi`
+ * brand): that brand means "belongs to pi", and a store two
+ * adapters write to belongs to neither. Pi's own memory-integration
+ * extension points here instead, once it exists.
+ */
+/** The memory database path, creating its parent directory if needed. */
+export declare function memoryDbPath(): Promise<string>;

package/dist/memory/paths.js

@@ -0,0 +1,33 @@
+/**
+ * Where the shared memory database lives on disk.
+ *
+ * Deliberately one location for every adapter, not one per
+ * adapter: a fact retained while working through pi should be
+ * recallable when the same project is later worked on through
+ * Claude Code, and the reverse. The schema lives here in core, so
+ * there is exactly one schema in play regardless of which adapter
+ * opens the file, pinned by whatever core version each adapter's
+ * own lockfile resolves to.
+ *
+ * This intentionally does not reuse pi's own XDG path (which
+ * scopes everything pi stores under an `agentic-harness.pi`
+ * brand): that brand means "belongs to pi", and a store two
+ * adapters write to belongs to neither. Pi's own memory-integration
+ * extension points here instead, once it exists.
+ */
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/** Honours XDG_STATE_HOME; falls back to ~/.local/state per the XDG spec. */
+function xdgStateRoot() {
+    const override = process.env.XDG_STATE_HOME;
+    return override && override.length > 0
+        ? override
+        : join(homedir(), ".local", "state");
+}
+/** The memory database path, creating its parent directory if needed. */
+export async function memoryDbPath() {
+    const path = join(xdgStateRoot(), "agentic-harness", "memory", "memory.db");
+    await mkdir(dirname(path), { recursive: true });
+    return path;
+}

package/dist/memory/scope.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Scope serialization. A fact's scope is stored as a single
+ * string key so recall is a plain lookup; this is the only
+ * place that shape is minted.
+ *
+ * Deliberately not here: resolving *which* scope currently
+ * applies. Pi derives that from its own session log (the loaded
+ * quest, or the project at ctx.cwd); a host with no quest system
+ * has nothing equivalent to derive from. Each adapter decides its
+ * own current scope and passes the resulting `Scope` value in.
+ */
+import type { Scope } from "./types.js";
+/** The canonical string key for a scope. */
+export declare function serializeScope(scope: Scope): string;

package/dist/memory/scope.js

@@ -0,0 +1,22 @@
+/**
+ * Scope serialization. A fact's scope is stored as a single
+ * string key so recall is a plain lookup; this is the only
+ * place that shape is minted.
+ *
+ * Deliberately not here: resolving *which* scope currently
+ * applies. Pi derives that from its own session log (the loaded
+ * quest, or the project at ctx.cwd); a host with no quest system
+ * has nothing equivalent to derive from. Each adapter decides its
+ * own current scope and passes the resulting `Scope` value in.
+ */
+/** The canonical string key for a scope. */
+export function serializeScope(scope) {
+    switch (scope.kind) {
+        case "global":
+            return "global";
+        case "project":
+            return `project:${scope.path}`;
+        case "quest":
+            return `quest:${scope.id}`;
+    }
+}

package/dist/memory/store.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SQLite-backed memory store.
+ *
+ * Facts are keyed by a serialized scope so recall is a plain
+ * lookup. Retention is by lifecycle, never by age: a fact
+ * leaves recall only when invalidated, when its scope is
+ * concluded, or never. The store is its own database file,
+ * separate from any other structured store an adapter keeps.
+ */
+import type { MemoryStore } from "./types.js";
+/** Open (and migrate) a memory store at the given path. */
+export declare function openMemoryStore(dbPath: string): Promise<MemoryStore>;

package/dist/memory/store.js

@@ -0,0 +1,146 @@
+/**
+ * SQLite-backed memory store.
+ *
+ * Facts are keyed by a serialized scope so recall is a plain
+ * lookup. Retention is by lifecycle, never by age: a fact
+ * leaves recall only when invalidated, when its scope is
+ * concluded, or never. The store is its own database file,
+ * separate from any other structured store an adapter keeps.
+ */
+import { openDb } from "../internal/sqlite/db.js";
+import { serializeScope } from "./scope.js";
+/** Default number of facts a single recall returns. */
+const DEFAULT_RECALL_LIMIT = 20;
+function rowToFact(row) {
+    return {
+        id: row.id,
+        scope: row.scope,
+        text: row.text,
+        tags: JSON.parse(row.tags),
+        ...(row.source ? { source: row.source } : {}),
+        status: row.status,
+        createdAt: row.created_at,
+        recalledCount: row.recalled_count,
+        ...(row.last_recalled_at !== null
+            ? { lastRecalledAt: row.last_recalled_at }
+            : {}),
+    };
+}
+/** Open (and migrate) a memory store at the given path. */
+export async function openMemoryStore(dbPath) {
+    const db = await openDb(dbPath);
+    await db.exec(`
+		CREATE TABLE IF NOT EXISTS facts (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			scope TEXT NOT NULL,
+			text TEXT NOT NULL,
+			tags TEXT NOT NULL DEFAULT '[]',
+			source TEXT,
+			status TEXT NOT NULL DEFAULT 'active',
+			created_at INTEGER NOT NULL,
+			recalled_count INTEGER NOT NULL DEFAULT 0,
+			last_recalled_at INTEGER
+		);
+		CREATE INDEX IF NOT EXISTS facts_scope_status ON facts (scope, status);
+	`);
+    const factById = async (id) => {
+        const rows = await db.all("SELECT * FROM facts WHERE id = ?", [
+            id,
+        ]);
+        return rows[0] ? rowToFact(rows[0]) : null;
+    };
+    const api = {
+        async retain(input) {
+            const scope = serializeScope(input.scope);
+            const now = Date.now();
+            await db.run("INSERT INTO facts (scope, text, tags, source, status, created_at) VALUES (?, ?, ?, ?, 'active', ?)", [
+                scope,
+                input.text,
+                JSON.stringify(input.tags ?? []),
+                input.source ?? null,
+                now,
+            ]);
+            const rows = await db.all("SELECT * FROM facts WHERE scope = ? ORDER BY id DESC LIMIT 1", [scope]);
+            return rowToFact(rows[0]);
+        },
+        async recall(query) {
+            const scopes = [serializeScope(query.scope)];
+            if (query.includeGlobal !== false && query.scope.kind !== "global") {
+                scopes.push("global");
+            }
+            const placeholders = scopes.map(() => "?").join(", ");
+            const params = [...scopes];
+            let where = `status = 'active' AND scope IN (${placeholders})`;
+            if (query.text) {
+                where += " AND (text LIKE ? OR tags LIKE ?)";
+                params.push(`%${query.text}%`, `%${query.text}%`);
+            }
+            const limit = query.limit ?? DEFAULT_RECALL_LIMIT;
+            params.push(limit);
+            const rows = await db.all(`SELECT * FROM facts WHERE ${where} ORDER BY recalled_count DESC, created_at DESC LIMIT ?`, params);
+            if (rows.length > 0) {
+                const now = Date.now();
+                await db.run(`UPDATE facts SET recalled_count = recalled_count + 1, last_recalled_at = ? WHERE id IN (${rows
+                    .map(() => "?")
+                    .join(", ")})`, [now, ...rows.map((r) => r.id)]);
+            }
+            // Reflect the bumped stats in what we hand back.
+            return rows.map((r) => rowToFact({
+                ...r,
+                recalled_count: r.recalled_count + 1,
+                last_recalled_at: Date.now(),
+            }));
+        },
+        async reflect(query) {
+            const facts = await api.recall({ scope: query.scope });
+            if (facts.length === 0)
+                return "No remembered facts for this scope.";
+            const lines = facts.map((f) => `- ${f.text}`).join("\n");
+            return `Remembered facts relevant to "${query.question}":\n${lines}`;
+        },
+        async edit(id, patch) {
+            const sets = [];
+            const params = [];
+            if (patch.text !== undefined) {
+                sets.push("text = ?");
+                params.push(patch.text);
+            }
+            if (patch.tags !== undefined) {
+                sets.push("tags = ?");
+                params.push(JSON.stringify(patch.tags));
+            }
+            if (sets.length === 0)
+                return factById(id);
+            params.push(id);
+            await db.run(`UPDATE facts SET ${sets.join(", ")} WHERE id = ?`, params);
+            return factById(id);
+        },
+        async invalidate(id) {
+            await db.run("UPDATE facts SET status = 'invalidated' WHERE id = ?", [
+                id,
+            ]);
+        },
+        async concludeScope(scope, mode) {
+            const key = serializeScope(scope);
+            const before = await db.all("SELECT COUNT(*) AS n FROM facts WHERE scope = ? AND status = 'active'", [key]);
+            if (mode === "drop") {
+                await db.run("DELETE FROM facts WHERE scope = ?", [key]);
+            }
+            else {
+                await db.run("UPDATE facts SET status = 'archived' WHERE scope = ? AND status = 'active'", [key]);
+            }
+            return before[0]?.n ?? 0;
+        },
+        async weakestBeyondCap(scope, cap) {
+            const key = serializeScope(scope);
+            const rows = await db.all("SELECT * FROM facts WHERE scope = ? AND status = 'active' ORDER BY recalled_count ASC, created_at ASC", [key]);
+            if (rows.length <= cap)
+                return [];
+            return rows.slice(0, rows.length - cap).map(rowToFact);
+        },
+        async close() {
+            await db.close();
+        },
+    };
+    return api;
+}

package/dist/memory/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Types for cross-session memory: durable facts scoped to a
+ * quest, a project, or globally, with lifecycle-based
+ * retention rather than age-based eviction.
+ */
+/** Where a fact applies. Recall widens a quest or project scope to include global. */
+export type Scope = {
+    readonly kind: "global";
+} | {
+    readonly kind: "project";
+    readonly path: string;
+} | {
+    readonly kind: "quest";
+    readonly id: string;
+};
+/** A fact's lifecycle status. Only active facts are recalled. */
+export type FactStatus = "active" | "invalidated" | "archived";
+/** A durable, scoped fact the agent chose to remember. */
+export interface Fact {
+    readonly id: number;
+    /** Serialized scope key (see serializeScope). */
+    readonly scope: string;
+    readonly text: string;
+    readonly tags: readonly string[];
+    readonly source?: string;
+    readonly status: FactStatus;
+    readonly createdAt: number;
+    readonly recalledCount: number;
+    readonly lastRecalledAt?: number;
+}
+/** Input to retain a new fact. */
+export interface RetainInput {
+    readonly scope: Scope;
+    readonly text: string;
+    readonly tags?: readonly string[];
+    readonly source?: string;
+}
+/** A recall query: facts in a scope, optionally keyword-filtered. */
+export interface RecallQuery {
+    readonly scope: Scope;
+    /** Keyword or tag substring to match. Omit for all facts in scope. */
+    readonly text?: string;
+    /** Widen to include global facts. Defaults to true. */
+    readonly includeGlobal?: boolean;
+    /** Maximum facts to return. Defaults to a small budget. */
+    readonly limit?: number;
+}
+/** The memory store's public surface. */
+export interface MemoryStore {
+    /** Store a durable fact and return it. */
+    retain(input: RetainInput): Promise<Fact>;
+    /** Recall active facts for a scope, bumping their recall stats. */
+    recall(query: RecallQuery): Promise<Fact[]>;
+    /** Synthesize a short answer over the facts matching a scope. */
+    reflect(query: {
+        scope: Scope;
+        question: string;
+    }): Promise<string>;
+    /** Amend a fact's text or tags. Returns the updated fact, or null. */
+    edit(id: number, patch: {
+        text?: string;
+        tags?: readonly string[];
+    }): Promise<Fact | null>;
+    /** Retire a fact so it is never recalled again. */
+    invalidate(id: number): Promise<void>;
+    /**
+     * Archive or drop every fact in a scope, for when the scope's
+     * owner (a quest, say) concludes or retires. Returns the count
+     * affected.
+     */
+    concludeScope(scope: Scope, mode: "archive" | "drop"): Promise<number>;
+    /**
+     * The weakest active facts in a scope beyond a soft cap
+     * (least recalled, oldest first), surfaced for curation. Never
+     * deletes; a true old fact is never silently evicted.
+     */
+    weakestBeyondCap(scope: Scope, cap: number): Promise<Fact[]>;
+    /** Close the underlying database. */
+    close(): Promise<void>;
+}

package/dist/memory/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for cross-session memory: durable facts scoped to a
+ * quest, a project, or globally, with lifecycle-based
+ * retention rather than age-based eviction.
+ */
+export {};

package/dist/notes/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Public types for the notes library.
+ *
+ * A note is a flat, self-contained directory --
+ * `NOTE-<created-date>-<suffix>/README.md` plus whatever
+ * attachments sit alongside it -- living directly under a
+ * notes root with no folder-per-topic nesting. Unlike a
+ * quest, a note owns no child documents of different kinds;
+ * it is a single leaf. Hierarchy, where it's real, is a
+ * `parent` front-matter link to another note's id, the same
+ * way quest hierarchy is a link rather than directory
+ * nesting -- see `internal/notes/discovery.ts`.
+ */
+/**
+ * The note's kind: a small, fixed vocabulary, not a
+ * subject. Subject-level detail belongs in `tags`. This is
+ * deliberately narrow -- a note's type rarely needs to grow
+ * new values, and an open vocabulary would just become an
+ * uncontrolled tag by another name.
+ */
+export type NoteType = "journal" | "reference" | "faith" | "financial" | "gaming" | "travel" | "writing" | "inbox";
+export declare const NOTE_TYPES: NoteType[];
+/**
+ * A note's front matter, as read from and written to its
+ * README.md. `created`/`updated` are free-form timestamp
+ * strings (whatever the note's original source recorded,
+ * typically `YYYYMMDDTHHMMSSZ`) rather than a parsed `Date`
+ * -- the library never needs to do arithmetic on them, only
+ * compare and display, and round-tripping the original text
+ * exactly avoids a whole class of timezone-shift bugs a
+ * parse/reformat cycle would invite.
+ */
+export interface NoteFrontMatter {
+    id: string;
+    type: NoteType;
+    title: string;
+    created: string;
+    updated: string;
+    /** Empty when the note carries no tags, never omitted. */
+    tags: string[];
+    /** Another note's id. Absent for the (common) case of no parent. */
+    parent?: string;
+    /** Where the note originally came from (an import source, a clip source, etc.). */
+    source?: string;
+}
+/** A note as read from disk: its parsed front matter plus its body text. */
+export interface NoteDoc {
+    frontMatter: NoteFrontMatter;
+    body: string;
+}

package/dist/notes/types.js

@@ -0,0 +1,23 @@
+/**
+ * Public types for the notes library.
+ *
+ * A note is a flat, self-contained directory --
+ * `NOTE-<created-date>-<suffix>/README.md` plus whatever
+ * attachments sit alongside it -- living directly under a
+ * notes root with no folder-per-topic nesting. Unlike a
+ * quest, a note owns no child documents of different kinds;
+ * it is a single leaf. Hierarchy, where it's real, is a
+ * `parent` front-matter link to another note's id, the same
+ * way quest hierarchy is a link rather than directory
+ * nesting -- see `internal/notes/discovery.ts`.
+ */
+export const NOTE_TYPES = [
+    "journal",
+    "reference",
+    "faith",
+    "financial",
+    "gaming",
+    "travel",
+    "writing",
+    "inbox",
+];

package/dist/notes/verbs/create.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `notes create`: mint a fresh note.
+ */
+import { type NoteResult, type NoteToolParams } from "./shared.js";
+export declare function create(notesRoot: string, params: NoteToolParams): NoteResult;

package/dist/notes/verbs/create.js

@@ -0,0 +1,55 @@
+/**
+ * `notes create`: mint a fresh note.
+ */
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { discoverNotes } from "../../internal/notes/discovery.js";
+import { serializeNote } from "../../internal/notes/frontmatter.js";
+import { mintIdFromDateString } from "../../internal/notes/id.js";
+import { atomicWriteFile } from "../../internal/notes/io.js";
+import { isNoteType, ok, refuse, } from "./shared.js";
+export function create(notesRoot, params) {
+    const title = params.title?.trim();
+    if (!title)
+        return refuse("create needs a title");
+    if (!params.type)
+        return refuse("create needs a type");
+    if (!isNoteType(params.type)) {
+        return refuse(`type must be one of: journal, reference, faith, financial, gaming, travel, writing, inbox (got "${params.type}")`);
+    }
+    const { index } = discoverNotes(notesRoot);
+    const now = new Date()
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\.\d+Z$/, "Z");
+    const created = params.created ?? now;
+    let id;
+    do {
+        id = mintIdFromDateString(created);
+    } while (index.notes.has(id));
+    if (params.parent) {
+        if (!index.notes.has(params.parent)) {
+            return refuse(`no note matches parent "${params.parent}"`);
+        }
+    }
+    const tags = params.tags
+        ? params.tags
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean)
+        : [];
+    const frontMatter = {
+        id,
+        type: params.type,
+        title,
+        created,
+        updated: now,
+        tags,
+    };
+    if (params.parent)
+        frontMatter.parent = params.parent;
+    const noteDir = join(notesRoot, id);
+    mkdirSync(noteDir, { recursive: true });
+    atomicWriteFile(join(noteDir, "README.md"), serializeNote(frontMatter, `\n# ${title}\n`));
+    return ok(id, { id, type: frontMatter.type, title });
+}

package/dist/notes/verbs/mutate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `notes retype` / `notes retitle` / `notes tag` / `notes reparent`.
+ */
+import { type NoteResult, type NoteToolParams } from "./shared.js";
+export declare function retype(notesRoot: string, params: NoteToolParams): NoteResult;
+export declare function retitle(notesRoot: string, params: NoteToolParams): NoteResult;
+export declare function tag(notesRoot: string, params: NoteToolParams): NoteResult;
+export declare function reparent(notesRoot: string, params: NoteToolParams): NoteResult;

package/dist/notes/verbs/mutate.js

@@ -0,0 +1,152 @@
+/**
+ * `notes retype` / `notes retitle` / `notes tag` / `notes reparent`.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { discoverNotes, } from "../../internal/notes/discovery.js";
+import { parseNoteFrontMatter, serializeNote, } from "../../internal/notes/frontmatter.js";
+import { atomicWriteFile } from "../../internal/notes/io.js";
+import { resolveId } from "./queries.js";
+import { isNoteType, ok, refuse, } from "./shared.js";
+function loadForWrite(notesRoot, id) {
+    const path = join(notesRoot, id, "README.md");
+    const text = readFileSync(path, "utf8");
+    const parsed = parseNoteFrontMatter(text);
+    if (!parsed)
+        return undefined;
+    return { path, ...parsed };
+}
+export function retype(notesRoot, params) {
+    if (!params.id)
+        return refuse("retype needs an id");
+    if (!params.type)
+        return refuse("retype needs a type");
+    if (!isNoteType(params.type)) {
+        return refuse(`type must be one of: journal, reference, faith, financial, gaming, travel, writing, inbox (got "${params.type}")`);
+    }
+    const { index } = discoverNotes(notesRoot);
+    const resolved = resolveId(index, params.id);
+    if ("error" in resolved)
+        return refuse(resolved.error);
+    const loaded = loadForWrite(notesRoot, resolved.id);
+    if (!loaded)
+        return refuse(`could not read ${resolved.id}`);
+    loaded.frontMatter.type = params.type;
+    atomicWriteFile(loaded.path, serializeNote(loaded.frontMatter, loaded.body));
+    return ok(`${resolved.id}: type -> ${params.type}`, {
+        id: resolved.id,
+        type: params.type,
+    });
+}
+/**
+ * A note's body opens with `# <title>`, an echo of the same
+ * front-matter field, not independent content -- kept in
+ * sync on retitle rather than left stale. Only the heading
+ * line itself is replaced; the blank line separating it from
+ * the rest of the body is preserved untouched, since a
+ * regex greedy enough to also consume trailing whitespace
+ * collapses that separator (caught the hard way once
+ * already, when a Python prototype of this tool did exactly
+ * that across every note it retitled in one pass).
+ */
+function retitleHeading(body, oldTitle, newTitle) {
+    const escaped = oldTitle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const headingRe = new RegExp(`^# ${escaped} *$`, "m");
+    return body.replace(headingRe, `# ${newTitle}`);
+}
+export function retitle(notesRoot, params) {
+    if (!params.id)
+        return refuse("retitle needs an id");
+    if (!params.title?.trim())
+        return refuse("retitle needs a title");
+    const { index } = discoverNotes(notesRoot);
+    const resolved = resolveId(index, params.id);
+    if ("error" in resolved)
+        return refuse(resolved.error);
+    const loaded = loadForWrite(notesRoot, resolved.id);
+    if (!loaded)
+        return refuse(`could not read ${resolved.id}`);
+    const newTitle = params.title.trim();
+    const newBody = retitleHeading(loaded.body, loaded.frontMatter.title, newTitle);
+    loaded.frontMatter.title = newTitle;
+    atomicWriteFile(loaded.path, serializeNote(loaded.frontMatter, newBody));
+    return ok(`${resolved.id}: title -> "${newTitle}"`, {
+        id: resolved.id,
+        title: newTitle,
+    });
+}
+export function tag(notesRoot, params) {
+    if (!params.id)
+        return refuse("tag needs an id");
+    const { index } = discoverNotes(notesRoot);
+    const resolved = resolveId(index, params.id);
+    if ("error" in resolved)
+        return refuse(resolved.error);
+    const loaded = loadForWrite(notesRoot, resolved.id);
+    if (!loaded)
+        return refuse(`could not read ${resolved.id}`);
+    let tags = [...loaded.frontMatter.tags];
+    if (params.add) {
+        for (const t of params.add.split(",")) {
+            const trimmed = t.trim();
+            if (trimmed && !tags.includes(trimmed))
+                tags.push(trimmed);
+        }
+    }
+    if (params.remove) {
+        const toRemove = new Set(params.remove.split(",").map((t) => t.trim()));
+        tags = tags.filter((t) => !toRemove.has(t));
+    }
+    loaded.frontMatter.tags = tags;
+    atomicWriteFile(loaded.path, serializeNote(loaded.frontMatter, loaded.body));
+    return ok(`${resolved.id}: tags -> [${tags.join(", ")}]`, {
+        id: resolved.id,
+        tags,
+    });
+}
+/** Is `candidate` inside `ancestor`'s subtree? Mirrors quest's own cycle guard (`internal/quest/structural.ts`). */
+function isDescendant(index, candidate, ancestor) {
+    const seen = new Set();
+    let cursor = candidate;
+    while (cursor !== undefined && !seen.has(cursor)) {
+        seen.add(cursor);
+        if (cursor === ancestor)
+            return true;
+        cursor = index.notes.get(cursor)?.doc.frontMatter.parent;
+    }
+    return false;
+}
+export function reparent(notesRoot, params) {
+    if (!params.id)
+        return refuse("reparent needs an id");
+    const { index } = discoverNotes(notesRoot);
+    const resolved = resolveId(index, params.id);
+    if ("error" in resolved)
+        return refuse(resolved.error);
+    const loaded = loadForWrite(notesRoot, resolved.id);
+    if (!loaded)
+        return refuse(`could not read ${resolved.id}`);
+    if (!params.parent || params.parent.toLowerCase() === "none") {
+        delete loaded.frontMatter.parent;
+        atomicWriteFile(loaded.path, serializeNote(loaded.frontMatter, loaded.body));
+        return ok(`${resolved.id}: parent cleared`, {
+            id: resolved.id,
+            parent: null,
+        });
+    }
+    const resolvedParent = resolveId(index, params.parent);
+    if ("error" in resolvedParent)
+        return refuse(resolvedParent.error);
+    if (resolvedParent.id === resolved.id) {
+        return refuse(`${resolved.id} cannot be its own parent (cycle)`);
+    }
+    if (isDescendant(index, resolvedParent.id, resolved.id)) {
+        return refuse(`reparenting ${resolved.id} under ${resolvedParent.id} would form a cycle`);
+    }
+    loaded.frontMatter.parent = resolvedParent.id;
+    atomicWriteFile(loaded.path, serializeNote(loaded.frontMatter, loaded.body));
+    return ok(`${resolved.id}: parent -> ${resolvedParent.id}`, {
+        id: resolved.id,
+        parent: resolvedParent.id,
+    });
+}