@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/migrate/recent-agents.js

@@ -0,0 +1,100 @@
+/**
+ * Recent foreign-agent activity detection for the migration hint.
+ *
+ * "Did the user just come from another coding agent?" is answered from file
+ * mtimes inside each source store: an active conversation appends to its
+ * log in real time (claude-code updates within the same minute), so the
+ * NEWEST file mtime per source is a faithful last-activity signal with good
+ * separation (measured on a real machine: 0min vs 117min vs 5867min across
+ * sources). Parent-directory mtimes would miss appends to existing
+ * conversations, so the scan is file-level — bounded by the same
+ * name-matching walk as the list-mode counter (sub-second at ~3000 files)
+ * and meant for a BACKGROUND pass, never the render path.
+ *
+ * Split: `recentAgentsFrom` is a pure judgment over collected samples
+ * (directly testable with fixture mtimes); `collectNewestMtime` is the IO
+ * collector; `detectRecentAgents` binds them for the TUI.
+ *
+ * @module dsh-cli/migrate/recent-agents
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** How recent the newest source activity must be to earn a hint. */
+export const RECENT_ACTIVITY_WINDOW_MS = 20 * 60 * 1000;
+/**
+ * Pure judgment: which samples count as recent, newest first.
+ * @param samples - one per source, `null` mtime = no data (never recent).
+ * @param nowMs - the current epoch milliseconds (injected for testability).
+ * @param windowMs - activity window, default 20 minutes.
+ */
+export function recentAgentsFrom(samples, nowMs, windowMs = RECENT_ACTIVITY_WINDOW_MS) {
+    const recent = [];
+    for (const sample of samples) {
+        if (sample.newestMtimeMs === null)
+            continue;
+        const age = nowMs - sample.newestMtimeMs;
+        if (age < 0 || age > windowMs)
+            continue;
+        recent.push({ agentId: sample.agentId, label: sample.label, minutesAgo: Math.floor(age / 60_000) });
+    }
+    recent.sort((a, b) => a.minutesAgo - b.minutesAgo);
+    return recent;
+}
+/**
+ * Newest file mtime under one set of roots, name-matched only (the counter's
+ * walk shape — no parsing). Returns null when nothing matches or IO fails;
+ * failures must read as "no data", never as "long ago".
+ */
+export function collectNewestMtime(roots, fileMatch, maxDepth) {
+    const match = fileMatch;
+    let newest = null;
+    const walk = (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(path, depth + 1);
+                continue;
+            }
+            if (!entry.isFile() || !match(entry.name))
+                continue;
+            try {
+                const mtimeMs = statSync(path).mtimeMs;
+                if (newest === null || mtimeMs > newest)
+                    newest = mtimeMs;
+            }
+            catch {
+                // A stat race on one file costs that file, not the scan.
+            }
+        }
+    };
+    for (const root of roots)
+        walk(root, 0);
+    return newest;
+}
+/**
+ * Collect one sample per adapter that can describe its scan; adapters
+ * without count() (no name-only scan shape) are skipped, not guessed.
+ */
+export function collectActivitySamples(adapters, scanOf) {
+    const samples = [];
+    for (const adapter of adapters) {
+        const spec = scanOf(adapter);
+        if (spec === undefined)
+            continue;
+        samples.push({
+            agentId: adapter.id,
+            label: adapter.label,
+            newestMtimeMs: collectNewestMtime(adapter.roots(), spec.fileMatch, spec.maxDepth),
+        });
+    }
+    return samples;
+}

package/lib/types/dsh-adapter/migrate/sessionize.d.ts

@@ -0,0 +1,19 @@
+import { SessionId, type SessionEvent, type SessionHeader } from '@deepseek-ai/dsh-session';
+import type { MigrationSession } from './types.js';
+/** One migration turn's model-visible outcome, ready for persistence. */
+export interface SessionizedLog {
+    readonly header: SessionHeader;
+    readonly events: readonly SessionEvent[];
+}
+/**
+ * Build one official DSH session log from a normalized foreign conversation.
+ *
+ * @param id - deterministic session id (see uuid.ts); the id IS the dedupe.
+ * @param agentId - source adapter id, stamped into assistant provenance as
+ *   `migrated:<agentId>` so the transcript can name where text came from.
+ * @param session - the normalized foreign conversation.
+ * @returns the official header plus the full event log, exactly as the
+ *   persistence backend expects them.
+ */
+export declare function sessionize(id: SessionId, agentId: string, session: MigrationSession): SessionizedLog;
+//# sourceMappingURL=sessionize.d.ts.map

