@things-factory/ai-assistant 10.1.79 → 10.1.87

package/client/components/assistant-session-manager.ts

@@ -47,11 +47,27 @@ const t = (key: string, defaultValue: string, options: Record<string, unknown> =
 @customElement('ox-assistant-session-manager')
 export class AssistantSessionManager extends LitElement {
   static styles = css`
+    .scope-label { padding: 12px 12px 0; font-size: 14px; font-weight: 600; }
+    .filter-toggle, .reset { margin: 6px 10px; padding: 7px; font: inherit; background: transparent; color: inherit; border: 1px solid var(--md-sys-color-outline-variant); border-radius: 6px; cursor: pointer; }
+    .filter-toggle { align-self: flex-end; }
+    .filters[hidden] { display: none; }
+    .open-row { display: block; flex: 1; min-width: 0; text-align: start; border: 0; background: transparent; color: inherit; font: inherit; padding: 4px; cursor: pointer; }
+    .meta { display: block; margin-top: 5px; font-size: 12px; color: var(--md-sys-color-on-surface-variant); }
+    /* Open and private must part at a glance - an open row is read by everyone in the domain (2026-09-30). */
+    .audience { display: inline-flex; align-items: center; gap: 3px; vertical-align: middle; }
+    .audience md-icon { --md-icon-size: 14px; }
+    .audience.open { padding: 1px 6px 1px 4px; border-radius: 6px; background: var(--md-sys-color-tertiary-container); color: var(--md-sys-color-on-tertiary-container); font-weight: 600; }
+    .row.open-audience { box-shadow: inset 3px 0 0 var(--md-sys-color-tertiary); }
+    .actions summary { cursor: pointer; padding: 8px; font-size: 18px; list-style: none; }
+    .actions[open] .acts { display: flex; flex-direction: column; position: absolute; right: 10px; top: 40px; z-index: 2; min-width: 180px; padding: 6px; background: var(--md-sys-color-surface-container-lowest); border: 1px solid var(--md-sys-color-outline-variant); border-radius: 8px; box-shadow: 0 4px 16px #0002; }
+    .actions button.icon { min-height: 40px; padding: 8px 12px; font: inherit; text-align: start; }
+    .actions button.danger { color: var(--md-sys-color-error, #b42318); }
+    button:focus-visible, summary:focus-visible { outline: 2px solid var(--md-sys-color-primary); outline-offset: 2px; }
     :host {
       display: flex;
       flex-direction: column;
       min-height: 0;
-      font-size: 12.5px;
+      font-size: 14px;
       color: var(--md-sys-color-on-surface);
     }
 
@@ -192,11 +208,6 @@ export class AssistantSessionManager extends LitElement {
       gap: 2px;
     }
 
-    .row:hover .acts,
-    .row:focus-within .acts {
-      display: flex;
-    }
-
     button.icon {
       display: inline-flex;
       padding: 3px;
@@ -300,6 +311,7 @@ export class AssistantSessionManager extends LitElement {
   @property({ type: String }) anchorId = ''
   /** The conversation the dock has open - marked in the list. */
   @property({ type: String }) sessionId = ''
+  @property({ type: String }) scopeLabel = ''
   /** The doors. Replaceable for tests; a host normally leaves it. */
   @property({ attribute: false }) admin: AssistantSessionAdmin = assistantSessionAdmin
   /** The conversation kind (mode) open in the dock - the list's default scope (§2-6). */
@@ -320,6 +332,22 @@ export class AssistantSessionManager extends LitElement {
   @state() private loading = false
   @state() private error = ''
   @state() private renamingId = ''
+  @state() private filtersOpen = false
+
+  private get hasFilters() {
+    return !!this.search.trim() || this.allKinds || this.whose !== 'all' || this.visibility !== 'all' || this.includeHidden || this.unreadOnly
+  }
+
+  private resetFilters() {
+    clearTimeout(this.searchTimer)
+    this.refilter(() => {
+      this.search = ''
+      this.allKinds = false
+      this.whose = 'all'
+      this.visibility = 'all'
+      this.includeHidden = this.unreadOnly = false
+    })
+  }
 
   private generation = 0
   private searchTimer?: ReturnType<typeof setTimeout>
@@ -461,17 +489,19 @@ export class AssistantSessionManager extends LitElement {
     const shown = this.entries.length
 
     return html`
+      <div class="scope-label">${this.scopeLabel}</div>
       <div class="bar">
         <input
           .value=${this.search}
-          placeholder=${t('search', 'Search names and last messages')}
-          aria-label=${t('search', 'Search names and last messages')}
+          placeholder=${t('search', 'Search conversations')}
+          aria-label=${t('search', 'Search conversations')}
           @input=${(e: Event) => this.onSearch((e.target as HTMLInputElement).value)}
-          @keydown=${(e: KeyboardEvent) => e.key === 'Escape' && this.onSearch('')}
+          @keydown=${(e: KeyboardEvent) => { if (e.key === 'Escape' && this.search) { e.stopPropagation(); this.onSearch('') } }}
         />
         <button class="new" @click=${() => this.emit('assistant-session-reset')}>+ ${t('new', 'New conversation')}</button>
       </div>
-      <div class="filters">
+      <button class="filter-toggle" aria-expanded=${this.filtersOpen} @click=${() => (this.filtersOpen = !this.filtersOpen)}>${t('filters', 'Filters')}${this.hasFilters ? ' •' : ''}</button>
+      <div class="filters" ?hidden=${!this.filtersOpen}>
         ${this.kind
           ? html`<select aria-label=${t('filter-kind', 'Which kind')} .value=${this.allKinds ? 'all' : 'this'}
               @change=${(e: Event) => this.refilter(() => (this.allKinds = (e.target as HTMLSelectElement).value === 'all'))}>
@@ -496,10 +526,12 @@ export class AssistantSessionManager extends LitElement {
         <label><input type="checkbox" .checked=${this.includeHidden}
           @change=${(e: Event) => this.refilter(() => (this.includeHidden = (e.target as HTMLInputElement).checked))} />${t('filter-hidden', 'Including hidden')}</label>
       </div>
+      ${this.hasFilters ? html`<button class="reset" @click=${() => this.resetFilters()}>${t('reset-filters', 'Clear search and filters')}</button>` : nothing}
       <div class="list">
         ${this.error ? html`<div class="note" role="alert">${this.error}</div>` : nothing}
-        ${shown === 0 && !this.loading
-          ? html`<div class="empty">${this.search ? t('no-match', 'No conversation matches "{q}".', { q: this.search }) : t('none', 'No conversations yet.')}</div>`
+        ${this.loading ? html`<div class="note" role="status">${t('loading', 'Loading conversations…')}</div>` : nothing}
+        ${shown === 0 && !this.loading && !this.error
+          ? html`<div class="empty" role="status">${this.hasFilters ? t('filtered-empty', 'No conversations match these filters here.') : t('scope-empty', 'No conversations for this subject yet.')}</div>`
           : this.entries.map(entry => this.renderRow(entry))}
         ${shown < this.total
           ? html`<button class="more" @click=${() => this.loadMore()}>${t('load-more', 'Show more ({rest})', { rest: this.total - shown })}</button>`
@@ -528,7 +560,7 @@ export class AssistantSessionManager extends LitElement {
           aria-label=${t('rename', 'Rename')}
           @keydown=${(e: KeyboardEvent) => {
             if (e.key === 'Enter') this.rename(entry, (e.target as HTMLInputElement).value)
-            if (e.key === 'Escape') this.renamingId = ''
+            if (e.key === 'Escape') { e.stopPropagation(); this.renamingId = '' }
           }}
           @blur=${(e: Event) => this.rename(entry, (e.target as HTMLInputElement).value)}
         />
@@ -536,29 +568,28 @@ export class AssistantSessionManager extends LitElement {
     }
 
     return html`<div
-      class="row ${entry.unread ? 'unread' : ''} ${entry.hidden ? 'hidden' : ''} ${entry.id === this.sessionId ? 'current' : ''}"
-      @click=${() => this.emit('assistant-session-select', { sessionId: entry.id, kind: entry.kind })}
+      class="row ${entry.unread ? 'unread' : ''} ${entry.hidden ? 'hidden' : ''} ${entry.id === this.sessionId ? 'current' : ''} ${isPrivate ? '' : 'open-audience'}"
     >
       <span class="dot"></span>
-      <md-icon title=${isPrivate ? t('private', 'Private - only its participants read it') : t('open', 'Public - everyone in this domain reads it')}
-        >${isPrivate ? 'lock' : 'public'}</md-icon
-      >
-      <span class="body">
-        <div class="title" @dblclick=${(e: Event) => { e.stopPropagation(); if (actions.rename) this.renamingId = entry.id }}>${name}</div>
+      <button class="open-row" aria-current=${entry.id === this.sessionId ? 'true' : 'false'} @click=${() => this.emit('assistant-session-select', { sessionId: entry.id, kind: entry.kind })}>
+        <div class="title">${name}</div>
         <div class="prev">${this.allKinds && entry.kind ? html`<span class="kind">${this.kindLabels[entry.kind] || entry.kind}</span> · ` : nothing}${entry.lastMessagePreview || ''}</div>
-      </span>
+        <span class="meta"><span class="audience ${isPrivate ? 'private' : 'open'}"><md-icon aria-hidden="true">${isPrivate ? 'lock' : 'public'}</md-icon>${isPrivate ? t('audience-private', 'Participants only') : t('audience-open', 'Everyone in this domain')}</span>${entry.lastMessageAt && Number.isFinite(Date.parse(entry.lastMessageAt)) ? html` · <time datetime=${entry.lastMessageAt}>${new Intl.DateTimeFormat(i18next.language || 'en', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' }).format(new Date(entry.lastMessageAt))}</time>` : nothing}${entry.mine ? html` · ${t('filter-mine', 'Started by me')}` : nothing}</span>
+      </button>
+      <details class="actions" @keydown=${(e: KeyboardEvent) => { if (e.key === 'Escape') { e.stopPropagation(); const details = e.currentTarget as HTMLDetailsElement; details.open = false; details.querySelector('summary')?.focus() } }}>
+      <summary aria-label=${t('manage', 'Manage conversation')}>⋯</summary>
       <span class="acts" @click=${(e: Event) => e.stopPropagation()}>
         ${actions.rename
           ? html`<button class="icon" title=${t('rename', 'Rename')} aria-label=${t('rename', 'Rename')} @click=${() => (this.renamingId = entry.id)}>
-              <md-icon>edit</md-icon>
+              ${t('rename', 'Rename')}
             </button>`
           : nothing}
         ${actions.setVisibility
           ? isPrivate
             ? html`<button class="icon" title=${t('make-open', 'Make public')} aria-label=${t('make-open', 'Make public')}
-                @click=${() => this.askOpen(entry, name)}><md-icon>public</md-icon></button>`
+                @click=${() => this.askOpen(entry, name)}>${t('make-open', 'Make public')}</button>`
             : html`<button class="icon" title=${t('make-private', 'Make private')} aria-label=${t('make-private', 'Make private')}
-                @click=${() => this.setVisibility(entry, 'private')}><md-icon>lock</md-icon></button>`
+                @click=${() => this.setVisibility(entry, 'private')}>${t('make-private', 'Make private')}</button>`
           : nothing}
         <button
           class="icon"
@@ -566,13 +597,14 @@ export class AssistantSessionManager extends LitElement {
           aria-label=${actions.unhide ? t('unhide', 'Show in my list') : t('hide', 'Hide from my list')}
           @click=${() => this.setHidden(entry, !entry.hidden)}
         >
-          <md-icon>${actions.unhide ? 'visibility' : 'visibility_off'}</md-icon>
+          ${actions.unhide ? t('unhide', 'Show in my list') : t('hide', 'Hide from my list')}
         </button>
         ${actions.remove
           ? html`<button class="icon danger" title=${t('remove', 'Delete')} aria-label=${t('remove', 'Delete')}
-              @click=${() => this.askRemove(entry, name)}><md-icon>delete</md-icon></button>`
+              @click=${() => this.askRemove(entry, name)}>${t('remove', 'Delete')}</button>`
           : nothing}
       </span>
+      </details>
     </div>`
   }
 

package/client/components/assistant-session-toolbar.ts

@@ -14,6 +14,7 @@ export class AssistantSessionToolbar extends LitElement {
   @property({ type: Boolean }) temporary = false
   @property() error = ''
   @property({ type: Boolean }) historyEnabled = false
+  @property({ type: Boolean }) singleConversation = false
   @property({ type: Number }) maxTabs = 5
   /** 좁은 도크의 문맥 헤더 바로 아래에서 쓰는 밀도. 기능은 줄이지 않는다. */
   @property({ type: Boolean, reflect: true }) compact = false
@@ -50,7 +51,8 @@ export class AssistantSessionToolbar extends LitElement {
     const label = i18next.t('ai-assistant.session.history', { defaultValue: 'Conversation history' })
     return html`
       <div class="controls">
-        ${this.temporary ? nothing : html`<div class="tabs" role="tablist" aria-label=${label}>
+        ${this.singleConversation ? html`<button @click=${() => this.emit('assistant-session-history')}>${i18next.t('ai-assistant.session.list', { defaultValue: 'Conversations' })}</button><span class="tabs">${this.sessions.find(session => session.id === this.sessionId)?.name || i18next.t('ai-assistant.session.new', { defaultValue: 'New conversation' })}</span>` : nothing}
+        ${this.temporary || this.singleConversation ? nothing : html`<div class="tabs" role="tablist" aria-label=${label}>
           ${!this.sessionId ? html`<button role="tab" aria-selected="true">${i18next.t('ai-assistant.session.new', { defaultValue: 'New conversation' })}</button>` : nothing}
           ${assistantRecentSessions(this.sessions, this.sessionId, this.historyEnabled ? this.maxTabs : this.sessions.length).map((session, index) => html`<button role="tab" aria-selected=${session.id === this.sessionId ? 'true' : 'false'}
             ?disabled=${this.disabled || this.loading} title=${session.name || `${label} ${index + 1}`}
@@ -60,7 +62,7 @@ export class AssistantSessionToolbar extends LitElement {
           title=${i18next.t('ai-assistant.session.reset-help', { defaultValue: 'Keep previous history and your work, and start a new conversation. Previous messages are excluded from subsequent requests.' })}
           @click=${() => this.emit('assistant-session-reset')}>+ ${i18next.t('ai-assistant.session.new', { defaultValue: 'New conversation' })}</button>
       </div>
-      ${this.historyEnabled ? html`<button class="history" ?disabled=${this.loading || this.disabled}
+      ${this.historyEnabled && !this.singleConversation ? html`<button class="history" ?disabled=${this.loading || this.disabled}
         @click=${() => this.emit('assistant-session-history')}>${i18next.t('ai-assistant.session.all', { defaultValue: 'All History' })}</button>` : nothing}
       ${this.loading ? html`<p role="status">${i18next.t('ai-assistant.session.loading', { defaultValue: 'Loading conversation history…' })}</p>` : nothing}
       ${this.error ? html`<p role="alert">${this.error} <button ?disabled=${this.loading || this.disabled}

package/client/components/chat-echo-dedup.ts

@@ -27,6 +27,8 @@ export interface RemoteMessage {
   content: string
   relatedPatchId?: string
   toolUsagesJson?: any
+  /** The answer's proposals, stored with it - the cards come back after a refresh (ADR-0097 Q-D4 ④). */
+  proposalsJson?: any
   /** 접지 경고(영속) — 답이 언급했으나 근거에 없던 식별자. 나중에 읽는 사람도 같은 주의를 봐야 한다. */
   groundingWarningsJson?: any
   /** 발신자 — 표시용 name + **자기 여부 판정용 email**(내부 관리키 id 는 쓰지 않는다). */
@@ -43,6 +45,7 @@ export function remoteMessageToLine(m: RemoteMessage): DedupLine {
     content: m.content,
     patchId: m.relatedPatchId ?? undefined,
     toolUsages: Array.isArray(m.toolUsagesJson) ? m.toolUsagesJson : undefined,
+    proposals: Array.isArray(m.proposalsJson) && m.proposalsJson.length ? m.proposalsJson : undefined,
     groundingWarnings: Array.isArray(m.groundingWarningsJson) ? m.groundingWarningsJson : undefined,
     /* Files sent with the turn (shared dock §9) - opened through the conversation's own route when drawn. */
     attachments: Array.isArray((m as any).attachmentsJson)
@@ -104,6 +107,7 @@ export function receiveRemoteMessage(
         content: m.content,
         patchId: m.relatedPatchId ?? nextLines[idx].patchId,
         toolUsages: Array.isArray(m.toolUsagesJson) ? m.toolUsagesJson : nextLines[idx].toolUsages,
+        proposals: nextLines[idx].proposals ?? (Array.isArray(m.proposalsJson) && m.proposalsJson.length ? m.proposalsJson : undefined),
         groundingWarnings: Array.isArray(m.groundingWarningsJson)
           ? m.groundingWarningsJson
           : nextLines[idx].groundingWarnings,

package/client/components/proposal-outcome-line.ts

@@ -31,3 +31,39 @@ export function parseProposalOutcomeLine(content: string): ParsedProposalOutcome
     total: matched[5] === undefined ? undefined : Number(matched[5])
   }
 }
+
+const REQUESTED = /^proposal (.+): requested$/
+
+/** The key of a "requested" row (server `formatProposalRequestedLine`), or undefined for any other line. */
+export function parseProposalRequestLine(content: string): string | undefined {
+  return REQUESTED.exec((content ?? '').trim())?.[1]
+}
+
+/**
+ * What a proposal card says, from the conversation's rows (ADR-0097 Q-D4 ④).
+ *
+ *   ready        nobody has taken it - the run button
+ *   applying     this page asked the host and no answer came yet - elapsed time, no button
+ *   unconfirmed  it was requested (here before a refresh, or in another window) and no answer is
+ *                recorded - "check result", which asks the host what happened and never runs it again
+ *   answered     the host's verdict
+ *
+ * Time never turns `applying` into a failure (ADR-0070 A12-a decision ②): all that is known is that
+ * no answer came.
+ */
+export type ProposalCardState =
+  | { state: 'ready' }
+  | { state: 'applying' }
+  | { state: 'unconfirmed' }
+  | { state: 'answered'; outcome: ParsedProposalOutcome }
+
+export function proposalCardState(
+  key: string,
+  seen: { outcomes: ReadonlyMap<string, ParsedProposalOutcome>; requested: ReadonlySet<string>; sentHere: boolean }
+): ProposalCardState {
+  const outcome = seen.outcomes.get(key)
+  if (outcome) return { state: 'answered', outcome }
+  if (seen.sentHere) return { state: 'applying' }
+  if (seen.requested.has(key)) return { state: 'unconfirmed' }
+  return { state: 'ready' }
+}

package/client/components/proposal-request.test.ts

@@ -0,0 +1,52 @@
+/*
+ * ADR-0097 Q-D4 ④ — the chat asks the server before it asks the host, and a card that was requested and
+ * never answered offers "check result", never "run".
+ *
+ * The component itself needs a browser; the order of its steps is read from the source, and the rules
+ * it follows are tested on their own (`proposal-outcome.test.ts`).
+ */
+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+import { remoteMessageToLine } from './chat-echo-dedup'
+
+const chat = readFileSync(join(__dirname, 'assistant-chat.ts'), 'utf8')
+const dock = readFileSync(join(__dirname, 'assistant-dock.ts'), 'utf8')
+
+const body = (source: string, start: string) => {
+  const from = source.indexOf(start)
+  expect(from).toBeGreaterThan(0)
+  return source.slice(from, source.indexOf('\n  }\n', from))
+}
+
+it('★ the host is asked only after the server granted the request', () => {
+  const run = body(chat, 'private async executeProposal(')
+  const asked = run.indexOf('await this.requestProposal(key)')
+  const dispatched = run.indexOf("new CustomEvent('assistant-proposal-execute'")
+  expect(asked).toBeGreaterThan(0)
+  expect(dispatched).toBeGreaterThan(asked)
+  expect(run.slice(asked, dispatched)).toMatch(/if \(!granted\) \{[\s\S]*return\n/)
+})
+
+it('★ a requested card without an answer checks the result — it never runs again', () => {
+  const unconfirmed = chat.slice(chat.indexOf("card.state === 'unconfirmed'"), chat.indexOf(': html`', chat.indexOf("card.state === 'unconfirmed'")))
+  expect(unconfirmed).toMatch(/this\.checkProposal\(p, key\)/)
+  expect(unconfirmed).not.toMatch(/executeProposal/)
+})
+
+it('★ "check result" reports only what the host knows, and runs nothing', () => {
+  const check = body(dock, 'private onProposalCheck = async')
+  expect(check).toMatch(/this\.surface\?\.proposalOutcome/)
+  expect(check).toMatch(/if \(!outcome\?\.verdict\) \{[\s\S]*return/)
+  expect(check).not.toMatch(/runProposal|assistant-proposal-execute/)
+})
+
+it('★ a stored answer brings its cards back after a refresh', () => {
+  const line: any = remoteMessageToLine({ id: 'm1', role: 'assistant', content: 'here', proposalsJson: [{ tool: 'proposeFigureCandidate', key: 'k1' }] })
+  expect(line.proposals).toEqual([{ tool: 'proposeFigureCandidate', key: 'k1' }])
+  expect((remoteMessageToLine({ id: 'm2', role: 'assistant', content: 'plain', proposalsJson: [] }) as any).proposals).toBeUndefined()
+})
+
+it('the chat reads stored proposals from history and from the broadcast', () => {
+  expect(chat.split('proposalsJson').length - 1).toBeGreaterThanOrEqual(2)
+})

package/client/utils/assistant-navigation.test.ts

@@ -0,0 +1,38 @@
+import { surfaceTransition } from './assistant-navigation.js'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+describe('a screen offers context without taking over an active conversation', () => {
+  test.each([false, true])('a different identity resets even when active=%s', active => {
+    for (const sameSubject of [false, true]) {
+      expect(surfaceTransition({ identityChanged: true, sameSubject, active })).toBe('reset')
+    }
+  })
+  test('an empty conversation follows the screen', () => {
+    expect(surfaceTransition({ identityChanged: false, sameSubject: false, active: false })).toBe('follow')
+  })
+  test('an existing conversation, draft or ongoing response offers a switch', () => {
+    expect(surfaceTransition({ identityChanged: false, sameSubject: false, active: true })).toBe('offer')
+  })
+  test('returning to the same subject refreshes without reopening', () => {
+    expect(surfaceTransition({ identityChanged: false, sameSubject: true, active: true })).toBe('refresh')
+  })
+})
+
+describe('navigation wiring', () => {
+  const dock = readFileSync(join(__dirname, '../components/assistant-dock.ts'), 'utf8')
+  test('history hides rather than unmounts the chat and its unsent input', () => {
+    expect(dock).toContain('?hidden=${this.showingHistory}')
+    expect(dock).toContain('ready && !this.loading && !this.failure')
+  })
+  test('identity changes clear a carried ask and reread capability', () => {
+    expect(dock).toContain("if (transition === 'reset')")
+    expect(dock).toContain('this.asking = undefined')
+    expect(dock).toContain("this.capability = 'unknown'")
+  })
+  test('all direct board actions check the current screen, not the retained editor', () => {
+    expect(dock).toContain('if (!this.mayApplyOnScreen()) return')
+    expect(dock.match(/if \(this.mayApplyOnScreen\(\)\)/g)).toHaveLength(2)
+    expect(dock).toContain("errorCode: 'conversation-screen-changed'")
+  })
+})

package/client/utils/assistant-navigation.ts

@@ -0,0 +1,6 @@
+/** Screen changes offer a new subject; identity changes must never carry the old conversation. */
+export function surfaceTransition(input: { identityChanged: boolean; sameSubject: boolean; active: boolean }): 'reset' | 'refresh' | 'offer' | 'follow' {
+  if (input.identityChanged) return 'reset'
+  if (input.sameSubject) return 'refresh'
+  return input.active ? 'offer' : 'follow'
+}

package/client/utils/assistant-session-controller.ts

@@ -11,6 +11,8 @@ export interface AssistantSession {
    * 칸이 서기 전에 난 세션에는 값이 없다. 그때는 지금 대화로 두고, 서버가 다음 턴에 찍는다.
    */
   kind?: string
+  /** Who reads it: 'open' (everyone in the domain) or 'private' (participants). The dock draws an open one apart. */
+  visibility?: string
 }
 export interface AssistantSessionTarget {
   /** Account/domain boundary supplied by the authenticated host. */

package/client/utils/assistant-session-transport.ts

@@ -20,7 +20,7 @@ export const assistantSessionTransport: AssistantSessionTransport = {
        * Every readable conversation of this kind on the anchor, not only mine - the same scope the manager
        * shows by default (design/ai/shared-dock.md §2-6). Without a kind: every kind, as before.
        */
-      query: gql`query($type:String!,$id:String!,$kind:String){chatSessionInbox(anchorType:$type,anchorId:$id,kind:$kind,limit:100){id name kind}}`,
+      query: gql`query($type:String!,$id:String!,$kind:String){chatSessionInbox(anchorType:$type,anchorId:$id,kind:$kind,limit:100){id name kind visibility}}`,
       variables: { type: target.anchorType, id: target.anchorId, kind: target.kind || null }, fetchPolicy: 'no-cache'
     })
     if (result.errors?.length) throw new Error(result.errors[0].message)
@@ -36,7 +36,7 @@ export const assistantSessionTransport: AssistantSessionTransport = {
   },
   async create(target) {
     const result = await client.mutate({
-      mutation: gql`mutation($type:String!,$id:String!){createAISession(anchorType:$type,anchorId:$id){id name kind}}`,
+      mutation: gql`mutation($type:String!,$id:String!){createAISession(anchorType:$type,anchorId:$id){id name kind visibility}}`,
       variables: { type: target.anchorType, id: target.anchorId }
     })
     if (result.errors?.length) throw new Error(result.errors[0].message)

package/client/utils/assistant-surface.ts

@@ -13,6 +13,8 @@
  */
 import { store } from '@operato/shell'
 
+import type { ProposalOutcome } from './assistant-proposals.js'
+
 /** The row a conversation hangs on - its session anchor (ADR-0072 decision 6). */
 export interface AssistantAnchor {
   anchorType: string
@@ -27,6 +29,16 @@ export interface AssistantStuck {
 
 export type AnchorResult = AssistantAnchor | AssistantStuck
 
+/** A route the person can take from a surface when the next useful action lives in the app. */
+export interface AssistantSurfaceNextStep {
+  /** The small, concrete action shown below the dock header. */
+  label(): string
+  /** A route inside the current application. */
+  href: string
+  /** Why this is the useful next action, in the person's words. */
+  description?(): string
+}
+
 export function isAnchor(result: AnchorResult | undefined): result is AssistantAnchor {
   return !!result && 'anchorId' in result && !!result.anchorId
 }
@@ -58,11 +70,20 @@ export interface AssistantSurface {
   label(): string
   detail?(): string
   icon?: string
+  /** An app-owned route that helps the person make this surface useful (for example, create the first Twin). */
+  nextStep?: AssistantSurfaceNextStep
   /** Read at the moment of sending - never cached, so a draft cannot go stale. */
   hostContext?(): Record<string, unknown>
   board?: BoardSurface
   /** The dock opened another conversation for this surface - e.g. the board modeller records its direct edits under it. */
   sessionChanged?(sessionId: string): void
+  /**
+   * What became of a proposal whose outcome never reached the conversation (ADR-0097 Q-D4 ④) - asked by
+   * "check result", never to run it again. Answer from the host's own record, keyed by the proposal's key.
+   * `undefined` when the host cannot tell (not saved, undone, never applied): the card stays "no answer
+   * received" - an unknown result is not a refusal.
+   */
+  proposalOutcome?(proposalKey: string, proposal: any): Promise<ProposalOutcome | undefined> | ProposalOutcome | undefined
 }
 
 type Listener = () => void

package/dist-client/components/assistant-chat.d.ts

@@ -273,6 +273,13 @@ export declare class OxAssistantChat extends LitElement {
     /** 안내를 닫았는가 — 한 번 닫으면 이 세션에서는 다시 띄우지 않는다(잔소리 금지). */
     private foldNoticeDismissed;
     private busy;
+    /** Host navigation may retain a conversation for reading while its subject is off screen. */
+    sendBlocked: string;
+    /** The host may inspect navigation risk without reading or copying the person's input. */
+    get navigationState(): {
+        busy: boolean;
+        draft: boolean;
+    };
     private errorMessage?;
     /** C4 presence/roster — 세션 참여자 목록. lastSeenAt 으로 online 판정. */
     private participants;
@@ -561,6 +568,14 @@ export declare class OxAssistantChat extends LitElement {
     private proposalSentAt;
     private elapsedTimer?;
     private executeProposal;
+    private requestProposal;
+    /**
+     * "Check result" on a card that was requested and never answered: the host is asked what happened
+     * (`AssistantSurface.proposalOutcome`), never to run it again. The dock reports what it learns.
+     */
+    private checkProposal;
+    /** Keys whose run was requested - from the conversation's rows, like the outcomes. */
+    private get proposalRequests();
     /**
      * 호스트가 무엇을 했는지 — 대화에 남은 `system` 행에서 읽는다(ADR-0070 A12-a 결정 ①).
      *