@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/effect-ledger.js

@@ -0,0 +1,290 @@
+/**
+ * Effect ledger (C-060): an append-only JSONL journal of plugin-visible
+ * effects at `~/.dsh-tui/effect-ledger.jsonl`, mounted by the
+ * dsh-tui-plugin-host row as `ctx.tuiEffectLedger`.
+ *
+ * Every record carries the lifecycle triple:
+ *
+ * - `pluginId` — derived from the verified Component identity bound to the
+ *   PASSED activation. `'host'` is used for host/root records and
+ *   `'undeclared'` for a plugin-facing call without a verified identity; a
+ *   display fiber name is never trusted as authorization identity.
+ * - `activationInstance` — stable per cordis fiber for the lifetime of this
+ *   process (first-seen assignment from a WeakMap), so a hot-reloaded plugin
+ *   shows up as a NEW instance while all effects of one activation share one
+ *   id.
+ * - `runtimeGenerationId` — the plugin-host row's generation (C-050), so
+ *   records from different process generations can never be confused.
+ *
+ * Recording rules:
+ *
+ * - FAIL-CLOSED ON SCHEMA: every record is validated against the vendored
+ *   `effect-ledger-record.schema.json` BEFORE it is appended; a record that
+ *   fails is dropped with a warning, never written. A missing vendored
+ *   schema suppresses ALL writes (warned once) — the same posture as the
+ *   messages.observe envelope check. The schema's `additionalProperties:
+ *   false` is what structurally bans secrets from the ledger: callers
+ *   cannot smuggle payload fields through.
+ * - SEQUENCE: continues across restarts (max sequence in the existing file
+ *   + 1); corrupt lines are skipped, never rewritten.
+ * - NEVER THROWS: recording is observability, not a gate — internal errors
+ *   (including disk failures) are caught and warned, the caller's path is
+ *   unaffected.
+ *
+ * privacyClass: operational — records hold identifiers and error codes,
+ * never message content, storage values, or grant-file contents.
+ */
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Context, Service } from '@deepseek-ai/cordis';
+import { DATA_DIR } from '../utils/paths.js';
+import { loadSpecData } from '../adapter/standard/registry.js';
+import { check } from '../adapter/standard/schema-check.js';
+import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
+import { componentIdentityOf } from './component-identity.js';
+import { compositionRoot, concreteService } from './host-access.js';
+import { createKernelLedger } from '../adapter/kernel/ledger.js';
+/** Default ledger file (JSONL, one record per line). */
+export const EFFECT_LEDGER_FILE = join(DATA_DIR, 'effect-ledger.jsonl');
+/** Resource kinds recorded by the host's wired emitters. */
+export const LEDGER_RESOURCE_KINDS = [
+    'command',
+    'scene',
+    'shortcut',
+    'status',
+    'renderer',
+    'theme',
+    'storage-namespace',
+    'subscription',
+    'permission',
+];
+/** Strip control chars and cap length so a hostile id cannot break the JSONL
+ *  line format or blow the schema bounds (JSON.stringify would keep the line
+ *  intact, but downstream tooling reads these fields raw). */
+function cleanField(value, max, fallback) {
+    if (typeof value !== 'string')
+        return fallback;
+    const cleaned = value.replace(/[\x00-\x1f\x7f-\x9f]/g, '').slice(0, max);
+    return cleaned === '' ? fallback : cleaned;
+}
+/** `ctx.tuiEffectLedger` — append-only effect journal (C-060). */
+export class TuiEffectLedgerRuntime extends Service {
+    constructor(ctx, options = {}) {
+        super(ctx, 'tuiEffectLedger');
+        const file = options.file ?? EFFECT_LEDGER_FILE;
+        // The generation is resolved LAZILY (per first record): cordis does not
+        // make sibling services visible to constructors of plugins mounted later
+        // by the same apply(), so a constructor-time probe would always miss the
+        // plugin-host service and fall back to 'unknown-generation'.
+        const state = {
+            hostContext: compositionRoot(ctx),
+            file,
+            optionsGenerationId: options.generationId,
+            generationId: undefined,
+            activations: new WeakMap(),
+            nextActivation: 1,
+            sequence: 0,
+            schemaWarned: false,
+            runtime: adapterRuntimeFor(ctx),
+            ledgerSchema: undefined,
+            kernelLedger: undefined,
+        };
+        // `'ledgerSchema' in options` lets a caller force-undefined (fail-closed
+        // test seam), same contract as the message observer's envelopeSchema.
+        state.ledgerSchema = 'ledgerSchema' in options ? options.ledgerSchema : loadSpecData()?.schemas.ledger;
+        state.sequence = resumeSequence(file);
+        // Route every public ledger write through the unified Kernel ledger
+        // channel. The kernel ledger performs shadow-policy enforcement and
+        // owner derivation; this class only serializes the normalized record to
+        // the existing JSONL file.
+        state.kernelLedger = createKernelLedger(record => this.appendKernelRecord(record, state), state.runtime.mode, context => this.resolveKernelOwner(context, state), state.runtime.slices);
+        ledgerStates.set(this, state);
+    }
+    /**
+     * Append one record. `identity` is the caller's own context (plugins pass
+     * their plugin ctx through the managed services' optional trailing
+     * parameter); omitting it records `undeclared`, never a guess.
+     */
+    record(entry, identity) {
+        const state = ledgerStateFor(this);
+        // The Kernel ledger is the single owner-deriving write channel. It
+        // asserts shadow policy and calls back with a kernel-resolved owner.
+        try {
+            state.kernelLedger.record(entry, identity);
+        }
+        catch {
+            // Ledger writes are explicitly best-effort and must not affect the seam.
+        }
+    }
+    /** Append one kernel-resolved record to the JSONL file. */
+    appendKernelRecord(kernelRecord, state) {
+        try {
+            if (state.ledgerSchema === undefined) {
+                if (!state.schemaWarned) {
+                    state.schemaWarned = true;
+                    state.hostContext.logger.warn('dsh-tui: effect ledger schema unavailable - suppressing all ledger writes (fail-closed)');
+                }
+                return;
+            }
+            const { entry, owner } = kernelRecord;
+            const pluginId = cleanField(owner.componentId, 128, 'undeclared');
+            const activationInstance = cleanField(owner.activationId ?? pluginId, 128, pluginId);
+            const record = {
+                ledgerVersion: '0.15',
+                sequence: state.sequence,
+                timestamp: new Date().toISOString(),
+                pluginId,
+                activationInstance,
+                runtimeGenerationId: this.generation(),
+                operation: entry.operation,
+                resource: {
+                    kind: cleanField(entry.resource?.kind, 64, 'unknown'),
+                    id: cleanField(entry.resource?.id, 128, 'unknown'),
+                },
+                result: entry.result,
+                ...(entry.errorCode !== undefined ? { errorCode: cleanField(entry.errorCode, 64, 'UNKNOWN') } : {}),
+                ...(entry.replaces !== undefined
+                    ? {
+                        replaces: {
+                            ...(entry.replaces.resourceId !== undefined
+                                ? { resourceId: cleanField(entry.replaces.resourceId, 128, 'unknown') }
+                                : {}),
+                            ...(entry.replaces.activationInstance !== undefined
+                                ? { activationInstance: cleanField(entry.replaces.activationInstance, 128, 'unknown') }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                ...(entry.valueDigest !== undefined ? { valueDigest: entry.valueDigest } : {}),
+            };
+            try {
+                check(record, state.ledgerSchema, state.ledgerSchema);
+            }
+            catch (error) {
+                state.hostContext.logger.warn(`dsh-tui: effect ledger record dropped (schema: ${error instanceof Error ? error.message : String(error)})`);
+                return;
+            }
+            mkdirSync(dirname(state.file), { recursive: true, mode: 0o700 });
+            appendFileSync(state.file, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+            state.sequence += 1;
+        }
+        catch (error) {
+            state.hostContext.logger.warn('dsh-tui: effect ledger write failed');
+        }
+    }
+    /** Kernel-ledger owner resolver: verified activation identity wins; host /
+     * undeclared fallbacks are explicit and never borrowed from fiber names. */
+    resolveKernelOwner(identity, state) {
+        if (!Context.is(identity)) {
+            return { componentId: 'undeclared', activationId: 'undeclared' };
+        }
+        const verified = componentIdentityOf(identity);
+        if (verified !== undefined) {
+            return { componentId: verified.componentId, activationId: verified.activationId };
+        }
+        const fiber = this.fiberOf(identity);
+        let name = '';
+        try {
+            name = typeof identity.fiber?.name === 'string' ? identity.fiber.name : '';
+        }
+        catch {
+            name = '';
+        }
+        if (fiber === undefined || name === '' || name === 'root') {
+            return { componentId: 'host', activationId: 'host' };
+        }
+        return { componentId: 'undeclared', activationId: this.activationOf(fiber, 'undeclared') };
+    }
+    /** Runtime generation (C-050): options override, else the plugin-host
+     *  service's id — resolved on first record and cached (the host row mounts
+     *  before any caller can record). */
+    generation() {
+        const state = ledgerStateFor(this);
+        if (state.optionsGenerationId !== undefined)
+            return state.optionsGenerationId;
+        state.generationId ??= state.hostContext.get('tuiPluginHost')?.generationId ?? 'unknown-generation';
+        return state.generationId;
+    }
+    /** Continue numbering after the existing file's max sequence (restart-safe). */
+    resumeSequence() {
+        return resumeSequence(ledgerStateFor(this).file);
+    }
+    fiberOf(identity) {
+        if (identity === undefined)
+            return undefined;
+        try {
+            const fiber = identity.fiber;
+            return typeof fiber === 'object' && fiber !== null ? fiber : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    pluginIdOf(identity, fiber, verifiedComponentId) {
+        if (identity === undefined)
+            return 'undeclared';
+        if (verifiedComponentId !== undefined)
+            return cleanField(verifiedComponentId, 128, 'undeclared');
+        let name = '';
+        try {
+            name = typeof identity.fiber?.name === 'string' ? identity.fiber.name : '';
+        }
+        catch {
+            name = '';
+        }
+        // A non-root fiber without a verified Component is intentionally not
+        // attributed by its Cordis export name.  Names are display metadata and
+        // can differ from the manifest identity (or be impersonated).
+        if (fiber === undefined || name === '' || name === 'root')
+            return 'host';
+        return 'undeclared';
+    }
+    activationOf(fiber, pluginId) {
+        // 'host'/'undeclared' are single-tenant identities (one root fiber per
+        // process; 'undeclared' has no fiber at all) — the constant instance id
+        // is exact; per-fiber ids only matter for plugin fibers.
+        if (fiber === undefined || pluginId === 'host' || pluginId === 'undeclared')
+            return pluginId;
+        const state = ledgerStateFor(this);
+        let activation = state.activations.get(fiber);
+        if (activation === undefined) {
+            activation = `activation-${state.nextActivation++}`;
+            state.activations.set(fiber, activation);
+        }
+        return activation;
+    }
+}
+const ledgerStates = new WeakMap();
+function ledgerStateFor(runtime) {
+    const state = ledgerStates.get(concreteService(runtime));
+    if (state === undefined)
+        throw new Error('tuiEffectLedger host state is unavailable');
+    return state;
+}
+/** Continue numbering after the existing file's max sequence (restart-safe). */
+function resumeSequence(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return 0; // missing file = fresh ledger, not corruption
+    }
+    let max = -1;
+    for (const line of text.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            const sequence = parsed.sequence;
+            if (typeof sequence === 'number' && Number.isInteger(sequence) && sequence > max)
+                max = sequence;
+        }
+        catch {
+            // Corrupt line: skip it (never rewritten — the bytes stay for manual
+            // recovery, same posture as plugin-storage).
+        }
+    }
+    return max + 1;
+}
+export default TuiEffectLedgerRuntime;

package/lib/types/dsh-adapter/extension-events.d.ts

@@ -0,0 +1,186 @@
+import type { TuiRewindMode } from '../adapter/ports/channel-session.js';
+export type { TuiRewindMode } from '../adapter/ports/channel-session.js';
+/**
+ * Decision-point events the TUI fires on the cordis bus so plugins can
+ * intercept, cancel, or customize interactive flows — the `session_before_*`
+ * style seam (pi's `session_before_fork` / `input` events) expressed in
+ * cordis dispatch semantics.
+ *
+ * All of these are FIRED BY THE CHANNEL and answered by admitted Components
+ * through the host-mediated DecisionEvents registry. No extra service row is
+ * involved: an absent handler simply means "no opinion", and the built-in
+ * flow proceeds unchanged. Dispatch is SERIAL in the registry's stable order
+ * with the first VALID decision winning — see {@link dispatchTuiDecision} for
+ * why this is not raw `ctx.serial`: per-handler crash isolation, deadlines and
+ * return-value normalization mean a broken or malformed handler can never
+ * skip a later (possibly safety) veto.
+ *
+ * Synchronous-only rule: handlers may be async, but while a decision is
+ * awaited the originating UI flow is parked (the submit is not delivered,
+ * the rewind confirm has not happened). Handlers that need user input should
+ * use the managed dialogs (`ctx.tuiDialogs`) or open a scene, then resolve.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Explicit budgets from the DecisionEvents profile.  A timed-out handler is
+ * treated as no-opinion and the chain continues; once the total budget is
+ * exhausted the remaining handlers are skipped with the same policy. */
+export declare const DECISION_HANDLER_TIMEOUT_MS = 1000;
+export declare const DECISION_TOTAL_TIMEOUT_MS = 5000;
+/**
+ * Dispatch a decision event listener-by-listener in the host's stable order.
+ *
+ * Deliberately NOT `ctx.serial`: cordis bails at ANY non-null/false/undefined
+ * return, so a malformed-but-object decision (a blank `{ text }` rewrite, a
+ * junk primitive) would cut the chain before a later veto listener runs —
+ * and one throwing listener rejects the whole dispatch, skipping every later
+ * listener. Here:
+ *
+ * - a throwing listener is logged and the chain CONTINUES;
+ * - each return value passes through `normalize` (per-event validation)
+ *   INSIDE the same isolation boundary — a Proxy/throwing-getter return is
+ *   logged and skipped like any other invalid shape;
+ * - "no opinion" (undefined/null/false) and invalid shapes are logged and
+ *   the chain CONTINUES;
+ * - the first listener whose NORMALIZED decision is non-undefined wins.
+ *
+ * Handlers come from the host-mediated DecisionEvents registry.  Raw Cordis
+ * `ctx.on` listeners are intentionally absent from this path.
+ */
+export declare function dispatchTuiDecision<T>(ctx: Context, name: string, payload: Record<string, unknown>, normalize: (result: unknown, warn: (what: string) => void) => T | undefined): Promise<T | undefined>;
+/** Fire a non-veto DecisionEvents point with the same bounded, isolated
+ * semantics.  Notifications deliberately ignore every return value. */
+export declare function dispatchTuiNotification(ctx: Context, name: string, payload: Record<string, unknown>): Promise<void>;
+/** Shared normalizer for the veto-only decisions (session-switch, compact):
+ *  `{ cancel: true, reason? }` or no opinion; everything else is ignored.
+ *  The reason is toast-bound plugin text — sanitized (a veto must not
+ *  smuggle control sequences onto the screen). */
+export declare function normalizeCancelDecision(result: unknown, warn: (what: string) => void): {
+    cancel: true;
+    reason?: string;
+} | undefined;
+/** Shared context every decision event carries. */
+export interface TuiDecisionContext {
+    /** The live session (agent) id the flow belongs to. */
+    sessionId: string;
+    /** Working directory of the session. */
+    cwd: string;
+}
+/**
+ * Fired before user-typed text is delivered to the model (`submit` and
+ * `steer`; local `!`/`!!` shell lines never fire it — they are not model
+ * input). The message is NOT yet in the session log; nothing is observable
+ * from the transcript at this point.
+ */
+export interface TuiInputEvent extends TuiDecisionContext {
+    /** The trimmed text as typed. */
+    text: string;
+    /** Where the text would go: a new turn (`followup`) or the running one. */
+    delivery: 'followup' | 'steer';
+}
+export type TuiInputDecision = 
+/** Replace the text; the substitute is delivered instead. */
+{
+    text: string;
+}
+/** The plugin consumed the input itself; nothing is delivered. An optional
+ *  notice is toasted so the user is not left wondering where the line went. */
+ | {
+    handled: true;
+    notice?: string;
+}
+/** Drop the input; an optional reason is toasted as a warning. */
+ | {
+    cancel: true;
+    reason?: string;
+}
+/** No opinion — delivery proceeds unchanged. */
+ | undefined;
+/**
+ * Fired when the rewind picker confirms a message, BEFORE the fork happens.
+ * `seq` is the session event seq of the picked user message (the fork itself
+ * lands just before its turn — see channel.rewindTo).
+ */
+export interface TuiRewindPromptEvent extends TuiDecisionContext {
+    /** Text of the picked message. */
+    text: string;
+    /** Session event seq of the picked message. */
+    seq: number;
+}
+export type TuiRewindPromptDecision = 
+/** Abort the rewind; the picker stays open. Optional reason is toasted. */
+{
+    cancel: true;
+    reason?: string;
+}
+/** Extra choices rendered in the confirm pane on top of the built-in
+ *  conversation-only rewind (which stays option zero). */
+ | {
+    modes: readonly TuiRewindMode[];
+}
+/** No opinion — the plain confirm pane shows, exactly as before. */
+ | undefined;
+/**
+ * Fired after a rewind completed: the forked session is live and the
+ * transcript replayed. The first listener returning a non-empty string has
+ * it toasted as the post-rewind summary (serial bail semantics).
+ */
+export interface TuiRewindDoneEvent extends TuiDecisionContext {
+    /** Text of the message that was rewound to (back in the input). */
+    text: string;
+    /** The mode id the user picked, or null for the built-in
+     *  conversation-only rewind. */
+    mode: string | null;
+    /** Inclusive source seq the fork cut at (the child's seed end). */
+    boundarySeq: number;
+    /** The session that was forked away from. */
+    sourceSessionId: string;
+    /** The freshly created fork session — now the live one. */
+    childSessionId: string;
+}
+/**
+ * Fired before the live session is replaced (`/new` or `/resume`; rewind has
+ * its own prompt event above). `targetSessionId` is set for resume only.
+ */
+export interface TuiSessionSwitchEvent extends TuiDecisionContext {
+    kind: 'new' | 'resume';
+    targetSessionId?: string;
+}
+export type TuiSessionSwitchDecision = 
+/** Abort the switch; the current session stays live. Optional reason is
+ *  toasted as a warning. */
+{
+    cancel: true;
+    reason?: string;
+} | undefined;
+/**
+ * Notification (parallel, fire-and-forget) after the live session changed.
+ * Listener errors are logged, never propagated. Rebind per-session state
+ * here; `previousSessionId` is undefined only when there was nothing live
+ * before (not currently produced — every switch has a live source).
+ */
+export interface TuiSessionSwitchedEvent extends TuiDecisionContext {
+    kind: 'new' | 'resume' | 'rewind' | 'fork';
+    /** The session that just went live. */
+    sessionId: string;
+    previousSessionId?: string;
+}
+/** Fired before manual `/compact` runs. */
+export interface TuiCompactEvent extends TuiDecisionContext {
+}
+export type TuiCompactDecision = 
+/** Abort the compaction; optional reason is toasted as a warning. */
+{
+    cancel: true;
+    reason?: string;
+} | undefined;
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        'tui/input'(event: TuiInputEvent): TuiInputDecision | Promise<TuiInputDecision>;
+        'tui/rewind-prompt'(event: TuiRewindPromptEvent): TuiRewindPromptDecision | Promise<TuiRewindPromptDecision>;
+        'tui/rewind-done'(event: TuiRewindDoneEvent): string | undefined | Promise<string | undefined>;
+        'tui/session-switch'(event: TuiSessionSwitchEvent): TuiSessionSwitchDecision | Promise<TuiSessionSwitchDecision>;
+        'tui/session-switched'(event: TuiSessionSwitchedEvent): void | Promise<void>;
+        'tui/compact'(event: TuiCompactEvent): TuiCompactDecision | Promise<TuiCompactDecision>;
+    }
+}
+//# sourceMappingURL=extension-events.d.ts.map

package/lib/types/dsh-adapter/extension-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extension-events.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/extension-events.ts"],"names":[],"mappings":"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"}

package/lib/types/dsh-adapter/extension-events.js

@@ -0,0 +1,187 @@
+import { cleanScalarText } from './sanitize.js';
+import { DECISION_EVENT_PERMISSIONS, decisionHandlersOf, decisionRegistryOf, } from './decision-guard.js';
+/** Toast-bound plugin text (veto reasons) is render-path data: sanitized
+ *  with the one shared implementation, capped at toast width. */
+const NOTICE_CELLS = 200;
+/** Explicit budgets from the DecisionEvents profile.  A timed-out handler is
+ * treated as no-opinion and the chain continues; once the total budget is
+ * exhausted the remaining handlers are skipped with the same policy. */
+export const DECISION_HANDLER_TIMEOUT_MS = 1000;
+export const DECISION_TOTAL_TIMEOUT_MS = 5000;
+function freezeClone(value) {
+    const seen = new WeakSet();
+    const freeze = (current) => {
+        if (current === null || typeof current !== 'object' || Object.isFrozen(current))
+            return current;
+        if (seen.has(current))
+            return current;
+        seen.add(current);
+        for (const child of Object.values(current))
+            freeze(child);
+        return Object.freeze(current);
+    };
+    let copy;
+    try {
+        copy = structuredClone(value);
+    }
+    catch {
+        // Decision payloads are host-created records.  Keep a defensive fallback
+        // for degraded embedders rather than handing a shared object to a plugin.
+        copy = JSON.parse(JSON.stringify(value));
+    }
+    return freeze(copy);
+}
+async function runBounded(task, timeoutMs) {
+    let timer;
+    const work = Promise.resolve()
+        .then(task)
+        .then(value => ({ kind: 'value', value }), error => ({ kind: 'error', error }));
+    const timeout = new Promise(resolve => {
+        timer = setTimeout(() => resolve({ kind: 'timeout' }), timeoutMs);
+    });
+    try {
+        return await Promise.race([work, timeout]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        // `work` has rejection handlers attached above, so a promise that settles
+        // after a timeout cannot become an unhandled rejection.
+    }
+}
+/**
+ * Dispatch a decision event listener-by-listener in the host's stable order.
+ *
+ * Deliberately NOT `ctx.serial`: cordis bails at ANY non-null/false/undefined
+ * return, so a malformed-but-object decision (a blank `{ text }` rewrite, a
+ * junk primitive) would cut the chain before a later veto listener runs —
+ * and one throwing listener rejects the whole dispatch, skipping every later
+ * listener. Here:
+ *
+ * - a throwing listener is logged and the chain CONTINUES;
+ * - each return value passes through `normalize` (per-event validation)
+ *   INSIDE the same isolation boundary — a Proxy/throwing-getter return is
+ *   logged and skipped like any other invalid shape;
+ * - "no opinion" (undefined/null/false) and invalid shapes are logged and
+ *   the chain CONTINUES;
+ * - the first listener whose NORMALIZED decision is non-undefined wins.
+ *
+ * Handlers come from the host-mediated DecisionEvents registry.  Raw Cordis
+ * `ctx.on` listeners are intentionally absent from this path.
+ */
+export async function dispatchTuiDecision(ctx, name, payload, normalize) {
+    const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
+    const scope = sessionId === undefined ? undefined : `session:${sessionId}`;
+    const listeners = decisionHandlersOf(ctx, name, scope);
+    const log = (message, error) => {
+        try {
+            if (error === undefined)
+                ctx.logger.warn(message);
+            else
+                ctx.logger.warn(message, error);
+        }
+        catch {
+            // Degraded ctx without a logger: warnings are best-effort.
+        }
+    };
+    const started = Date.now();
+    for (const handler of listeners) {
+        const permission = DECISION_EVENT_PERMISSIONS[name];
+        const principal = { componentId: handler.componentId, activationId: handler.activationId };
+        if (permission !== undefined
+            // Re-check the handler's declared scope at the concrete payload scope.
+            // GrantStore applies parent-scope grants and narrow deny precedence, so
+            // an event-wide grant cannot bypass a revoked session.
+            && !decisionRegistryOf(ctx).grants.allows(principal, permission, scope ?? handler.scope)) {
+            log(`dsh-tui: ${name} handler from Component "${handler.componentId}" skipped after grant revocation`);
+            continue;
+        }
+        const remaining = DECISION_TOTAL_TIMEOUT_MS - (Date.now() - started);
+        if (remaining <= 0) {
+            log(`dsh-tui: ${name} total decision budget exceeded; remaining handlers skipped`);
+            break;
+        }
+        const bounded = await runBounded(() => handler.listener(freezeClone(payload)), Math.min(DECISION_HANDLER_TIMEOUT_MS, remaining));
+        if (bounded.kind === 'timeout') {
+            log(`dsh-tui: ${name} handler from Component "${handler.componentId}" exceeded ${DECISION_HANDLER_TIMEOUT_MS}ms; continuing`);
+            continue;
+        }
+        if (bounded.kind === 'error') {
+            log(`dsh-tui: ${name} listener failed; continuing with the next listener: %o`, bounded.error);
+            continue;
+        }
+        const result = bounded.value;
+        // normalize runs INSIDE the isolation boundary too: a hostile return
+        // value (a Proxy or a throwing getter) must not reject the dispatch —
+        // that would cut the chain before later veto listeners run, and leave
+        // unhandled rejections at the fire-and-forget call sites.
+        let decision;
+        try {
+            decision = normalize(result, what => log(`dsh-tui: ${name} listener returned ${what}; ignored`));
+        }
+        catch (error) {
+            log(`dsh-tui: ${name} listener returned a value that threw during validation; ignored: %o`, error);
+            continue;
+        }
+        if (decision !== undefined)
+            return decision;
+    }
+    return undefined;
+}
+/** Fire a non-veto DecisionEvents point with the same bounded, isolated
+ * semantics.  Notifications deliberately ignore every return value. */
+export async function dispatchTuiNotification(ctx, name, payload) {
+    const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
+    const scope = sessionId === undefined ? undefined : `session:${sessionId}`;
+    const listeners = decisionHandlersOf(ctx, name, scope);
+    const log = (message, error) => {
+        try {
+            if (error === undefined)
+                ctx.logger.warn(message);
+            else
+                ctx.logger.warn(message, error);
+        }
+        catch {
+            // Degraded ctx without a logger: warnings are best-effort.
+        }
+    };
+    const started = Date.now();
+    // Notifications have no return-value or ordering semantics. Start every
+    // listener from the same snapshot so one slow plugin cannot delay another
+    // plugin's session rebind (or make a fire-and-forget dispatch look stuck).
+    await Promise.all(listeners.map(async (handler) => {
+        const permission = DECISION_EVENT_PERMISSIONS[name];
+        const principal = { componentId: handler.componentId, activationId: handler.activationId };
+        if (permission !== undefined
+            && !decisionRegistryOf(ctx).grants.allows(principal, permission, scope ?? handler.scope)) {
+            log(`dsh-tui: ${name} handler from Component "${handler.componentId}" skipped after grant revocation`);
+            return;
+        }
+        const remaining = DECISION_TOTAL_TIMEOUT_MS - (Date.now() - started);
+        if (remaining <= 0) {
+            log(`dsh-tui: ${name} total decision budget exceeded; handler skipped`);
+            return;
+        }
+        const bounded = await runBounded(() => handler.listener(freezeClone(payload)), Math.min(DECISION_HANDLER_TIMEOUT_MS, remaining));
+        if (bounded.kind === 'timeout') {
+            log(`dsh-tui: ${name} handler from Component "${handler.componentId}" exceeded ${DECISION_HANDLER_TIMEOUT_MS}ms; continuing`);
+        }
+        else if (bounded.kind === 'error') {
+            log(`dsh-tui: ${name} listener failed; continuing with the other listeners: %o`, bounded.error);
+        }
+    }));
+}
+/** Shared normalizer for the veto-only decisions (session-switch, compact):
+ *  `{ cancel: true, reason? }` or no opinion; everything else is ignored.
+ *  The reason is toast-bound plugin text — sanitized (a veto must not
+ *  smuggle control sequences onto the screen). */
+export function normalizeCancelDecision(result, warn) {
+    if (result === undefined || result === null || result === false)
+        return undefined;
+    if (typeof result === 'object' && result.cancel === true) {
+        const reason = cleanScalarText(result.reason, NOTICE_CELLS);
+        return { cancel: true, ...(reason === '' ? {} : { reason }) };
+    }
+    warn('an unrecognized decision shape');
+    return undefined;
+}