pi-vault-mind 0.16.34 → 0.16.37

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.16.36 — 2026-08-30
+
+### Changed
+
+- **Node 24 runtime floor.** The supported Node.js floor is now `24.19.0+`, matching the current local/runtime toolchain and simplifying support expectations.
+- **GitHub workflows disabled.** The repository no longer runs the generic `ci.yml` or `release-obsidian.yml` automation. Verification and publishing are currently a local operator workflow; the former workflow files are preserved under `.github/workflows-disabled/` for future reuse.
+
+## 0.16.35 — 2026-08-30
+
+### Added
+
+- **Watcher request-block preservation.** The vault watcher no longer destructively replaces `@agent` markers with subagent output. The original request block is preserved in the source note; only the running-status line is updated with a brief completion summary. Requests are reviewable and the vault note remains a faithful record of what was asked.
+- **Reserved `@agent:main` identity.** The `@agent:main` marker is recognized by the watcher but never auto-dispatched to a background subagent. It is reserved for the interactive main session. Use `/vm main sweep [file-or-folder]` to collect pending `@agent:main` markers and address them in the current session.
+- **Stock `system.md` and `AGENTS.md` baseline provisioning.** `pvm setup` provisions vault-local `system.md` (agent system prompt) and vault-root `AGENTS.md` (agent conventions) from curated stock baselines when those files do not already exist, giving every fresh vault a working agent identity without manual authoring. Baselines are demarcated with `<!-- vm:baseline:start/end -->` tags so `/vm personalize` can update only the personalization section without touching the baseline.
+- **`vm_script` tool and run-sdk scaffold.** A sandboxed JavaScript/TypeScript execution tool (`vm_script`) is scaffolded using the `run` QuickJS package. Scripts execute with no ambient filesystem, network, or timer access beyond declared host functions (`vm.*`, `vault.read`, `log`). Enabled by default for manager and main agents. Follow-up: HITL interruption path, `vault.write`, and `pvm run <script>` CLI subcommand.
+
+### Changed
+
+- **docling replaces any2md.** The Miner's document-conversion path (`vm_ingest`) now uses `docling` (via `uvx` or a globally installed `pip install docling`) for PDF, DOCX, HTML, and URL normalization. The `any2md` npm package is no longer a dependency or runtime requirement.
+
+
 ## 0.16.34 — 2026-08-29
 
 ### Added

package/README.md