package/lib/types/dsh-adapter/migrate/sessionize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionize.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/migrate/sessionize.ts"],"names":[],"mappings":"AAyBA,OAAO,EAGL,SAAS,EACT,KAAK,YAAY,EACjB,KAAK,aAAa,EACnB,MAAM,0BAA0B,CAAA;AACjC,OAAO,KAAK,EAAE,gBAAgB,EAAiB,MAAM,YAAY,CAAA;AAEjE,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAA;CACzC;AAeD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAmDpG"}

package/lib/types/dsh-adapter/migrate/sessionize.js

@@ -0,0 +1,101 @@
+/**
+ * Cross-agent conversation migration: MigrationSession → official DSH events.
+ *
+ * The sessionize step owns NO storage decisions. It drives the official
+ * `Session` logical-event API (`Session.create` + `append`), so envelope
+ * fields (seq/time/id), surface contract and format version come from the
+ * upstream implementation — the part the first iteration of this feature got
+ * wrong by hand-crafting physical log rows. Physical encoding, project
+ * layout, zstd and atomic writes belong to JsonlSessionPersistence (see
+ * index.ts), exactly as scripts/migrate-sessions-to-jsonl.mts does for the
+ * retired sqlite store.
+ *
+ * Turn shape: one migration turn per user message — `turn/start`, the user
+ * message, one step per assistant message that follows before the next user
+ * message, then `turn/end`. A conversation that starts with an assistant
+ * message (source lost its head) opens its turn with no user message; a
+ * trailing user message closes a step-less turn — both are legal log shapes
+ * (a turn with no entered step carries no step events). Tool traffic is not
+ * migrated: source formats cannot replay it faithfully, and the migration
+ * contract is "re-read the conversation", not "resume the task".
+ *
+ * @module dsh-cli/migrate/sessionize
+ */
+import { createAssistantMessage, createUserMessage } from '@deepseek-ai/dsh-llm';
+import { SESSION_FORMAT_VERSION, Session, } from '@deepseek-ai/dsh-session';
+/** Blocks for one migrated message: reasoning first (when the source kept
+ *  one), then the visible text. Empty text with reasoning keeps both blocks
+ *  honest — the projection renders reasoning as its own collapsible row. */
+function assistantBlocks(turn) {
+    const blocks = [];
+    if (turn.reasoning !== undefined && turn.reasoning !== '') {
+        blocks.push({ type: 'reasoning', text: turn.reasoning });
+    }
+    if (turn.text !== '')
+        blocks.push({ type: 'text', text: turn.text });
+    if (blocks.length === 0)
+        blocks.push({ type: 'text', text: '' });
+    return blocks;
+}
+/**
+ * Build one official DSH session log from a normalized foreign conversation.
+ *
+ * @param id - deterministic session id (see uuid.ts); the id IS the dedupe.
+ * @param agentId - source adapter id, stamped into assistant provenance as
+ *   `migrated:<agentId>` so the transcript can name where text came from.
+ * @param session - the normalized foreign conversation.
+ * @returns the official header plus the full event log, exactly as the
+ *   persistence backend expects them.
+ */
+export function sessionize(id, agentId, session) {
+    const header = {
+        version: SESSION_FORMAT_VERSION,
+        id,
+        createdAt: session.startedAt,
+        cwd: session.cwd,
+        isSeeded: false,
+    };
+    const model = Session.create(id, undefined, header);
+    // Collect each append()'s RETURN (a fully enveloped event) instead of the
+    // deprecated snapshotEvents() bulk read — upstream forbids NEW callers of
+    // the latter, and append already returns seq/time-stamped events.
+    const events = [];
+    let turnIndex = 0;
+    let i = 0;
+    const turns = session.turns;
+    while (i < turns.length) {
+        turnIndex += 1;
+        events.push(model.append('turn/start', { turn: turnIndex }));
+        if (turns[i].role === 'user') {
+            events.push(model.append('user/message', createUserMessage({
+                content: [{ type: 'text', text: turns[i].text }],
+                source: { kind: 'user' },
+            }), { surfaceOp: 'append' }));
+            i += 1;
+        }
+        let step = 0;
+        while (i < turns.length && turns[i].role === 'assistant') {
+            step += 1;
+            const turn = turns[i];
+            events.push(model.append('step/start', { turn: turnIndex, step }));
+            events.push(model.append('assistant/message', {
+                turn: turnIndex,
+                step,
+                message: createAssistantMessage({
+                    content: assistantBlocks(turn),
+                    // createAssistantMessage stamps `kind: 'model'` itself; the
+                    // caller-visible provenance is provider + model only.
+                    source: {
+                        provider: `migrated:${agentId}`,
+                        model: turn.model ?? agentId,
+                    },
+                }),
+                stream: [],
+            }, { surfaceOp: 'append' }));
+            events.push(model.append('step/end', { turn: turnIndex, step }));
+            i += 1;
+        }
+        events.push(model.append('turn/end', { turn: turnIndex, reason: { kind: 'completed' } }));
+    }
+    return { header: model.header, events };
+}

