refactor(packages): dissolve ui/ and rename sdk/ to scaffold/

git mv per the regrouping RFC: the five human-collaboration seams and
tui join packages/interaction/, app-boot becomes packages/boot/, and
jsonrpc joins the renamed scaffold/ (formerly sdk/) as its server half
beside client/protocol/create-sdk/helper/scripts/telemetry, whose
folders drop the legacy sdk- prefix. Three new group README triplets
replace the ui/ and sdk/ ones; tsconfig references/paths/globs,
knip keys, vitest globs, gate scripts, catalogs, docs, and the
lockfile follow. Adds the four settled FIXME rename markers
(dsh-sdk-server, dsh-sdk-telemetry, dsh-sdk-helper, dsh-sdk-scripts).

The scaffold folders diverge from their npm names until those renames
land, so tsconfig.base.json maps the three affected names explicitly
beside the group wildcard. Also repairs two pre-existing stale-path
classes the strengthened sweep surfaced: docs/web-styling.md's retired
web-ui host package and type-model spec fixture-literal joins.

app-boot's three Loader-composition specs time out at the default 5s
under full-suite parallel load on this filesystem (pre-existing;
pass isolated with --testTimeout=30000); interaction/scaffold/boot
suites otherwise green (687 passed).

packages/interaction/user-approval/src/index.ts