@@ -12,13 +12,13 @@ Passive Obsidian vault extension for the [pi](https://github.com/mariozechner/pi
 
 ## Features
 
-- **Passive File Watcher** — drop `@agent-Miner`, `@agent-Broadcaster`, etc. in any Obsidian note. Save the file. The watcher detects the marker, groups by role, and dispatches isolated subagent forks (`vault-mind-{role}` agents). No chat pollution, no manual triggers.
+- **Passive File Watcher** — drop `@agent:<role>` (or `@agent-<role>`) markers in any Obsidian note. Save. The watcher detects the marker, groups by role, and dispatches isolated subagent forks. The original request block is preserved in the note; only the running-status line is updated with the result summary. `@agent:main` is reserved for the current interactive session and is never auto-dispatched — sweep it manually with `/vm main sweep`. No chat pollution, no manual triggers.
 - **Multi-Agent Architecture** — five specialist agents under the `vault-mind-{role}` skill naming: **Manager** (interactive orchestrator), **Miner** (research + entity extraction), **Broadcaster** (NotebookLM artifacts), **Heavy-Lifter** (external delegation), **Watcher** (passive file observer).
 - **LanceDB Vector + FTS + Graph** — hybrid semantic + keyword search with automatic entity extraction and BFS graph traversal. All local, no external binaries.
 - **JSONL Source-of-Truth + LanceDB Index** — every fact lives in a durable, human-readable, version-control-friendly `collections/*.jsonl` file. The LanceDB index is derived and rebuildable via `/vm reindex --all --reembed`.
 - **Bidirectional Obsidian Sync** — substantial entries (`>200 chars` or tagged `decision`/`insight`/`requirement`) auto-write to `Vault/Agent/Inbox/`. Graph entities render as Obsidian Canvas files.
 - **Vault-Scoped Configuration Surface** — Vault Mind setup/config now lives under `<vault>/.vault-mind/`, with the Obsidian setup wizard and `/vm setup` both writing the vault-local surface instead of a shared global config.
-- **Interactive Setup Wizard** — the Obsidian setup wizard handles first-run runtime/install/provider/folder/preferences/review flow, and `/vm setup` remains available for CLI/repair use.
+- **Audio Transcription Lane** — `vm_transcribe` handles audio/video separately from `vm_ingest`, preferring a vault-configured Modal HTTP endpoint for high-quality jobs when `vaultMind.transcription.remoteUrl` is set, while keeping a safe local `faster-whisper` fallback and `/vm transcribe status|config|use|local` ops surface for switching lanes and managing the local server.
 
 ## Architecture
 
@@ -171,19 +171,13 @@ The Broadcaster agent can generate podcasts, study guides, and slide decks from
 
 ### Prerequisites
 
-- **Node.js** 22.19.0+ (matches `engines` in `package.json`)
+- **Node.js** 24.19.0+ (matches `engines` in `package.json`)
 - **Embedding Provider** — choose one:
   - `@xenova/transformers` — built-in, no external deps (uses all-MiniLM-L6-v2, offline-capable)
   - `ollama` — requires Ollama running locally with `embeddinggemma` (higher quality)
   - `modal` — optional, **bring-your-own deploy**: offload embedding + bulk re-index to a cloud GPU service and sync vectors down for offline search (see [docs/integrations/MODAL_EMBEDDING.md](docs/integrations/MODAL_EMBEDDING.md)). Default behavior is unchanged until you opt in.
 
-> **On the Modal provider:** the local providers above work for everyone with
-> zero infrastructure — that's the default. `modal` is an **optional, self-hosted
-> tier**: you deploy your own copy of the service (`uvx modal deploy modal/app.py`
-> from a clone of this repo) to your own Modal account and point the extension at
-> *your* URL + token. There is no shared/hosted endpoint — a deployment's URL and
-> bearer token are private to whoever owns it. (A standalone PyPI package for the
-> server may come later.)
+> **On the Modal transcription path:** this is **bring-your-own deploy**. You deploy your own Modal HTTP endpoint from the `audio-transcription` repo, store its URL under `vaultMind.transcription.remoteUrl`, and Vault Mind can prefer that remote high-quality path by default. If no remote transcription URL is configured, `vm_transcribe` falls back to the local `faster-whisper` lane.
 
 ### 1. Install and set up the vault-local runtime
 
@@ -200,8 +194,10 @@ context, model-routing, task, and subagent extensions inside
 `<vault>/.vault-mind/.pi/agent/`; installs the curated `obsidian-cli`,
 `obsidian-markdown`, `obsidian-bases`, and `json-canvas` skills; and
 merge-safely scaffolds Vault Mind, model-router, and main-agent configuration.
-Existing user configuration, collections, model choices, and `system.md` are
-preserved.
+On first run it also creates stock `.pi/agent/system.md` and vault-root
+`AGENTS.md` baseline regions. All of these are preserved on repeat runs —
+existing user configuration, collections, model choices, and personalizations
+are never overwritten.
 
 Refresh only extensions, tools, and skills without touching vault
 configuration:
@@ -360,16 +356,33 @@ applies no boundary while the persona is `main`.
 ### Use specialist agents without changing the main session
 
 Normally, leave the interactive session on `main` and dispatch specialist work
-through the passive watcher:
+through the passive watcher. Both marker forms are equivalent:
 
 ```text
-@agent-Miner
+@agent:miner
 Research and extract the durable facts from this note.
 ```
 
-The watcher runs that work as an isolated specialist job. It does not turn the
-interactive terminal into the Miner persona. The same distinction applies to
-`@agent-Broadcaster`, `@agent-Manager`, and `@agent-Heavy-Lifter`.
+or
+
+```text
+@agent-miner
+Research and extract the durable facts from this note.
+```
+
+The watcher runs that work as an isolated specialist job, preserving the
+request block in the source note and replacing only the running-status line
+with a result summary. It does not turn the interactive terminal into the
+Miner persona. The same applies to `@agent:broadcaster`, `@agent:manager`,
+and `@agent:heavy-lifter`.
+
+`@agent:main` is reserved for the current interactive session and is never
+auto-dispatched. To sweep reserved markers into the active session:
+
+```text
+/vm main sweep
+/vm main sweep path/to/note.md
+```
 
 ### Explicitly change the interactive persona
 
@@ -535,8 +548,9 @@ belongs in `vaultMind.identities` or an explicit environment override.
 | `vm_describe`   | Introspect schema, count, and sample entries            |
 | `vm_stats`      | Dashboard: counts, sizes, LanceDB status                |
 | `vm_export`     | Export to JSON, CSV, or Markdown                        |
-| `vm_promote`    | Promote entries between collections via pending queue  |
-
+| `vm_ingest`     | Convert URLs and documents to markdown via docling       |
+| `vm_transcribe` | Transcribe audio/video, generate transcript notes + raw artifacts |
+| `vm_script`     | Execute sandboxed JS/TS with vm.*, vault.read, log.*    |
 ## Commands
 
 | Command                        | Purpose                                                  |
@@ -555,7 +569,8 @@ belongs in `vaultMind.identities` or an explicit environment override.
 | `/vm embedding status \| use \| model \| models \| pull` | Manage embedding provider |
 | `/vm identity status \| set <role> \| on \| off` | Inspect or explicitly control the interactive agent persona boundary |
 | `/vm remote status \| config \| sync \| jobs \| migrate` | Manage remote embedding + vector sync |
-| `/vm watcher start \| stop \| status` | Manage the passive file watcher                  |
+| `/vm watcher start \| stop \| status` | Manage the passive file watcher        |
+| `/vm main sweep [file]`      | Sweep `@agent:main` markers into the current interactive session |
 | `/vm server status` | Show HTTP server status, port, and uptime |
 
 ## Documentation

package/dist/runtime/headless-sync-worker.d.ts

@@ -0,0 +1,84 @@
+import { type HeadlessRebuildAfterReindexDependencies, type HeadlessRebuildDependencies } from "../src/headless-rebuild.js";
+import type { UniversalConfig } from "../src/types.js";
+type WorkerPhase = "credentials" | "auth" | "sync" | "embed" | "graph" | "config";
+export declare class HeadlessSyncWorkerError extends Error {
+    readonly phase: WorkerPhase;
+    constructor(phase: WorkerPhase);
+}
+export interface HeadlessSyncWorkerRequest {
+    operationId: string;
+    graphId: string;
+    collections: string[];
+}
+interface SecretClient {
+    secrets: {
+        resolve(reference: string): Promise<string>;
+    };
+}
+interface VectorRevision {
+    collection: string;
+    model: string;
+    dim: number;
+    watermark: number;
+    revision: string;
+}
+interface GraphRevisionRow {
+    graph_id: string;
+    revision: string;
+    source_fingerprint: string;
+    updated_at: string;
+}
+interface RevisionManifest {
+    vectors: Array<VectorRevision & {
+        updated_at: string;
+    }>;
+    graphs: GraphRevisionRow[];
+}
+export interface HeadlessSyncWorkerDependencies {
+    env: Record<string, string | undefined>;
+    workspaceRoot: string;
+    createClient(options: {
+        auth: string;
+        integrationName: string;
+        integrationVersion: string;
+    }): Promise<SecretClient>;
+    execFile(command: string, args: string[], options: {
+        cwd: string;
+        env: Record<string, string | undefined>;
+    }): Promise<unknown>;
+    runRebuild(request: {
+        graphId: string;
+        clonePath: string;
+        wait: true;
+    }, deps: Partial<HeadlessRebuildDependencies> & Pick<HeadlessRebuildAfterReindexDependencies, "reindex">): Promise<{
+        graphId: string;
+        sourceFingerprint: string;
+        jobId?: string;
+        jobStatus?: string;
+    }>;
+    reindexRemote(cfg: UniversalConfig, collections: string[], vaultPath: string, options: {
+        syncDown: false;
+    }): Promise<Array<{
+        collection: string;
+        job?: {
+            status: string;
+        };
+        error?: string;
+        model?: string;
+        dim?: number | null;
+        remote_collection?: string;
+    }>>;
+    readRevisionsManifest(baseUrl: string, token: string): Promise<{
+        vectors: VectorRevision[];
+        graphs: GraphRevisionRow[];
+    }>;
+    fetchNamespaceWatermark(baseUrl: string, token: string, collection: string, model: string, dim: number): Promise<number>;
+    publishRevisions(baseUrl: string, token: string, manifest: RevisionManifest): Promise<void>;
+    now(): string;
+}
+export declare function runHeadlessSyncWorker(request: HeadlessSyncWorkerRequest, deps: HeadlessSyncWorkerDependencies): Promise<{
+    graphId: string;
+    graphJobId?: string;
+    sourceFingerprint: string;
+}>;
+export {};

package/dist/runtime/headless-sync-worker.js

@@ -0,0 +1,319 @@
+import { execFile as nodeExecFile } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { runHeadlessRebuildAfterReindex, } from "../src/headless-rebuild.js";
+import { reindexRemote } from "../src/sync.js";
+const execFileAsync = promisify(nodeExecFile);
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export class HeadlessSyncWorkerError extends Error {
+    phase;
+    constructor(phase) {
+        super(`${phase} failed`);
+        this.name = "HeadlessSyncWorkerError";
+        this.phase = phase;
+    }
+}
+function required(env, key, phase) {
+    const value = env[key];
+    if (!value)
+        throw new HeadlessSyncWorkerError(phase);
+    return value;
+}
+function assertSafe(value, phase) {
+    if (!IDENTIFIER.test(value))
+        throw new HeadlessSyncWorkerError(phase);
+    return value;
+}
+function reference(env, key) {
+    const value = required(env, key, "config");
+    if (!value.startsWith("op://") || value.length > 512)
+        throw new HeadlessSyncWorkerError("config");
+    return value;
+}
+function optionalReference(env, key) {
+    const value = env[key];
+    if (!value)
+        return undefined;
+    return reference(env, key);
+}
+function selectConfig(raw, collections, token) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new HeadlessSyncWorkerError("config");
+    }
+    if (!parsed || typeof parsed !== "object")
+        throw new HeadlessSyncWorkerError("config");
+    const cfg = parsed;
+    const embeddingUrl = cfg.vaultMind?.embedding?.remoteUrl;
+    if (!cfg.collections ||
+        typeof cfg.collections !== "object" ||
+        !cfg.vaultMind ||
+        typeof embeddingUrl !== "string" ||
+        embeddingUrl.length === 0) {
+        throw new HeadlessSyncWorkerError("config");
+    }
+    const selected = {};
+    for (const collection of collections) {
+        const definition = cfg.collections[collection];
+        if (!definition)
+            throw new HeadlessSyncWorkerError("config");
+        selected[collection] = definition;
+    }
+    cfg.collections = selected;
+    cfg.vaultMind.embedding = {
+        ...cfg.vaultMind.embedding,
+        remoteApiKey: token,
+    };
+    return { config: cfg, embeddingUrl };
+}
+function sanitizeError(error, phase) {
+    if (error instanceof HeadlessSyncWorkerError)
+        throw error;
+    throw new HeadlessSyncWorkerError(phase);
+}
+export async function runHeadlessSyncWorker(request, deps) {
+    assertSafe(request.operationId, "config");
+    assertSafe(request.graphId, "config");
+    if (request.collections.length === 0 ||
+        new Set(request.collections).size !== request.collections.length) {
+        throw new HeadlessSyncWorkerError("config");
+    }
+    for (const collection of request.collections)
+        assertSafe(collection, "config");
+    const workspace = path.resolve(deps.workspaceRoot, request.operationId);
+    const home = path.join(workspace, ".home");
+    const env = { ...deps.env, HOME: home };
+    fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+    required(deps.env, "OP_SERVICE_ACCOUNT_TOKEN", "credentials");
+    const embeddingToken = required(deps.env, "PVM_REMOTE_EMBEDDING_API_KEY", "credentials");
+    let email;
+    let password;
+    let mfa;
+    let e2ePassword;
+    let vault;
+    try {
+        const resolve = async (ref) => {
+            const result = (await deps.execFile("op", ["read", "--no-newline", ref], {
+                cwd: workspace,
+                env,
+            }));
+            if (typeof result.stdout !== "string" || result.stdout.length === 0) {
+                throw new HeadlessSyncWorkerError("credentials");
+            }
+            return result.stdout;
+        };
+        const mfaRef = optionalReference(deps.env, "PVM_HEADLESS_OP_MFA_REF");
+        const e2eRef = optionalReference(deps.env, "PVM_HEADLESS_OP_E2E_PASSWORD_REF");
+        [email, password, mfa, e2ePassword, vault] = await Promise.all([
+            resolve(reference(deps.env, "PVM_HEADLESS_OP_EMAIL_REF")),
+            resolve(reference(deps.env, "PVM_HEADLESS_OP_PASSWORD_REF")),
+            mfaRef ? resolve(mfaRef) : Promise.resolve(undefined),
+            e2eRef ? resolve(e2eRef) : Promise.resolve(undefined),
+            resolve(reference(deps.env, "PVM_HEADLESS_OP_VAULT_REF")),
+        ]);
+        let parsedVault;
+        try {
+            parsedVault = JSON.parse(vault);
+        }
+        catch {
+            throw new HeadlessSyncWorkerError("credentials");
+        }
+        if (!parsedVault ||
+            typeof parsedVault !== "object" ||
+            !("vault_id" in parsedVault) ||
+            typeof parsedVault.vault_id !== "string" ||
+            !IDENTIFIER.test(parsedVault.vault_id)) {
+            throw new HeadlessSyncWorkerError("credentials");
+        }
+        vault = parsedVault.vault_id;
+    }
+    catch (error) {
+        return sanitizeError(error, "credentials");
+    }
+    try {
+        const loginArgs = ["login", "--email", email, "--password", password];
+        if (mfa)
+            loginArgs.push("--mfa", mfa);
+        await deps.execFile("ob", loginArgs, { cwd: workspace, env });
+        const setupArgs = [
+            "sync-setup",
+            "--vault",
+            vault,
+            "--path",
+            workspace,
+            "--password",
+            e2ePassword,
+            "--device-name",
+            `pvm-headless-${request.operationId}`,
+        ];
+        if (!e2ePassword)
+            setupArgs.splice(setupArgs.indexOf("--password"), 2);
+        await deps.execFile("ob", setupArgs, { cwd: workspace, env });
+        await deps.execFile("ob", ["sync", "--path", workspace], { cwd: workspace, env });
+    }
+    catch (error) {
+        return sanitizeError(error, "auth");
+    }
+    let cfg;
+    let embeddingUrl;
+    try {
+        const configPath = path.join(workspace, ".vault-mind", "vault-mind.config.json");
+        const rawConfig = fs.readFileSync(configPath, "utf8");
+        ({ config: cfg, embeddingUrl } = selectConfig(rawConfig, request.collections, embeddingToken));
+    }
+    catch (error) {
+        return sanitizeError(error, "config");
+    }
+    let checkpoint;
+    let reindexRevisions;
+    try {
+        checkpoint = await deps.runRebuild({ graphId: request.graphId, clonePath: workspace, wait: true }, {
+            runObSync: async (clonePath) => {
+                await deps.execFile("ob", ["sync", "--path", clonePath], { cwd: clonePath, env });
+            },
+            reindex: async (resolvedConfig, clonePath) => {
+                const selectedConfig = {
+                    ...cfg,
+                    ...resolvedConfig,
+                    collections: cfg.collections,
+                };
+                const results = await deps.reindexRemote(selectedConfig, request.collections, clonePath, {
+                    syncDown: false,
+                });
+                if (results.some((result) => result.error || result.job?.status !== "done")) {
+                    throw new HeadlessSyncWorkerError("embed");
+                }
+                reindexRevisions = results
+                    .filter((result) => result.job?.status === "done" &&
+                    !result.error &&
+                    !!result.model &&
+                    !!result.remote_collection)
+                    .map((result) => ({
+                    collection: result.remote_collection,
+                    model: result.model,
+                    dim: (result.dim ?? 0),
+                    revision: result.job.status,
+                    watermark: 0,
+                }));
+            },
+        });
+    }
+    catch (error) {
+        return sanitizeError(error, error instanceof HeadlessSyncWorkerError ? error.phase : "graph");
+    }
+    if (checkpoint.jobStatus !== "done" || !checkpoint.jobId)
+        throw new HeadlessSyncWorkerError("graph");
+    let vectors;
+    try {
+        vectors = reindexRevisions;
+        const remoteCollections = new Set(vectors.map((vector) => vector.collection));
+        if (vectors.length !== request.collections.length ||
+            vectors.some((vector) => !remoteCollections.has(vector.collection) ||
+                !(typeof vector.dim === "number" && vector.dim > 0) ||
+                !Number.isSafeInteger(vector.watermark) ||
+                vector.watermark < 0)) {
+            throw new HeadlessSyncWorkerError("embed");
+        }
+        const watermarks = await Promise.all(vectors.map(async (vector) => {
+            try {
+                return await deps.fetchNamespaceWatermark(embeddingUrl, embeddingToken, vector.collection, vector.model, vector.dim);
+            }
+            catch (error) {
+                throw new HeadlessSyncWorkerError("embed");
+            }
+        }));
+        vectors = vectors.map((vector, index) => ({
+            ...vector,
+            watermark: watermarks[index],
+        }));
+    }
+    catch (error) {
+        return sanitizeError(error, "embed");
+    }
+    try {
+        const existing = await deps.readRevisionsManifest(embeddingUrl, embeddingToken);
+        const selectedRemote = new Set(vectors.map((vector) => vector.collection));
+        const survivingVectors = existing.vectors
+            .filter((vector) => !selectedRemote.has(vector.collection))
+            .map((vector) => ({ ...vector, updated_at: deps.now() }));
+        await deps.publishRevisions(embeddingUrl, embeddingToken, {
+            vectors: [
+                ...survivingVectors,
+                ...vectors.map((vector) => ({
+                    ...vector,
+                    updated_at: deps.now(),
+                })),
+            ],
+            graphs: [
+                ...existing.graphs,
+                {
+                    graph_id: checkpoint.graphId,
+                    revision: checkpoint.jobId,
+                    source_fingerprint: checkpoint.sourceFingerprint,
+                    updated_at: deps.now(),
+                },
+            ],
+        });
+    }
+    catch (error) {
+        return sanitizeError(error, "graph");
+    }
+    return {
+        graphId: checkpoint.graphId,
+        graphJobId: checkpoint.jobId,
+        sourceFingerprint: checkpoint.sourceFingerprint,
+    };
+}
+const defaultDependencies = {
+    env: process.env,
+    workspaceRoot: process.env.PVM_HEADLESS_WORKSPACE_ROOT || "/pvm-vault/workspaces",
+    execFile: async (command, args, options) => execFileAsync(command, args, options),
+    runRebuild: runHeadlessRebuildAfterReindex,
+    reindexRemote: reindexRemote,
+    readRevisionsManifest: async (baseUrl, token) => {
+        const target = baseUrl.replace(/\/$/, "");
+        const response = await fetch(`${target}/sync/revisions`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok)
+            throw new Error("revision read failed");
+        return (await response.json());
+    },
+    fetchNamespaceWatermark: async (baseUrl, token, collection, model, dim) => {
+        const target = baseUrl.replace(/\/$/, "");
+        const params = new URLSearchParams({ collection, model, dim: String(dim) });
+        const response = await fetch(`${target}/sync/namespace-watermark?${params.toString()}`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok)
+            throw new Error("namespace watermark read failed");
+        const body = (await response.json());
+        return body.watermark;
+    },
+    publishRevisions: async (baseUrl, token, manifest) => {
+        const response = await fetch(`${baseUrl.replace(/\/$/, "")}/sync/revisions`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+            body: JSON.stringify(manifest),
+        });
+        if (!response.ok)
+            throw new Error("revision publish failed");
+    },
+    now: () => new Date().toISOString(),
+};
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const [operationId, graphId, collectionsJson] = process.argv.slice(2);
+    void (async () => {
+        const collections = JSON.parse(collectionsJson || "[]");
+        const result = await runHeadlessSyncWorker({ operationId: operationId || "", graphId: graphId || "", collections }, defaultDependencies);
+        process.stdout.write(JSON.stringify(result));
+    })().catch(() => {
+        process.exitCode = 1;
+    });
+}

