@markii/host 0.0.0-stage → 0.17.0-next.2

package/dist/host/pack-trust-behavior.js

@@ -0,0 +1,262 @@
+/**
+ * The shared pack-trust behavior (docs/packs.md, docs/integration.md's host
+ * checklist). A host that declares `HostPackSource.trust: 'device-list'`
+ * loads an installed pack only when this device's trust list names its
+ * namespace. A folder that sits in the install root without being named
+ * there is listed as present but not enabled, and nothing in it is read
+ * past its folder name: it is never discovered, never evaluated.
+ *
+ * The list lives in the adapter's device-local `memento` (the same state
+ * the grant model uses), never in anything that travels with a vault or a
+ * workspace file. Installing a pack trusts it (the install consent prompt
+ * already asked), enabling a present folder asks the same prompt, and
+ * disabling or removing withdraws the entry.
+ *
+ * A host that declares `trust: 'none'` (or omits the field) trusts every
+ * folder its own policy authorizes, and every function here is inert for
+ * it. Neutral on purpose: only the adapter's file and state primitives
+ * are used.
+ */
+import { parsePackManifest, validatePackName } from '@markii/pack';
+import { joinPath } from '../path-util.js';
+import { PACK_TRUST_STORAGE_KEY, isPackTrusted, normalizePackTrustList, trustPack, untrustPack, } from '../packs/pack-trust.js';
+import { installConsentMessage } from './pack-install.js';
+/** Whether this adapter's pack source gates installed packs on the device trust list and can say where they live. */
+export function usesPackTrust(adapter) {
+    return (adapter.packs?.trust === 'device-list' &&
+        adapter.packs.installRoot !== undefined);
+}
+export function readPackTrust(adapter) {
+    return normalizePackTrustList(adapter.memento.get(PACK_TRUST_STORAGE_KEY));
+}
+async function writePackTrust(adapter, list) {
+    await adapter.memento.update(PACK_TRUST_STORAGE_KEY, list);
+}
+/**
+ * Pure: splits the namespaces found in the install root by the trust
+ * list. A trust entry naming a namespace no longer on disk contributes to
+ * neither side: there is nothing to load and nothing to report.
+ */
+export function selectEnabledPacks(installRoot, onDiskNamespaces, trust) {
+    const byNamespace = new Map(trust.entries.map((entry) => [entry.namespace, entry]));
+    const enabled = [];
+    const notEnabled = [];
+    for (const namespace of onDiskNamespaces) {
+        const entry = byNamespace.get(namespace);
+        if (entry) {
+            enabled.push({
+                namespace,
+                folder: joinPath(installRoot, namespace),
+                ...(entry.version !== undefined ? { version: entry.version } : {}),
+            });
+        }
+        else {
+            notEnabled.push(namespace);
+        }
+    }
+    return { enabled, notEnabled };
+}
+/** Lists the install root through the adapter and splits it by trust. A host without trust returns everything as neither: callers check `usesPackTrust` first. Never throws. */
+export async function listInstalledPacks(adapter) {
+    const installRoot = adapter.packs?.installRoot?.();
+    if (installRoot === undefined)
+        return { enabled: [], notEnabled: [] };
+    let names;
+    try {
+        names = (await adapter.listFolder(installRoot))
+            .filter((entry) => entry.isDirectory)
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        names = [];
+    }
+    return selectEnabledPacks(installRoot, names, readPackTrust(adapter));
+}
+/** The folders the trust gate lets load, for `authorizedFolders` to be extended with. Empty for a host that does not use trust. */
+export async function trustedPackFolders(adapter) {
+    if (!usesPackTrust(adapter))
+        return [];
+    return (await listInstalledPacks(adapter)).enabled.map((p) => p.folder);
+}
+/** Reads a pack's declared `version`, or `undefined` for a missing or malformed `pack.json`. Never throws. */
+async function readPackVersion(adapter, folder) {
+    try {
+        const text = new TextDecoder().decode(await adapter.readFile(joinPath(folder, 'pack.json')));
+        const parsed = JSON.parse(text);
+        return typeof parsed.version === 'string' ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Why a folder's `pack.json` cannot be a pack, or `undefined` when it parses as a valid manifest. Never throws. */
+async function manifestProblem(adapter, folder) {
+    let text;
+    try {
+        text = new TextDecoder().decode(await adapter.readFile(joinPath(folder, 'pack.json')));
+    }
+    catch {
+        return 'the folder has no readable pack.json';
+    }
+    const parsed = parsePackManifest(text);
+    return parsed.ok ? undefined : parsed.errors.join('; ');
+}
+/**
+ * Called by the install path after an archive was extracted: records the
+ * namespace as trusted on this device. A no-op for a host without trust.
+ * Never throws; a refused write is reported on the diagnostics surface.
+ */
+export async function trustInstalledPack(adapter, namespace, installedDir) {
+    if (!usesPackTrust(adapter))
+        return;
+    try {
+        const version = await readPackVersion(adapter, installedDir);
+        await writePackTrust(adapter, trustPack(readPackTrust(adapter), namespace, version));
+    }
+    catch (err) {
+        adapter.diagnostics(`Could not record trust for pack "${namespace}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function invalidReason(namespace) {
+    return `"${namespace}" is not a valid pack namespace`;
+}
+/** Never throws. The caller checks `usesPackTrust` first. */
+export async function enablePackViaAdapter(adapter, namespace) {
+    if (!validatePackName(namespace).ok) {
+        return { kind: 'invalid', reason: invalidReason(namespace) };
+    }
+    const packs = adapter.packs;
+    if (packs === undefined || packs.installRoot === undefined) {
+        return { kind: 'failed', reason: 'no pack install folder is available' };
+    }
+    if (packs.reservedNamespaces().has(namespace)) {
+        return { kind: 'reserved', namespace };
+    }
+    const folder = joinPath(packs.installRoot(), namespace);
+    try {
+        if (!(await adapter.exists(folder))) {
+            return { kind: 'not-installed', namespace };
+        }
+        // A folder that is not a valid pack is refused before the consent
+        // prompt: trusting it would record an entry for a namespace that
+        // cannot load, and would trust whatever later appears in that folder.
+        const problem = await manifestProblem(adapter, folder);
+        if (problem !== undefined) {
+            return {
+                kind: 'failed',
+                reason: `could not enable pack "${namespace}": ${problem}`,
+            };
+        }
+        const consented = await adapter.prompt({
+            kind: 'pack-install-consent',
+            message: installConsentMessage(namespace, adapter.labels),
+            allowLabel: 'Enable',
+            denyLabel: 'Cancel',
+            consequential: true,
+        });
+        if (!consented)
+            return { kind: 'declined', namespace };
+        const version = await readPackVersion(adapter, folder);
+        await writePackTrust(adapter, trustPack(readPackTrust(adapter), namespace, version));
+    }
+    catch (err) {
+        return {
+            kind: 'failed',
+            reason: `could not enable pack "${namespace}": ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    return { kind: 'enabled', namespace };
+}
+/** Never throws. The caller checks `usesPackTrust` first. The folder stays on disk. */
+export async function disablePackViaAdapter(adapter, namespace) {
+    if (!validatePackName(namespace).ok) {
+        return { kind: 'invalid', reason: invalidReason(namespace) };
+    }
+    const list = readPackTrust(adapter);
+    if (!isPackTrusted(list, namespace)) {
+        return { kind: 'not-enabled', namespace };
+    }
+    try {
+        await writePackTrust(adapter, untrustPack(list, namespace));
+    }
+    catch (err) {
+        return {
+            kind: 'failed',
+            reason: `could not disable pack "${namespace}": ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    return { kind: 'disabled', namespace };
+}
+/** Withdraws a namespace's trust entry after a removal. A no-op for a host without trust. Never throws. */
+export async function forgetPackTrust(adapter, namespace) {
+    if (!usesPackTrust(adapter))
+        return;
+    try {
+        await writePackTrust(adapter, untrustPack(readPackTrust(adapter), namespace));
+    }
+    catch (err) {
+        adapter.diagnostics(`Could not withdraw trust for pack "${namespace}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// --- wording ---------------------------------------------------------------
+export function enablePackMessage(outcome) {
+    switch (outcome.kind) {
+        case 'enabled':
+            return `Markii: enabled the pack ${outcome.namespace}.`;
+        case 'declined':
+            return `Markii: the pack ${outcome.namespace} was not enabled.`;
+        case 'not-installed':
+            return `Markii: no pack named "${outcome.namespace}" is installed. Nothing was enabled.`;
+        case 'reserved':
+            return `Markii: "${outcome.namespace}" is built in and is always enabled.`;
+        case 'invalid':
+            return `Markii: ${outcome.reason}. Nothing was enabled.`;
+        case 'failed':
+            return `Markii: ${outcome.reason}.`;
+    }
+}
+export function enablePackDiagnosticLine(outcome) {
+    switch (outcome.kind) {
+        case 'enabled':
+            return `Enable pack enabled "${outcome.namespace}".`;
+        case 'declined':
+            return `Enable pack declined for "${outcome.namespace}": the consent prompt was refused.`;
+        case 'not-installed':
+            return `Enable pack found no installed pack "${outcome.namespace}"; nothing was enabled.`;
+        case 'reserved':
+            return `Enable pack refused "${outcome.namespace}": a built-in pack is always enabled.`;
+        case 'invalid':
+            return `Enable pack refused: ${outcome.reason}.`;
+        case 'failed':
+            return `Enable pack failed: ${outcome.reason}`;
+    }
+}
+export function disablePackMessage(outcome) {
+    switch (outcome.kind) {
+        case 'disabled':
+            return `Markii: disabled the pack ${outcome.namespace}. Its folder was left in place.`;
+        case 'not-enabled':
+            return `Markii: the pack "${outcome.namespace}" is not enabled. Nothing changed.`;
+        case 'invalid':
+            return `Markii: ${outcome.reason}. Nothing changed.`;
+        case 'failed':
+            return `Markii: ${outcome.reason}.`;
+    }
+}
+export function disablePackDiagnosticLine(outcome) {
+    switch (outcome.kind) {
+        case 'disabled':
+            return `Disable pack disabled "${outcome.namespace}"; its folder was left in place.`;
+        case 'not-enabled':
+            return `Disable pack found "${outcome.namespace}" not enabled; nothing changed.`;
+        case 'invalid':
+            return `Disable pack refused: ${outcome.reason}.`;
+        case 'failed':
+            return `Disable pack failed: ${outcome.reason}`;
+    }
+}
+/** One line per folder that is present in the install root but not enabled on this device. Informational, not a failure. */
+export function notEnabledPackDiagnosticLine(namespace, deviceNoun) {
+    return `Pack "${namespace}" is present but not enabled on ${deviceNoun}; it was not loaded.`;
+}

package/dist/host/refresh-interval.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The scheduled-refresh interval's parsing, validation, and clamp,
+ * merged from `apps/vscode/src/refresh-interval.ts` (the input-box
+ * parse/validate half) and `apps/obsidian/src/local-settings.ts`'s
+ * `refreshIntervalMsFromSeconds`/`MIN_REFRESH_INTERVAL_SECONDS` (the
+ * read-side clamp half) — survey finding A7: the constant was duplicated
+ * verbatim, with Obsidian's own comment noting it mirrors VS Code's, and
+ * the clamp-not-reject policy was duplicated as both prose and behavior.
+ *
+ * The policy: a positive value under `MIN_REFRESH_INTERVAL_SECONDS` is
+ * still ACCEPTED as typed (a host's own settings UI must not silently
+ * rewrite what the user entered), but is clamped UP to the minimum only
+ * once a view actually schedules a timer against it.
+ *
+ * Pure and dependency-free: re-exported from `../browser.ts` as well as
+ * `../index.ts`.
+ */
+/** Below this, a positive scheduled-refresh interval is clamped up rather than silently rejected. */
+export declare const MIN_REFRESH_INTERVAL_SECONDS = 5;
+/**
+ * Parses a user-typed interval into whole seconds, or `undefined` when the
+ * input is not a positive integer (empty, non-numeric, zero, negative, or
+ * fractional). Whitespace around the input is ignored.
+ */
+export declare function parseRefreshIntervalSeconds(input: string): number | undefined;
+/**
+ * An error message for input `parseRefreshIntervalSeconds` would reject,
+ * or `undefined` when the input is valid. What a host's own interval
+ * prompt (an input box, a settings field) shows as its validation
+ * message.
+ */
+export declare function refreshIntervalValidationMessage(input: string): string | undefined;
+/**
+ * The scheduled-refresh interval in milliseconds a view should actually
+ * run its timer at, or `undefined` when refresh is off (`seconds` is `0`
+ * or any non-positive/invalid value). A positive value below
+ * `MIN_REFRESH_INTERVAL_SECONDS` is clamped up to it.
+ */
+export declare function refreshIntervalMsFromSeconds(seconds: number): number | undefined;

package/dist/host/refresh-interval.js

@@ -0,0 +1,61 @@
+/**
+ * The scheduled-refresh interval's parsing, validation, and clamp,
+ * merged from `apps/vscode/src/refresh-interval.ts` (the input-box
+ * parse/validate half) and `apps/obsidian/src/local-settings.ts`'s
+ * `refreshIntervalMsFromSeconds`/`MIN_REFRESH_INTERVAL_SECONDS` (the
+ * read-side clamp half) — survey finding A7: the constant was duplicated
+ * verbatim, with Obsidian's own comment noting it mirrors VS Code's, and
+ * the clamp-not-reject policy was duplicated as both prose and behavior.
+ *
+ * The policy: a positive value under `MIN_REFRESH_INTERVAL_SECONDS` is
+ * still ACCEPTED as typed (a host's own settings UI must not silently
+ * rewrite what the user entered), but is clamped UP to the minimum only
+ * once a view actually schedules a timer against it.
+ *
+ * Pure and dependency-free: re-exported from `../browser.ts` as well as
+ * `../index.ts`.
+ */
+/** Below this, a positive scheduled-refresh interval is clamped up rather than silently rejected. */
+export const MIN_REFRESH_INTERVAL_SECONDS = 5;
+/**
+ * Parses a user-typed interval into whole seconds, or `undefined` when the
+ * input is not a positive integer (empty, non-numeric, zero, negative, or
+ * fractional). Whitespace around the input is ignored.
+ */
+export function parseRefreshIntervalSeconds(input) {
+    const trimmed = input.trim();
+    if (trimmed === '')
+        return undefined;
+    if (!/^\d+$/.test(trimmed))
+        return undefined;
+    const seconds = Number(trimmed);
+    if (!Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    return seconds;
+}
+/**
+ * An error message for input `parseRefreshIntervalSeconds` would reject,
+ * or `undefined` when the input is valid. What a host's own interval
+ * prompt (an input box, a settings field) shows as its validation
+ * message.
+ */
+export function refreshIntervalValidationMessage(input) {
+    if (parseRefreshIntervalSeconds(input) === undefined) {
+        return 'Enter a whole number of seconds greater than 0.';
+    }
+    return undefined;
+}
+/**
+ * The scheduled-refresh interval in milliseconds a view should actually
+ * run its timer at, or `undefined` when refresh is off (`seconds` is `0`
+ * or any non-positive/invalid value). A positive value below
+ * `MIN_REFRESH_INTERVAL_SECONDS` is clamped up to it.
+ */
+export function refreshIntervalMsFromSeconds(seconds) {
+    if (typeof seconds !== 'number' ||
+        !Number.isFinite(seconds) ||
+        seconds <= 0) {
+        return undefined;
+    }
+    return Math.max(seconds, MIN_REFRESH_INTERVAL_SECONDS) * 1000;
+}

package/dist/host/run-behavior.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The `run` behavior's host-shaped seams, built from a `HostAdapter`:
+ * this is where survey findings A1 and A6 stop being duplicated three
+ * times over.
+ *
+ * A1: `apps/vscode/src/preview-panel.ts`'s `promptHostAdapter` /
+ * `promptUnknownHostsAdapter` / `promptManyHostsAdapter`,
+ * `apps/obsidian/src/run-modals.ts`'s `promptHostModal` /
+ * `promptUnknownHostsModal` / `promptManyHostsModal`, and
+ * `apps/cli/src/prompts.ts`'s three closures all did the same thing: call
+ * one of `@markii/host`'s exported message builders and turn the answer
+ * into a `boolean` through a host-specific UI primitive. `promptsFromAdapter`
+ * below collapses all nine into three calls to the ONE `adapter.prompt`
+ * method every `HostAdapter` already has.
+ *
+ * A6: `apps/vscode/src/preview-panel.ts:spawnRun` and
+ * `apps/cli/src/run-note.ts:spawnRun` were the same five-line function —
+ * the CLI's own doc comment said outright it was "mirroring
+ * apps/vscode/src/preview-panel.ts's identical function". `spawnRunViaAdapter`
+ * below is that function, written once, dispatching on `HostAdapter.isolate`'s
+ * discriminated union instead of assuming a Node worker path.
+ *
+ * `runViaAdapter` composes both of these around `../run/run-flow.ts`'s
+ * `runOnce` (the existing, already-shared grant-flow-plus-spawn
+ * orchestration) and writes the `RunTrace` through `adapter.now()` rather
+ * than `Date.now()`, so a fixed clock in a test fake makes the trace
+ * byte-stable (batch 11 Phase 3's requirement).
+ */
+import type { RunTrigger } from '@markii/runtime';
+import { type PromptHost, type PromptManyHosts, type PromptUnknownHosts } from '../run/grant-flow.js';
+import { type RunResult, type SpawnRunRequest } from '../run/run-host.js';
+import { type RunOnceOptions, type RunOnceResult } from '../run/run-flow.js';
+import { type RunTrace } from '../run/run-trace.js';
+import type { HostAdapter, HostIsolate } from './adapter.js';
+/**
+ * External wall-clock budget for one run, matching the figure both
+ * `apps/vscode` and `apps/cli` already used, so a note behaves the same
+ * way under any host's watchdog.
+ */
+export declare const RUN_TIMEOUT_MS = 15000;
+/**
+ * Builds the three grant prompts (`PromptHost`, `PromptUnknownHosts`,
+ * `PromptManyHosts`) `../run/run-flow.ts`'s `runOnce` needs, each routed
+ * through `adapter.prompt` with the exact wording `@markii/host`'s
+ * message builders already produce. `consequential: true` on all three:
+ * every one of them authorizes network access, so a host that can only
+ * show a non-blocking surface must deny rather than assume yes — that
+ * policy is the adapter's own (see `HostPromptRequest`'s doc comment).
+ */
+export declare function promptsFromAdapter(adapter: HostAdapter): {
+    promptHost: PromptHost;
+    promptUnknownHosts: PromptUnknownHosts;
+    promptManyHosts: PromptManyHosts;
+};
+/**
+ * The one `spawnRun` adapter every Node host (`apps/vscode`, `apps/cli`)
+ * used to duplicate (survey A6), plus the browser-isolate path Obsidian's
+ * own `spawnRun` wrapper needed. Dispatches on `HostIsolate`'s
+ * discriminated union: a `'node'` host supplies only a worker path; a
+ * `'browser'` host supplies an async, disposable `IsolateSpawner` factory,
+ * disposed once this run's spawner has been used.
+ */
+export declare function spawnRunViaAdapter(isolate: HostIsolate | undefined, options: SpawnRunRequest): Promise<RunResult>;
+export interface RunViaAdapterRequest {
+    /** Stable identity for the note this run belongs to. */
+    readonly documentKey: string;
+    readonly text: string;
+    readonly trigger: RunTrigger;
+    readonly netPolicy?: RunOnceOptions['netPolicy'];
+    readonly bundle?: RunOnceOptions['bundle'];
+    readonly packModules?: RunOnceOptions['packModules'];
+    readonly onValue?: RunOnceOptions['onValue'];
+    readonly timeoutMs?: number;
+}
+/** A run's result plus the `RunTrace` it just recorded, so a host can show its in-note marker from the same value the shared path persisted. */
+export type RunViaAdapterResult = RunOnceResult & {
+    readonly trace: RunTrace;
+};
+/**
+ * Runs one manual, auto, or scheduled pass of `request.text`'s scripts,
+ * exactly as `runOnce` already does (the grant flow prompts only on a
+ * miss, and only for `'manual'`), but with every host-shaped input —
+ * `spawnRun`, the three grant prompts, the memento, the last-run clock —
+ * supplied from `adapter` instead of assembled ad hoc per app. Writes the
+ * `RunTrace` through `writeLastRunTrace` using `adapter.now()`, never
+ * `Date.now()` directly, so a fixed clock in a test fake makes the trace
+ * byte-stable.
+ */
+export declare function runViaAdapter(adapter: HostAdapter, request: RunViaAdapterRequest, overrideSpawnRun?: (options: SpawnRunRequest) => Promise<RunResult>): Promise<RunViaAdapterResult>;

package/dist/host/run-behavior.js

@@ -0,0 +1,168 @@
+import { ALLOW_LABEL, DONT_ALLOW_LABEL, UNKNOWN_HOSTS_PROMPT_MESSAGE, hostPromptMessage, manyHostsPromptMessage, } from '../run/grant-flow.js';
+import { spawnRun as spawnRunHost, } from '../run/run-host.js';
+import { runOnce, } from '../run/run-flow.js';
+import { writeLastRunTrace } from '../run/run-trace.js';
+import { runCrashDiagnosticLine, runDiagnosticLines, } from './run-diagnostics.js';
+import { BROWSER_ISOLATE_ENTRY } from './adapter.js';
+/**
+ * External wall-clock budget for one run, matching the figure both
+ * `apps/vscode` and `apps/cli` already used, so a note behaves the same
+ * way under any host's watchdog.
+ */
+export const RUN_TIMEOUT_MS = 15_000;
+/**
+ * Builds the three grant prompts (`PromptHost`, `PromptUnknownHosts`,
+ * `PromptManyHosts`) `../run/run-flow.ts`'s `runOnce` needs, each routed
+ * through `adapter.prompt` with the exact wording `@markii/host`'s
+ * message builders already produce. `consequential: true` on all three:
+ * every one of them authorizes network access, so a host that can only
+ * show a non-blocking surface must deny rather than assume yes — that
+ * policy is the adapter's own (see `HostPromptRequest`'s doc comment).
+ */
+export function promptsFromAdapter(adapter) {
+    return {
+        promptHost: (host, declaredHosts) => adapter.prompt({
+            kind: 'grant-host',
+            message: hostPromptMessage(host, declaredHosts),
+            allowLabel: ALLOW_LABEL,
+            denyLabel: DONT_ALLOW_LABEL,
+            consequential: true,
+        }),
+        promptUnknownHosts: () => adapter.prompt({
+            kind: 'grant-unknown-hosts',
+            message: UNKNOWN_HOSTS_PROMPT_MESSAGE,
+            allowLabel: ALLOW_LABEL,
+            denyLabel: DONT_ALLOW_LABEL,
+            consequential: true,
+        }),
+        promptManyHosts: (hostCount) => adapter.prompt({
+            kind: 'grant-many-hosts',
+            message: manyHostsPromptMessage(hostCount),
+            allowLabel: ALLOW_LABEL,
+            denyLabel: DONT_ALLOW_LABEL,
+            consequential: true,
+        }),
+    };
+}
+/**
+ * A synthetic `RunResult` for a host with no `isolate` capability at all —
+ * `spawnRunViaAdapter`'s never-throws contract extends to this case too:
+ * a host that cannot run scripts reports it as an ordinary
+ * `'capability-denied'` failure, not a thrown error.
+ */
+function noIsolateResult(cacheSnapshot) {
+    return {
+        values: {},
+        failures: [
+            {
+                name: '<document>',
+                message: 'this host has no isolate configured, so scripts cannot run.',
+                kind: 'capability-denied',
+            },
+        ],
+        cacheSnapshot,
+    };
+}
+/**
+ * The one `spawnRun` adapter every Node host (`apps/vscode`, `apps/cli`)
+ * used to duplicate (survey A6), plus the browser-isolate path Obsidian's
+ * own `spawnRun` wrapper needed. Dispatches on `HostIsolate`'s
+ * discriminated union: a `'node'` host supplies only a worker path; a
+ * `'browser'` host supplies an async, disposable `IsolateSpawner` factory,
+ * disposed once this run's spawner has been used.
+ */
+export async function spawnRunViaAdapter(isolate, options) {
+    if (!isolate)
+        return noIsolateResult(options.cacheSnapshot);
+    if (isolate.kind === 'node') {
+        return spawnRunHost({
+            ...options,
+            workerPath: isolate.workerPath(),
+            spawnIsolate: isolate.spawnIsolate,
+        });
+    }
+    const spawner = await isolate.spawner();
+    try {
+        return await spawnRunHost({
+            ...options,
+            spawnIsolate: spawner,
+            // A blob-URL Web Worker has no entry path, but `spawnRun` still
+            // labels the entry it handed out. Naming the label here keeps a
+            // meaningless path out of the browser branch.
+            workerPath: isolate.entryLabel ?? BROWSER_ISOLATE_ENTRY,
+        });
+    }
+    finally {
+        isolate.dispose();
+    }
+}
+/**
+ * Runs one manual, auto, or scheduled pass of `request.text`'s scripts,
+ * exactly as `runOnce` already does (the grant flow prompts only on a
+ * miss, and only for `'manual'`), but with every host-shaped input —
+ * `spawnRun`, the three grant prompts, the memento, the last-run clock —
+ * supplied from `adapter` instead of assembled ad hoc per app. Writes the
+ * `RunTrace` through `writeLastRunTrace` using `adapter.now()`, never
+ * `Date.now()` directly, so a fixed clock in a test fake makes the trace
+ * byte-stable.
+ */
+export async function runViaAdapter(adapter, request, overrideSpawnRun) {
+    const prompts = promptsFromAdapter(adapter);
+    const spawn = overrideSpawnRun ??
+        ((options) => spawnRunViaAdapter(adapter.isolate, options));
+    let result;
+    try {
+        result = await runOnce({
+            documentKey: request.documentKey,
+            text: request.text,
+            trigger: request.trigger,
+            memento: adapter.memento,
+            ...prompts,
+            spawnRun: spawn,
+            timeoutMs: request.timeoutMs ?? RUN_TIMEOUT_MS,
+            ...(request.netPolicy !== undefined
+                ? { netPolicy: request.netPolicy }
+                : {}),
+            ...(request.bundle !== undefined ? { bundle: request.bundle } : {}),
+            ...(request.packModules !== undefined
+                ? { packModules: request.packModules }
+                : {}),
+            ...(request.onValue !== undefined ? { onValue: request.onValue } : {}),
+        });
+    }
+    catch (err) {
+        // A run that threw is still a failure with two homes: the diagnostics
+        // line and a failed trace for the in-note marker. The caller keeps its
+        // own visible surface (a notice), so the error is rethrown.
+        const detail = err instanceof Error ? err.message : String(err);
+        adapter.diagnostics(runCrashDiagnosticLine(request.trigger, detail));
+        await writeLastRunTrace(adapter.memento, request.documentKey, {
+            trigger: request.trigger,
+            ranAt: adapter.now(),
+            ok: false,
+            reason: detail,
+        }).then(undefined, () => { });
+        throw err;
+    }
+    // The failure's second home (AGENTS.md, "clean is not silent"): one line
+    // per failed script and per declaration mismatch, written here once so no
+    // host can forget it.
+    for (const line of runDiagnosticLines(request.trigger, result)) {
+        adapter.diagnostics(line);
+    }
+    const trace = {
+        trigger: request.trigger,
+        ranAt: adapter.now(),
+        ok: result.failures.length === 0,
+        ...(result.failures.length > 0
+            ? {
+                reason: `${result.failures.length} script${result.failures.length === 1 ? '' : 's'} failed`,
+            }
+            : {}),
+    };
+    // Best-effort, matching both apps' own posture: a trace-write failure
+    // must never turn a successful (or already-reported) run into a thrown
+    // error.
+    await writeLastRunTrace(adapter.memento, request.documentKey, trace).then(undefined, () => { });
+    return { ...result, trace };
+}

package/dist/host/run-diagnostics.d.ts

@@ -0,0 +1,26 @@
+import type { RunTrigger } from '@markii/runtime';
+import type { RunOnceResult } from '../run/run-flow.js';
+/**
+ * The lines a host's diagnostics surface gets for one run's script
+ * failures (GitHub issue #37), moved here from
+ * `apps/vscode/src/run-diagnostics.ts` so Obsidian gains the same
+ * behavior instead of writing its own copy (it previously wrote each
+ * failure to its console ad hoc; VS Code showed them only as value-marker
+ * tooltips and the run marker, which a hidden or collapsed marker can
+ * bury). This is the "second home" AGENTS.md's "clean is not silent" rule
+ * requires: one line per failed script, with its name, its failure kind,
+ * and the same short reason the tooltip carries. No failures, no lines:
+ * the surface stays quiet on a clean run.
+ */
+export declare function formatRunFailureLines(failures: RunOnceResult['failureDetails']): string[];
+/**
+ * Every diagnostics line one completed run owes the host's surface, in
+ * the order they are written: a header and one indented line per failed
+ * script (the "second home" of each failure, `formatRunFailureLines`),
+ * then a header and the lines of any net-declaration mismatch. A clean
+ * run with agreeing declarations returns no lines, so an empty surface
+ * still means nothing went wrong.
+ */
+export declare function runDiagnosticLines(trigger: RunTrigger, result: Pick<RunOnceResult, 'failureDetails' | 'netDeclarationDiagnostics'>): string[];
+/** The one line a run that threw (rather than returning failures) owes the diagnostics surface. */
+export declare function runCrashDiagnosticLine(trigger: RunTrigger, detail: string): string;