@@ -0,0 +1,348 @@
+/**
+ * Approval request, cancellation, audit, and per-session policy seam. Missing
+ * answerers fail closed; grants apply only to the requested action.
+ * @module @deepseek-ai/dsh-user-approval
+ */
+
+import { randomUUID } from 'node:crypto'
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { createUserMessage, type CallId } from '@deepseek-ai/dsh-llm'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import type { Scoped } from '@deepseek-ai/dsh-scope'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+
+declare module 'cordis' {
+  interface Context {
+    approval: ApprovalService
+  }
+
+  interface Events {
+    /**
+     * Ask composed answerers for one decision. Return an outcome to claim the
+     * request or call `next()`; failure yields the fail-closed default.
+     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+     * @param req - the pending decision (agent, tool identity, reason, signal).
+     * @mode waterfall
+     */
+    'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
+  }
+}
+
+declare module '@deepseek-ai/dsh-session' {
+  interface SessionEventMap {
+    /**
+     * An approval question was put to the answerer chain — log-only audit
+     * (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs
+     * it with the `approval/decided` that always follows; `toolName` is the
+     * tool the question is about, `callId` the exact tool call when the asker
+     * had one, `reason` the asker's human-readable explanation (e.g. a hook's
+     * permission-decision reason).
+     */
+    'approval/asked': {
+      id: ApprovalRequestId
+      toolName: string
+      callId?: CallId
+      reason?: string
+    }
+    /**
+     * The outcome of a prior `approval/asked` (same `id`) — log-only audit.
+     * Exactly one per ask, appended when the outcome is known: a decision, a
+     * cancellation, or the fail-closed `'unavailable'`.
+     */
+    'approval/decided': {
+      id: ApprovalRequestId
+      outcome: ApprovalOutcome
+    }
+    /**
+     * The session's approval policy was switched — log-only, durable,
+     * replayable, never in the model transcript (the model learns the policy
+     * from the runtime-context snapshot and live switch notices). The LAST
+     * such event is the session's override ({@link effectiveApprovalPolicy}).
+     * `source: 'delegation'` marks an override seeded into a child; an absent
+     * source is a runtime switch.
+     */
+    'approval/policy': {
+      policy: ApprovalPolicy
+      /** Marks an override seeded into a child at delegation. */
+      source?: 'delegation'
+    }
+  }
+}
+
+import { ApprovalRequestId } from './types.ts'
+import type { ApprovalOutcome } from './types.ts'
+
+export { ApprovalRequestId } from './types.ts'
+export type { ApprovalOutcome } from './types.ts'
+
+/** Every {@link ApprovalOutcome}, for runtime normalization of answerer returns. */
+const OUTCOMES: readonly ApprovalOutcome[] = ['allowed-once', 'rejected', 'cancelled', 'unavailable']
+
+/**
+ * A session's approval policy — what happens to an {@link ApprovalService}
+ * ask BEFORE any interactive answerer sees it:
+ *
+ * - `'ask'` (the default) — delegate to the composed answerers; with none
+ *   composed the chain falls through to the fail-closed `'unavailable'`
+ *   (exactly today's behavior).
+ * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
+ *   deterministically. The strict headless stance (CI, unattended runs) and
+ *   the policy whose outcome is knowable without asking.
+ */
+export type ApprovalPolicy = 'ask' | 'never'
+
+/** Every {@link ApprovalPolicy}, for option advertisement and runtime validation of untrusted policy strings. */
+export const APPROVAL_POLICIES: readonly ApprovalPolicy[] = ['ask', 'never']
+
+/** Model-facing statement for the deterministic `'never'` policy. */
+const NEVER_SENTENCE = 'Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).'
+/** Model-facing statement for an interactive policy that may still fail closed. */
+const ASK_SENTENCE = 'Approval policy: ask. Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.'
+
+/**
+ * The session's approval-policy override: the last `approval/policy` event in
+ * the log, or undefined when the session never switched (callers apply the
+ * plugin's configured default). The pure fold — resume needs no catch-up
+ * machinery because replaying the log IS the state.
+ * @param events - session events in log order (other event types are skipped).
+ * @returns the policy of the last switch event, or undefined without one.
+ */
+export function effectiveApprovalPolicy(events: readonly SessionEvent[]): ApprovalPolicy | undefined {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const event = events[index] as SessionEvent
+    if (event.type === 'approval/policy') return event.data.policy
+  }
+  return undefined
+}
+
+/**
+ * Whether the log currently sits inside an open turn (a `turn/start` not yet
+ * closed by a `turn/end`) — the {@link ApprovalService.request} precondition.
+ * The audit pair must be turn-enclosed: the turn is the durable log's
+ * commit/replay boundary, so a bare event appended between turns is
+ * indistinguishable from a crash tail and silently dropped on reload.
+ */
+function hasOpenTurn(events: readonly SessionEvent[]): boolean {
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const type = (events[index] as SessionEvent).type
+    if (type === 'turn/start') return true
+    if (type === 'turn/end') return false
+  }
+  return false
+}
+
+/**
+ * Append the sole durable representation of a session policy override. Invalid
+ * values throw before the log changes; consumers fold the new value on each read.
+ * @param session - the session the override belongs to.
+ * @param policy - the policy in effect until the next switch.
+ */
+export function setApprovalPolicy(session: Session, policy: ApprovalPolicy): void {
+  if (!APPROVAL_POLICIES.includes(policy)) {
+    throw new TypeError('approval policy must be one of "ask" or "never"')
+  }
+  session.append('approval/policy', { policy })
+}
+
+/**
+ * Readonly same-process permission question. `callId` links to an already
+ * presented tool call, so arguments are not duplicated here.
+ */
+export interface ApprovalRequest {
+  /**
+   * The agent on whose behalf the question is asked. Routes the question (a
+   * UI answerer only answers for agents it owns) and receives the audit
+   * events on its session log.
+   */
+  readonly agent: Agent
+  /** The tool the question is about (presentation and audit). */
+  readonly toolName: string
+  /**
+   * The exact tool call being decided, when the asker has one — lets a UI
+   * attach the prompt to the tool call it already streamed.
+   */
+  readonly callId?: CallId
+  /** The asker's human-readable explanation of WHY it is asking. */
+  readonly reason?: string
+  /**
+   * Aborting withdraws the question: the request settles `'cancelled'`
+   * immediately and a late answer from a still-pending answerer is discarded.
+   */
+  readonly signal?: AbortSignal
+}
+
+/** Plugin config. All optional — `static Config` supplies the defaults. */
+export interface Config {
+  /**
+   * The deployment's default {@link ApprovalPolicy} for sessions without an
+   * `approval/policy` override — `'ask'` delegates to the composed answerers
+   * (fail-closed with none); `'never'` auto-rejects every ask without
+   * prompting (the deterministic CI/unattended stance).
+   */
+  readonly policy?: ApprovalPolicy
+}
+
+/**
+ * Approval service that applies session policy before answerers and logs every
+ * ask/outcome pair to the requesting session. It exposes deterministic policy
+ * changes to the model through the runtime-context snapshot and switch notices.
+ */
+export class ApprovalService extends Service {
+  static Config: z<Config> = z.object({
+    policy: z.union(['ask', 'never'] as const).default('ask'),
+  })
+
+  constructor(ctx: Context, public config: Config) {
+    super(ctx, 'approval')
+
+    const effective = (agent: Agent): ApprovalPolicy => this.effectivePolicy(agent.session)
+
+    // The complete current value travels after retained history, so switching
+    // policy does not rewrite the stable system-prompt cache prefix.
+    ctx.inject(['systemPrompt'], (scope: Context) => {
+      scope.systemPrompt.context({
+        name: 'approval:policy',
+        order: 115,
+        text: (context) => {
+          const agent = context.agent
+          // A bare assemble() (tests, diagnostics) has no session to state.
+          if (agent === undefined) return ''
+          const policy = effective(agent)
+          return policy === 'never' ? NEVER_SENTENCE : ASK_SENTENCE
+        },
+      })
+    })
+  }
+
+  /**
+   * Switch one live agent's policy and queue the transition for its next model
+   * step. Session initialization uses {@link setApprovalPolicy} directly
+   * because there is no previously visible policy to change.
+   * @param agent - the live agent whose policy is changing.
+   * @param policy - the new effective policy.
+   */
+  setPolicy(agent: Agent, policy: ApprovalPolicy): void {
+    const previous = this.effectivePolicy(agent.session)
+    if (previous === policy) return
+    setApprovalPolicy(agent.session, policy)
+    agent.inject(createUserMessage({
+      content: [{
+        type: 'text',
+        text: `The approval policy changed from "${previous}" to "${policy}" (changed by the user).`,
+      }],
+      source: { kind: 'plugin', plugin: 'user-approval' },
+    }))
+  }
+
+  /**
+   * Ask the composed answerers to decide one readonly same-process request.
+   * The service borrows the request, agent, session, and live signal directly.
+   * The request requires an open turn because the audit pair must be enclosed
+   * by the durable log's commit/replay boundary; an idle ask rejects before
+   * appending anything. The answerer phase always produces an outcome: an
+   * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+   * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+   * normalized to `'unavailable'`. A failure that prevents either audit append
+   * from committing still rejects because returning an unlogged decision would
+   * violate the pair. Session contains post-commit observer failures, so an
+   * authoritative append cannot reject the request or suppress its matching
+   * audit event.
+   * @param req - the pending decision (agent, tool identity, reason, signal).
+   * @returns the closed outcome; `'allowed-once'` is the only grant.
+   * @throws when no turn is open or either audit event fails before the session
+   *   append commit point.
+   */
+  async request(req: ApprovalRequest): Promise<ApprovalOutcome> {
+    const session = req.agent.session
+    if (!hasOpenTurn(session.events)) {
+      throw new Error(
+        'approval.request() outside an open turn: the approval/asked + approval/decided audit pair '
+        + 'must be turn-enclosed (a bare event between turns is crash-tail garbage on reload). '
+        + 'Ask from inside the turn that needs the decision.',
+      )
+    }
+    const id = ApprovalRequestId(randomUUID())
+    session.append('approval/asked', {
+      id,
+      toolName: req.toolName,
+      ...req.callId !== undefined ? { callId: req.callId } : {},
+      ...req.reason !== undefined ? { reason: req.reason } : {},
+    })
+    const outcome = await this.decide(req, session)
+    session.append('approval/decided', { id, outcome })
+    return outcome
+  }
+
+  /**
+   * The session's effective policy: its own `approval/policy` fold, else the
+   * configured default (the schema already defaulted an omitted policy to
+   * `'ask'`; the `??` only narrows the optional-input TYPE).
+   * @param session - the exact accepted session whose policy applies.
+   * @returns the policy every ask for this session resolves under right now.
+   */
+  private effectivePolicy(session: Session): ApprovalPolicy {
+    return this.overrideOf(session) ?? this.config.policy ?? 'ask'
+  }
+
+  /**
+   * Read the session override without applying the configured default.
+   * @param session - session whose log supplies the override.
+   * @returns the last logged policy, or `undefined` without one.
+   */
+  overrideOf(session: Session): ApprovalPolicy | undefined {
+    return effectiveApprovalPolicy(session.events)
+  }
+
+  /**
+   * Dispatch the waterfall, contained and raced against the request signal.
+   * @param req - the borrowed public request.
+   * @param session - the request agent's session used for policy lookup.
+   * @returns the normalized closed outcome.
+   */
+  private async decide(req: ApprovalRequest, session: Session): Promise<ApprovalOutcome> {
+    const signal = req.signal
+    if (signal?.aborted) return 'cancelled'
+    // The 'never' policy is decided HERE, before any dispatch: a listener
+    // registered with `prepend: true` after this service mounts would sit
+    // ahead of any gate LISTENER, so a listener-shaped gate cannot keep the
+    // documented promise that 'never' rejects deterministically regardless
+    // of registration order — only the service's own request path can.
+    if (this.effectivePolicy(session) === 'never') return 'rejected'
+    // Enter the promise chain BEFORE dispatching: a listener that throws
+    // SYNCHRONOUSLY (before its first await) must land in the same rejection
+    // path as an async one — `Promise.resolve(call())` would let it escape
+    // the containment into the caller.
+    const answer: Promise<ApprovalOutcome> = Promise.resolve().then(
+      () => this.ctx.waterfall(
+        scopeTarget(this, req.agent), 'approval/request', req,
+        () => Promise.resolve<ApprovalOutcome>('unavailable'),
+      ),
+    ).then(
+      // Normalize a rogue (non-vocabulary) answerer return to the fail-closed
+      // outcome instead of leaking it into callers' closed-union switches.
+      outcome => OUTCOMES.includes(outcome) ? outcome : 'unavailable',
+      // A throwing answerer must fail the QUESTION closed, not the caller's
+      // tool call open — the seam contains its callbacks.
+      () => 'unavailable',
+    )
+    if (signal === undefined) return answer
+    return await new Promise<ApprovalOutcome>((resolve) => {
+      const onAbort = () => {
+        signal.removeEventListener('abort', onAbort)
+        resolve('cancelled')
+      }
+      signal.addEventListener('abort', onAbort, { once: true })
+      void answer.then((outcome) => {
+        signal.removeEventListener('abort', onAbort)
+        // After an abort won the race this resolve is a settled-promise no-op:
+        // the late answer is discarded by construction.
+        resolve(outcome)
+      })
+    })
+  }
+}
+
+export default ApprovalService