package/dist/src/agent-docs.d.ts

@@ -0,0 +1,6 @@
+export declare const BASELINE_START = "<!-- vm:baseline:start -->";
+export declare const BASELINE_END = "<!-- vm:baseline:end -->";
+export declare const PERSONALIZATION_START = "<!-- vm:personalization:start -->";
+export declare const PERSONALIZATION_END = "<!-- vm:personalization:end -->";
+export declare const buildDefaultSystemMd: (vaultPath: string) => string;
+export declare const buildDefaultAgentsMd: () => string;

package/dist/src/agent-docs.js

@@ -0,0 +1,60 @@
+import * as path from "node:path";
+export const BASELINE_START = "<!-- vm:baseline:start -->";
+export const BASELINE_END = "<!-- vm:baseline:end -->";
+export const PERSONALIZATION_START = "<!-- vm:personalization:start -->";
+export const PERSONALIZATION_END = "<!-- vm:personalization:end -->";
+export const buildDefaultSystemMd = (vaultPath) => {
+    const vaultName = path.basename(vaultPath);
+    return `# Pi main agent: ${vaultName}
+
+${BASELINE_START}
+You are the unrestricted main interactive agent for this vault. Bundled specialist skills are available resources; their presence does not change your active identity. Adopt a specialist identity only when explicitly launched as that subagent.
+
+## Operating baseline
+- Read \`00-system/SYSTEM.md\` first when it exists. If it does not exist, fall back to a vault-root \`SYSTEM.md\`. Then read the vault-root \`AGENTS.md\`.
+- Prefer the vault's own operating manual and schemas over generic assumptions.
+- Use the \`vm_*\` tools, collections, and queue as the durable system of record for agent work.
+- Prefer \`uv\` for Python tools and CLIs. Use \`pnpm\`/\`npm\` for JavaScript and TypeScript packages such as \`run\`.
+- Use \`docling\` for document conversion in ingest flows.
+- Use \`vm_script\` for reusable sandboxed JS/TS workflows when the task fits the approved host-function surface.
+- Use \`vm_transcribe\` for audio/video transcription (voice notes, podcasts, NotebookLM audio overviews). Defaults come from \`vaultMind.transcription\`: prefer the remote Modal HTTP endpoint when \`remoteUrl\` is configured, otherwise fall back to the local engine. Keep this lane separate from \`vm_ingest\`/docling.
+- Use the \`nlm\` CLI for NotebookLM source inventory lookups. Do not use MCP as the primary path for NotebookLM notebook/source queries.
+- Never auto-publish, never fabricate facts, and keep human approval at external side effects.
+- The watcher recognizes \`@agent:<role>\` and \`@agent-<role>\` anywhere in watchable files. \`@agent:main\` is reserved for human-authored review and follow-up notes; it is never auto-dispatched. Automated transcript preparation, source linking, and note population use \`@agent:audio-overviews\`.
+${BASELINE_END}
+
+${PERSONALIZATION_START}
+Add vault-specific priorities, domain language, and working preferences here. /vm personalize may update only this section.
+${PERSONALIZATION_END}
+`;
+};
+export const buildDefaultAgentsMd = () => `# AGENTS: pi-vault-mind operating baseline
+
+${BASELINE_START}
+## Agent roles
+- \`main\` — the interactive agent you work with directly.
+- \`manager\` — synthesis, orchestration, and roadmap work.
+- \`miner\` — extraction, ingestion, and structured knowledge capture.
+- \`broadcaster\` — human-facing artifact generation.
+- \`heavy-lifter\` — large-context implementation and deeper delegated work.
+- \`personalization\` — resolves annotated feedback on generated system/agent docs.
+- \`audio-overviews\` — automated worker for NotebookLM audio overview transcription, source resolution, and note population. Uses deterministic scripts/functions rather than freeform improvisation.
+
+## Watcher + inline requests
+- Use \`@agent:<role>\` or \`@agent-<role>\` in watchable files to request agent help.
+- \`@agent:main\` is recognized but never auto-dispatched; it is for human-authored review notes and follow-up only — not automated transcript generation.
+- Auto-dispatched watcher jobs preserve the request block in the source note and replace only the running-status line with the result summary.
+- Watcher dispatches should be logged to collections so they can be queried later.
+
+## Tooling baseline
+- Prefer \`uv\` for Python tools.
+- Prefer reusable \`vm_script\` workflows over ad-hoc one-off scripts when the workflow should be repeatable.
+- Use \`vm_transcribe\` for audio/video transcription; keep this lane separate from \`vm_ingest\`/docling.
+- Use \`nlm\` for NotebookLM source inventory. Do not use MCP as the primary path for NotebookLM lookups.
+- Keep reusable content, test, and update workflows in skills/tools rather than scattered shell snippets.
+${BASELINE_END}
+
+${PERSONALIZATION_START}
+Add vault-specific agent roster details, domain-specific prompts, and delegation rules here. /vm personalize may update only this section.
+${PERSONALIZATION_END}
+`;