package/lib/types/dsh-adapter/migrate/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cross-agent conversation migration: shared types.
+ *
+ * An adapter turns one foreign agent's stored conversation into the neutral
+ * {@link MigrationSession} shape; the sessionizer (see sessionize.ts) then
+ * emits DSH session events. Adapters are read-only against their source and
+ * defensive by default: a malformed line costs that line, never the scan.
+ *
+ * @module dsh-cli/migrate/types
+ */
+/** One conversational turn in a foreign conversation, normalized. */
+export interface MigrationTurn {
+    readonly role: 'user' | 'assistant';
+    readonly text: string;
+    /** Assistant reasoning trace, when the source recorded one. */
+    readonly reasoning?: string;
+    /** Source-recorded model id for an assistant turn, when available. */
+    readonly model?: string;
+    /** Epoch milliseconds when the source recorded the turn. */
+    readonly time: number;
+}
+/** A discovered foreign conversation, ready for conversion. */
+export interface MigrationSession {
+    /** Stable id in the SOURCE store (file uuid, rollout id, …). */
+    readonly sourceId: string;
+    /** Source working directory, when recorded; falls back to the scan root. */
+    readonly cwd: string;
+    /** Conversation title, when the source derived one. */
+    readonly title?: string;
+    readonly startedAt: number;
+    readonly turns: readonly MigrationTurn[];
+}
+/** What one adapter found on disk. */
+export interface MigrationDiscovery {
+    /** Absolute roots that were scanned (reported to the user). */
+    readonly roots: readonly string[];
+    readonly sessions: readonly MigrationSession[];
+}
+/** A migration adapter for one foreign agent. */
+export interface MigrationAdapter {
+    readonly id: string;
+    readonly label: string;
+    /** Absolute source roots this adapter would scan on this machine. */
+    roots(): readonly string[];
+    /** Scan the roots and normalize every readable conversation. */
+    discover(): MigrationDiscovery;
+    /** Cheap per-root file count for list mode (no parsing). Implementations
+     *  that cannot count by name alone may omit this and fall back to
+     *  discover() — the count then equals the parsed session total. */
+    count?(): number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/dsh-adapter/migrate/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/migrate/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CACzC;AAED,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC/C;AAED,iDAAiD;AACjD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,qEAAqE;IACrE,KAAK,IAAI,SAAS,MAAM,EAAE,CAAA;IAC1B,gEAAgE;IAChE,QAAQ,IAAI,kBAAkB,CAAA;IAC9B;;uEAEmE;IACnE,KAAK,CAAC,IAAI,MAAM,CAAA;CACjB"}

package/lib/types/dsh-adapter/migrate/types.js

@@ -0,0 +1,11 @@
+/**
+ * Cross-agent conversation migration: shared types.
+ *
+ * An adapter turns one foreign agent's stored conversation into the neutral
+ * {@link MigrationSession} shape; the sessionizer (see sessionize.ts) then
+ * emits DSH session events. Adapters are read-only against their source and
+ * defensive by default: a malformed line costs that line, never the scan.
+ *
+ * @module dsh-cli/migrate/types
+ */
+export {};

package/lib/types/dsh-adapter/migrate/uuid.d.ts

@@ -0,0 +1,7 @@
+/**
+ * RFC 4122 UUIDv5 over the migration namespace.
+ * @param name - The distinguishing name (e.g. `claude-code:<file uuid>`).
+ * @returns Dashed lowercase uuid v5.
+ */
+export declare function migrationUuid(name: string): string;
+//# sourceMappingURL=uuid.d.ts.map

package/lib/types/dsh-adapter/migrate/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../../../../src/dsh-adapter/migrate/uuid.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD"}

package/lib/types/dsh-adapter/migrate/uuid.js

@@ -0,0 +1,25 @@
+/**
+ * Deterministic UUIDv5 for migration ids.
+ *
+ * Re-importing the same source conversation must land on the SAME DSH
+ * session id, so repeats overwrite their own copy instead of stacking
+ * duplicates — the id IS the dedupe. Inline SHA-1 RFC 4122 variant (no
+ * runtime dependency; node:crypto does the hashing).
+ *
+ * @module dsh-cli/migrate/uuid
+ */
+import { createHash } from 'node:crypto';
+/** This project's migration namespace: dsh-tui-migrate as 16 fixed bytes. */
+const NAMESPACE = Buffer.from([0x9f, 0x1d, 0x3a, 0x72, 0x6c, 0x55, 0x4c, 0x8e, 0xb0, 0x2f, 0x6d, 0x69, 0x67, 0x72, 0x61, 0x74]);
+/**
+ * RFC 4122 UUIDv5 over the migration namespace.
+ * @param name - The distinguishing name (e.g. `claude-code:<file uuid>`).
+ * @returns Dashed lowercase uuid v5.
+ */
+export function migrationUuid(name) {
+    const hash = createHash('sha1').update(NAMESPACE).update(name, 'utf8').digest();
+    hash[6] = (hash[6] & 0x0f) | 0x50;
+    hash[8] = (hash[8] & 0x3f) | 0x80;
+    const hex = hash.subarray(0, 16).toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}

package/lib/types/dsh-adapter/packaged-presets.d.ts

@@ -0,0 +1,22 @@
+export interface PackagedPresetResult {
+    id: string;
+    status: 'installed' | 'updated' | 'current' | 'conflict';
+}
+export interface PackagedPresetOptions {
+    dshHome?: string;
+    sourceRoot?: string;
+    moduleUrl?: string;
+}
+/** Resolve the package asset in both src/tsx and compiled npm layouts. */
+export declare function packagedPresetRoot(moduleUrl?: string): string;
+/**
+ * Materialize presets shipped by dsh-tui into the Harness user preset root.
+ *
+ * The official launcher replaces the roster's configured roots with its own
+ * shipped root at the end of profile composition, so a bundle patch cannot
+ * add a second system root. The user root is the roster's supported extension
+ * seam and is discovered on every list/resolve call. Existing unmarked
+ * directories are never overwritten.
+ */
+export declare function ensurePackagedPresets(options?: PackagedPresetOptions): PackagedPresetResult[];
+//# sourceMappingURL=packaged-presets.d.ts.map

package/lib/types/dsh-adapter/packaged-presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packaged-presets.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/packaged-presets.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,CAAA;CACzD;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAmBD,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,SAAS,GAAE,MAAwB,GAAG,MAAM,CAQ9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,qBAA0B,GAAG,oBAAoB,EAAE,CAqDjG"}

package/lib/types/dsh-adapter/packaged-presets.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const OWNER = 'dsh-cli';
+const LEGACY_OWNER = '@deepseek-harness-tui/dsh-tui';
+const MARKER = '.dsh-tui-managed.json';
+function readMarker(directory) {
+    try {
+        const value = JSON.parse(readFileSync(join(directory, MARKER), 'utf8'));
+        if ((value.owner === OWNER || value.owner === LEGACY_OWNER)
+            && typeof value.preset === 'string'
+            && typeof value.revision === 'string'
+            && value.revision.length > 0) {
+            return value;
+        }
+    }
+    catch {
+        // An absent or user-authored marker means this directory is not ours.
+    }
+    return undefined;
+}
+/** Resolve the package asset in both src/tsx and compiled npm layouts. */
+export function packagedPresetRoot(moduleUrl = import.meta.url) {
+    const directory = dirname(fileURLToPath(moduleUrl));
+    const candidates = [join(directory, '../../presets'), join(directory, '../../../presets')];
+    const found = candidates.find(candidate => existsSync(candidate));
+    if (found === undefined) {
+        throw new Error(`dsh-tui: packaged preset root is missing (checked ${candidates.join(', ')})`);
+    }
+    return found;
+}
+/**
+ * Materialize presets shipped by dsh-tui into the Harness user preset root.
+ *
+ * The official launcher replaces the roster's configured roots with its own
+ * shipped root at the end of profile composition, so a bundle patch cannot
+ * add a second system root. The user root is the roster's supported extension
+ * seam and is discovered on every list/resolve call. Existing unmarked
+ * directories are never overwritten.
+ */
+export function ensurePackagedPresets(options = {}) {
+    const sourceRoot = options.sourceRoot ?? packagedPresetRoot(options.moduleUrl);
+    const dshHome = options.dshHome ?? process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    const targetRoot = join(dshHome, '.agent-presets');
+    const results = [];
+    for (const entry of readdirSync(sourceRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const id = entry.name;
+        const source = join(sourceRoot, id);
+        const sourceMarker = readMarker(source);
+        if (sourceMarker === undefined || sourceMarker.preset !== id) {
+            throw new Error(`dsh-tui: packaged preset ${id} has no valid ${MARKER}`);
+        }
+        const target = join(targetRoot, id);
+        if (!existsSync(target)) {
+            mkdirSync(targetRoot, { recursive: true });
+            // `filter` forces the JS copy path (see src/utils/paths.ts): the native
+            // cpSync fast path fails with EIO or crashes under a non-ASCII home
+            // directory such as `C:\Users\米`.
+            cpSync(source, target, { recursive: true, force: false, errorOnExist: true, filter: () => true });
+            results.push({ id, status: 'installed' });
+            continue;
+        }
+        const targetMarker = readMarker(target);
+        if (targetMarker === undefined || targetMarker.preset !== id) {
+            results.push({ id, status: 'conflict' });
+            continue;
+        }
+        if (targetMarker.revision === sourceMarker.revision) {
+            results.push({ id, status: 'current' });
+            continue;
+        }
+        const suffix = `${process.pid}-${randomUUID()}`;
+        const staged = join(targetRoot, `.${id}.staged-${suffix}`);
+        const backup = join(targetRoot, `.${id}.backup-${suffix}`);
+        cpSync(source, staged, { recursive: true, force: false, errorOnExist: true, filter: () => true });
+        try {
+            renameSync(target, backup);
+            renameSync(staged, target);
+            rmSync(backup, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (!existsSync(target) && existsSync(backup))
+                renameSync(backup, target);
+            rmSync(staged, { recursive: true, force: true });
+            throw error;
+        }
+        results.push({ id, status: 'updated' });
+    }
+    return results;
+}

package/lib/types/dsh-adapter/plugin-host.d.ts

@@ -0,0 +1,205 @@
+/**
+ * The dsh-tui-plugin-host row: the plugin-interop anchor every later
+ * contract surface hangs off (storage.local, messages.observe, effect
+ * ledger — each lands as a sibling service mounted by THIS row's apply, so
+ * the patch surface changed exactly once for the whole v0.15 alignment).
+ *
+ * What it provides on `ctx.tuiPluginHost`:
+ *
+ * - `generationId` — the runtime generation id (C-050), a fresh UUID per
+ *   row activation; ledger records and the Host Descriptor stamp it so
+ *   effects from different process generations can never be confused.
+ * - `grants` — the unified 8-permission live GrantStore
+ *   (`../adapter/standard/grants.js`).
+ * - `hostDescriptor()` — the C-010 Host Descriptor
+ *   (`../adapter/standard/descriptor.js`), built lazily and cached; drifted
+ *   contracts are dropped fail-closed.
+ * - `selfCheck()` — vendored registry + contract-profile violations
+ *   (definition/profile drift, ten-point incompleteness, parity mismatches).
+ * - `registerCommand(pluginCtx, definition)` — the MEDIATED command
+ *   registration surface (C-041 attribution): stamps each command with the
+ *   verified Component identity so the invoke checkpoint can enforce per-owner
+ *   denies (./command-attribution.js). Direct `ctx.get('commands')`
+ *   registrations stay unattributed — the documented C-070 boundary.
+ *
+ * Discipline notes:
+ *
+ * - #183: consumers NEVER get this service via inject — always
+ *   `ctx.get('tuiPluginHost', false)` soft probing, with the skew warning in
+ *   plugin.ts covering profile launches on a stale patch.
+ * - The D-7 decision gate does NOT depend on this row: the extensions row
+ *   and the channel each install it with their own GrantStore read, so a
+ *   missing plugin-host row never relaxes interception gating.
+ * - Boot-time self-check failures are logged once here (fail closed happens
+ *   per-contract at descriptor build time; boot must not die on drifted
+ *   vendored data).
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { CommandDefinition } from '@deepseek-ai/dsh-commands';
+import type { HostDescriptor } from '../adapter/standard/types.js';
+import { type HostDescriptorBuild } from '../adapter/standard/descriptor.js';
+import { type DecisionRegistrationOptions } from './decision-guard.js';
+import { type VerifiedComponentIdentity } from './component-identity.js';
+/** Caller-safe grant facade exposed through `ctx.tuiPluginHost.grants`.
+ * Unlike the internal full-parameter GrantStore, this facade derives the
+ * principal from the calling activation and never accepts a caller-supplied
+ * component/activation identity. The legacy `.corrupt` boolean is
+ * deliberately not exposed here; use `selfCheck()` / `/doctor` or host-side
+ * diagnostics for grant-file health. */
+export interface HostGrantFacade {
+    /** Evaluate a grant for the calling activation, not an arbitrary principal. */
+    allows(pluginCtx: Context, permission: string, scope: string): boolean;
+    defaultOf(permission: string): 'allow' | 'deny';
+    knownPermissions(): readonly string[];
+    /**
+     * File-change watch, used by grant-owned effects to release promptly.
+     *
+     * This is a subscribe-class adapter capability. The caller activation is
+     * required both for shadow-policy enforcement and for lifecycle binding:
+     * the returned watcher (and the underlying file poller's registration) is
+     * owned by the calling Cordis activation, so unloading that activation
+     * cannot leave the listener or the poller behind.
+     */
+    onChange(pluginCtx: Context, listener: () => void): (() => void) | undefined;
+}
+/** Public, mediated plugin-host capability. Loader-only admission remains
+ * behind getHostAdmission(), which is deliberately omitted from the package
+ * export surface. */
+export interface TuiPluginHost {
+    readonly generationId: string;
+    readonly grants: HostGrantFacade;
+    hostDescriptor(): HostDescriptor;
+    describe(): HostDescriptorBuild;
+    subscribeDecision(pluginCtx: Context, event: string, listener: (payload: Record<string, unknown>) => unknown, options?: {
+        scope?: string;
+        order?: string;
+    }): () => boolean;
+    registerCommand(pluginCtx: Context, definition: CommandDefinition): () => void;
+    registerCommand(pluginCtx: Context, contributionId: string, definition: CommandDefinition): () => void;
+    selfCheck(): string[];
+    /** Read-only DecisionEvents feature probe (host/driver diagnostics). */
+    probeDecisionEvents(): readonly string[];
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        tuiPluginHost: TuiPluginHost;
+    }
+}
+/** `ctx.tuiPluginHost` — plugin-interop anchor (generation, grants, descriptor). */
+export declare class TuiPluginHostRuntime extends Service implements TuiPluginHost {
+    #private;
+    /** Runtime generation id (C-050): fresh per activation of this row. */
+    get generationId(): string;
+    /** Caller-safe grant facade; the internal full-parameter store stays
+     * host-only (see getHostGrantStore in ./host-grants.js). */
+    get grants(): HostGrantFacade;
+    /** Read-only DecisionEvents feature probe. Returns only the event names
+     * whose guard is installed in this composition. */
+    probeDecisionEvents(): readonly string[];
+    constructor(ctx: Context);
+    /** @internal Start the Kernel after the whole plugin-host row (including
+     * sibling storage/observer services) is mounted. Called from `apply()`; not
+     * part of the public plugin surface. */
+    startKernelRuntime(): void;
+    private assertEffect;
+    /**
+     * The C-010 Host Descriptor, built lazily and cached while the
+     * runtime-dependent commands capability remains unchanged.
+     */
+    hostDescriptor(): HostDescriptor;
+    /** The full build result (descriptor + dropped coordinates + warnings). */
+    describe(): HostDescriptorBuild;
+    private build;
+    private buildUnsafe;
+    /**
+     * Parse, project, validate, negotiate, and bind one activation's Component
+     * identity before any mediated runtime capability can be used.
+     */
+    admit(pluginCtx: Context, source: string, options?: {
+        source?: string;
+    }): VerifiedComponentIdentity;
+    /** @internal Host loader entry; the unexported production token prevents
+     * proxy calls. The test token is only reachable from the test-only adapter
+     * helper, never from the package's production admission accessor. */
+    admitInternal(pluginCtx: Context, source: string, options?: {
+        source?: string;
+        activationId?: string;
+    }, token?: symbol): VerifiedComponentIdentity;
+    /**
+     * Host-mediated DecisionEvents activation surface.  A plugin cannot use a
+     * raw `ctx.on` for these points: the verified Component identity, static
+     * requirement, scope and current grant are all checked before insertion in
+     * the registry.  The returned disposer is idempotent and is also owned by
+     * the activation so deactivation cannot leave an effect behind.
+     */
+    subscribeDecision(pluginCtx: Context, event: string, listener: (payload: Record<string, unknown>) => unknown, options?: DecisionRegistrationOptions): () => boolean;
+    /**
+     * Mediated command registration (C-041 attribution): registers through
+     * the commands service and, on success, stamps the command's owner as
+     * the verified Component identity — so the channel's invoke checkpoint
+     * can enforce per-owner `commands.invoke` denies on the host-mediated
+     * path. Mirrors the honest-identity pattern of storage.open /
+     * messages.observe subscribe: there is no parameter to impersonate
+     * another plugin. The returned disposer unregisters AND lifts the stamp
+     * (idempotent). Duplicates throw the mapped DUPLICATE_CONTRIBUTION_ID
+     * error; a missing commands service fails loud (the descriptor's
+     * Command contract is excluded in that situation anyway).
+    */
+    registerCommand(pluginCtx: Context, definition: CommandDefinition): () => void;
+    registerCommand(pluginCtx: Context, contributionId: string, definition: CommandDefinition): () => void;
+    /**
+     * Vendored registry + contract-profile self-check (C-020 definition/profile
+     * pins, C-040 ten-point completeness, coordinate/permission parity). Empty =
+     * clean; violations are strings, never thrown.
+     */
+    selfCheck(): string[];
+}
+/** Initial host-owned Kernel refresh outcome. This is adapter-test-only
+ * readiness evidence, not a plugin capability or a Kernel control surface. */
+export interface InitialKernelRefreshResult {
+    readonly status: 'pending' | 'completed' | 'failed' | 'skipped';
+    readonly error?: string;
+}
+/**
+ * Loader-only admission capability.  It is intentionally omitted from the
+ * package `plugin-host` export; tests and the in-process loader can obtain it
+ * from this adapter module, while a plugin calling the public service proxy
+ * receives a deterministic denial instead of being able to impersonate a
+ * different manifest identity.
+ */
+export interface HostAdmission {
+    admit(pluginCtx: Context, source: string, options?: {
+        source?: string;
+    }): VerifiedComponentIdentity;
+}
+/** Test-only admission accessor. Kept separate from the production
+ * `getHostAdmission` so the test-utils injection of a deterministic
+ * activationId can never be reached by production host loaders. */
+export interface HostAdmissionForTest extends HostAdmission {
+    admit(pluginCtx: Context, source: string, options?: {
+        source?: string;
+        activationId?: string;
+    }): VerifiedComponentIdentity;
+}
+/** Adapter-test-only readiness accessor. It exposes only the host-owned
+ * initial refresh promise/result; callers cannot inspect or control KernelRuntime. */
+export interface HostInitialKernelRefreshForTest {
+    result(): InitialKernelRefreshResult | undefined;
+    awaitResult(): Promise<InitialKernelRefreshResult>;
+}
+export declare function getHostInitialKernelRefreshForTest(runtime: TuiPluginHost | TuiPluginHostRuntime | undefined): HostInitialKernelRefreshForTest | undefined;
+export declare function getHostAdmissionForTest(runtime: TuiPluginHost | TuiPluginHostRuntime | undefined): HostAdmissionForTest | undefined;
+export declare function getHostAdmission(runtime: TuiPluginHost | TuiPluginHostRuntime | undefined): HostAdmission | undefined;
+/**
+ * Host-only accessor for the new Kernel HostFacade. Deliberately omitted from
+ * the public plugin-host export: HostFacade is an internal composition entry,
+ * not an external plugin API.
+ *
+ * @internal P2: the facade is now backed by the KernelRuntime's unified
+ * evidence snapshot (driver detect + live verification), not by a legacy
+ * describe() wrapper. It remains read-only and shadow-guarded.
+ */
+export declare function getHostFacade(runtime: TuiPluginHost | TuiPluginHostRuntime | undefined): import("../adapter/index.js").HostFacade | undefined;
+export declare const name = "dsh-tui-plugin-host";
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=plugin-host.d.ts.map