packages/interaction/user-approval/src/invariant.ts

@@ -0,0 +1,111 @@
+/** Package-owned approval audit-stream invariants. @module @deepseek-ai/dsh-user-approval/invariant */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { ApprovalRequestId } from './index.ts'
+import { APPROVAL_POLICIES } from './index.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-user-approval'
+const APPROVAL_OUTCOMES = ['allowed-once', 'rejected', 'cancelled', 'unavailable'] as const
+
+/** Cordis companion plugin name. */
+export const name = 'user-approval-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+type ApprovalTransition =
+  | { kind: 'asked'; id: ApprovalRequestId }
+  | { kind: 'decided'; id: ApprovalRequestId }
+
+interface ApprovalTrace {
+  openTurn: number | null
+  pending: Set<ApprovalRequestId>
+}
+
+/** Validate one approval event against committed unmatched questions. */
+function validateApprovalEvent(
+  trace: ApprovalTrace,
+  event: SessionEvent,
+  fail: InvariantFailure,
+): ApprovalTransition | undefined {
+  if (event.type === 'approval/asked') {
+    if (trace.openTurn === null) fail('approval/asked appended outside any open turn')
+    if (event.data.toolName.length === 0) fail('approval/asked toolName must be non-empty')
+    if (trace.pending.has(event.data.id)) fail(`approval/asked repeated open id ${JSON.stringify(event.data.id)}`)
+    return { kind: 'asked', id: event.data.id }
+  }
+  if (event.type === 'approval/decided') {
+    if (trace.openTurn === null) fail('approval/decided appended outside any open turn')
+    if (!trace.pending.has(event.data.id)) fail(`approval/decided has no matching approval/asked for id ${JSON.stringify(event.data.id)}`)
+    if (!APPROVAL_OUTCOMES.includes(event.data.outcome)) {
+      fail(`approval/decided carries unknown outcome ${JSON.stringify(event.data.outcome)}`)
+    }
+    return { kind: 'decided', id: event.data.id }
+  }
+  if (event.type === 'approval/policy' && !APPROVAL_POLICIES.includes(event.data.policy)) {
+    fail(`approval/policy carries unknown policy ${JSON.stringify(event.data.policy)}`)
+  }
+  return undefined
+}
+
+/** Apply one accepted approval-pair transition. */
+function applyApprovalTransition(pending: Set<ApprovalRequestId>, transition: ApprovalTransition): void {
+  if (transition.kind === 'asked') pending.add(transition.id)
+  else pending.delete(transition.id)
+}
+
+/** Install audit pairing and closed-vocabulary checks. */
+// Event owners keep precommit staging local so their vocabularies never move into a central helper.
+/* jscpd:ignore-start */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+  const traces = new WeakMap<Session, ApprovalTrace>()
+  const staged = new WeakMap<SessionEvent, { session: Session; transition: ApprovalTransition }>()
+  const seed = (session: Session): ApprovalTrace => {
+    const trace: ApprovalTrace = { openTurn: null, pending: new Set() }
+    traces.set(session, trace)
+    for (const event of session.events) {
+      if (event.type === 'turn/start') trace.openTurn = event.data.turn
+      else if (event.type === 'turn/end') trace.openTurn = null
+      const transition = validateApprovalEvent(trace, event, fail)
+      if (transition !== undefined) applyApprovalTransition(trace.pending, transition)
+    }
+    return trace
+  }
+  const traceFor = (session: Session): ApprovalTrace => traces.get(session) ?? seed(session)
+
+  for (const session of ctx.sessions.list()) seed(session)
+  ctx.on('session/created', (session) => { seed(session) }, { global: true })
+  ctx.on('session/event', (session, event) => {
+    const trace = traceFor(session)
+    if (event.type === 'turn/start') {
+      trace.openTurn = event.data.turn
+      return
+    }
+    if (event.type === 'turn/end') {
+      trace.openTurn = null
+      return
+    }
+    if (event.type !== 'approval/asked' && event.type !== 'approval/decided') return
+    const candidate = staged.get(event)
+    /* v8 ignore next -- internal/dispatch stages every package-owned pair event */
+    if (candidate === undefined || candidate.session !== session) return fail('approval audit event published without pre-commit validation')
+    staged.delete(event)
+    applyApprovalTransition(trace.pending, candidate.transition)
+  }, { global: true })
+  ctx.on('internal/dispatch', (_mode, eventName, args) => {
+    if (eventName !== 'session/event') return
+    const [session, event] = args as [Session, SessionEvent]
+    const transition = validateApprovalEvent(traceFor(session), event, fail)
+    if (transition !== undefined) staged.set(event, { session, transition })
+  }, { global: true })
+}, { inject: ['sessions'] })
+/* jscpd:ignore-end */
+
+/**
+ * Register the approval invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/interaction/user-approval/src/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Wire-safe approval identifiers and outcome vocabulary, free of
+ * cordis/service imports so browser type chains (apiproxy api → client) can
+ * consume them without loading this package's Context augmentation.
+ * @module @deepseek-ai/dsh-user-approval/types
+ */
+
+import type { Branded } from '@deepseek-ai/dsh-brand'
+
+/**
+ * Pairs one `approval/asked` audit event with its `approval/decided`.
+ * Service-issued (one fresh id per {@link ApprovalService.request} call).
+ */
+export type ApprovalRequestId = Branded<'ApprovalRequestId'>
+
+/**
+ * Brand a string as an {@link ApprovalRequestId}.
+ * @param id - the raw id string to brand.
+ * @returns the same string carrying the brand.
+ */
+export function ApprovalRequestId(id: string): ApprovalRequestId {
+  return id as ApprovalRequestId
+}
+
+/**
+ * Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn
+ * request, or unavailable answerer. Callers fail closed on `unavailable`.
+ */
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'