package/dist/src/agent-queue.d.ts

@@ -75,7 +75,7 @@ export declare const markJobFailed: (vaultPath: string, id: string, error: strin
 export declare const markJobRunning: (vaultPath: string, id: string) => AgentJob | undefined;
 /** Mark a pending job as cancelled. */
 export declare const cancelJob: (vaultPath: string, id: string) => AgentJob | undefined;
-/** True if the file still contains the dispatch marker for this job. */
+/** True if the file still contains the pending dispatch status placeholder. */
 export declare const markerStillPresent: (filePath: string, dispatchId: string) => boolean;
 /** Scan a vault's queue and mark any running job whose marker is gone as done. */
 export declare const sweepCompletedJobs: (vaultPath: string) => AgentJob[];

package/dist/src/agent-queue.js

@@ -12,6 +12,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { dispatchStatusLine } from "./dispatch-writeback.js";
 import { loadConfig, resolveVaultFile } from "./utils.js";
 const queueSubscribers = new Set();
 /** Subscribe to queue events. Returns an unsubscribe function. */
@@ -138,11 +139,11 @@ export const cancelJob = (vaultPath, id) => {
         return undefined;
     return updateJob(vaultPath, id, "cancelled");
 };
-/** True if the file still contains the dispatch marker for this job. */
+/** True if the file still contains the pending dispatch status placeholder. */
 export const markerStillPresent = (filePath, dispatchId) => {
     try {
         const content = fs.readFileSync(filePath, "utf-8");
-        return content.includes(`<!-- pi-dispatch:${dispatchId} -->`);
+        return content.includes(dispatchStatusLine(dispatchId));
     }
     catch {
         return false;

package/dist/src/agents/BroadcasterAgent.js

@@ -6,6 +6,7 @@
  * Writes output only under Agent/Presentations/.
  */
 import { Agent } from "../agent-bus/Agent.js";
+import { buildDispatchResultLine, dispatchStatusLine } from "../dispatch-writeback.js";
 export class BroadcasterAgent extends Agent {
     taskQueue = null;
     constructor(config, bus, llm) {
@@ -58,8 +59,8 @@ export class BroadcasterAgent extends Agent {
             path: job.filePath,
             edits: [
                 {
-                    oldText: `<!-- pi-dispatch:${job.dispatchId} -->`,
-                    newText: `> Broadcaster completed. See dispatch ${job.dispatchId}.`,
+                    oldText: dispatchStatusLine(job.dispatchId),
+                    newText: buildDispatchResultLine(job.dispatchId, `Broadcaster completed. See dispatch ${job.dispatchId}.`),
                 },
             ],
         });