threadroom-pi 0.1.0-beta.0

package/extensions/native/receipt.ts

@@ -0,0 +1,25 @@
+import { readFileSync, statSync } from 'node:fs';
+
+/** Public SDK session-file protocol, not manager internals. Memory-only hosts
+ * have no disk assertion. A persisted host's branch row alone cannot prove a
+ * receipt: SDK can expose it before a failed write. Cache identities only. */
+export function createReceiptJournal() {
+  let cached: { file: string; stamp: string; ids: Set<string> } | undefined;
+  return (manager: { getSessionFile?(): string | undefined }): ReadonlySet<string> | undefined => {
+    const file = manager.getSessionFile?.(); if (!file) return undefined;
+    try {
+      const stat = statSync(file), stamp = `${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+      if (cached?.file === file && cached.stamp === stamp) return cached.ids;
+      const ids = new Set<string>();
+      for (const line of readFileSync(file, 'utf8').split('\n')) {
+        try {
+          const entry = JSON.parse(line);
+          const nativeFeedback = entry.type === 'custom_message';
+          const blockingResult = entry.type === 'message' && entry.message?.role === 'toolResult' && entry.message.toolName === 'ask_user_question';
+          if ((nativeFeedback || blockingResult) && typeof entry.id === 'string') ids.add(entry.id);
+        } catch {} // A torn line is not a receipt.
+      }
+      cached = { file, stamp, ids }; return ids;
+    } catch { cached = undefined; return new Set<string>(); }
+  };
+}

package/extensions/native/ui.ts

@@ -0,0 +1,167 @@
+import { Input, matchesKey, wrapTextWithAnsi, truncateToWidth, visibleWidth, Text } from '@earendil-works/pi-tui';
+import { stripVTControlCharacters } from 'node:util';
+
+// Stored text is data, never terminal instructions (including OSC links and bidi).
+export function plain(value: unknown): string {
+  return stripVTControlCharacters(String(value ?? ''))
+    .replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/gu, ' ');
+}
+function singleLine(value: unknown) { return plain(value).replace(/\n/g, ' '); }
+export function card(text: string) { return new Text(plain(text), 0, 0); }
+export type Feedback = { id: string; text: string; optionIndex?: number };
+
+/** Lives in Pi's normal input area while the agent continues its turn. */
+export class AskPanel {
+  private input!: Input;
+  private question: any;
+  private option = 0;
+  private writing = false;
+  private scroll = 0;
+  private pageSize = 1;
+  private closed = false;
+  private suspended = false;
+  beforeRender?: () => void;
+  onRetire?: () => void;
+  retiredInput?: (data: string) => void;
+  private drafts = new Map<string, { input: Input; writing: boolean; option: number; scroll: number }>();
+  private _focused = false;
+  get focused() { return this._focused; }
+  set focused(value: boolean) { this._focused = value; this.input.focused = value && this.writing; }
+
+  constructor(private items: any[], private tui: any, private theme: any,
+    private done: (value: Feedback | undefined) => void, initialId?: string) {
+    this.show(items.find((item) => item.id === initialId) || items[0]);
+  }
+  suspend(value: boolean) { if (value !== this.suspended) { this.suspended = value; this.tui.requestRender(); } }
+  private submit(value: Feedback) { if (!this.closed) this.done(value); }
+  close(value?: Feedback) { if (!this.closed) { this.closed = true; this.onRetire?.(); this.done(value); } }
+  private show(item: any) {
+    if (this.input) this.input.focused = false;
+    this.question = item;
+    const draft = this.drafts.get(item?.id);
+    this.input = draft?.input ?? new Input({ prompt: '> ', placeholder: 'Your response' });
+    this.input.onSubmit = (text) => {
+      if (this.question && text.trim()) this.submit({ id: this.question.id, text });
+    };
+    this.option = draft?.option ?? 0; this.scroll = draft?.scroll ?? 0;
+    this.writing = draft?.writing ?? !item?.prompt.options?.length;
+    this.focused = this._focused;
+  }
+  update(items: any[]) {
+    this.items = items;
+    for (const id of this.drafts.keys()) if (!items.some((item) => item.id === id)) this.drafts.delete(id);
+    // Another async ask joins the panel without replacing the current answer draft.
+    if (!items.some((item) => item.id === this.question?.id)) this.show(items[0]);
+    if (!items.length) this.close();
+    this.tui.requestRender();
+  }
+  private next(direction = 1) {
+    this.drafts.set(this.question.id, { input: this.input, writing: this.writing, option: this.option, scroll: this.scroll });
+    const index = this.items.findIndex((item) => item.id === this.question.id);
+    this.show(this.items[(index + direction + this.items.length) % this.items.length]);
+  }
+  private write(value = '') {
+    this.writing = true;
+    // Browsing choices is not permission to replace an existing written draft.
+    if (!this.input.getValue()) this.input.setValue(value);
+    this.focused = this._focused;
+  }
+  handleInput(data: string) {
+    if (this.closed) { this.retiredInput?.(data); return; }
+    if (!this.question) return;
+    const options = this.question.prompt.options || [];
+    if (matchesKey(data, 'escape')) { this.close(); return; }
+    if (matchesKey(data, 'shift+tab') && this.items.length > 1) this.next();
+    else if (matchesKey(data, 'pageUp')) this.scroll = Math.max(0, this.scroll - this.pageSize);
+    else if (matchesKey(data, 'pageDown')) this.scroll += this.pageSize;
+    else if (!this.writing && (matchesKey(data, 'left') || matchesKey(data, 'right'))) {
+      const direction = matchesKey(data, 'left') ? -1 : 1;
+      this.next(direction);
+    } else if (!this.writing && (matchesKey(data, 'up') || matchesKey(data, 'down'))) {
+      const direction = matchesKey(data, 'up') ? -1 : 1;
+      this.option = (this.option + direction + options.length + 1) % (options.length + 1);
+      this.scroll = 0;
+    } else if (!this.writing && matchesKey(data, 'enter')) {
+      if (this.option === options.length) this.write();
+      else this.submit({ id: this.question.id, text: singleLine(options[this.option].label), optionIndex: this.option });
+    } else if (matchesKey(data, 'tab') && options.length) {
+      if (this.writing) { this.writing = false; this.focused = this._focused; }
+      else this.write(this.option < options.length ? singleLine(options[this.option].label) : '');
+    } else {
+      // Let Pi Input decode ordinary text, bracketed paste and Kitty printable
+      // keys. Escape-prefixed input is not necessarily a navigation key.
+      this.input.handleInput(data);
+      const value = this.input.getValue(), safe = singleLine(value);
+      if (safe !== value) this.input.setValue(safe);
+      const writing = options.length ? safe.length > 0 : true;
+      if (writing !== this.writing) { this.writing = writing; this.focused = this._focused; }
+    }
+    this.tui.requestRender();
+  }
+  render(width: number): string[] {
+    this.beforeRender?.();
+    width = Math.max(1, width);
+    const line = (text: string) => truncateToWidth(singleLine(text), width);
+    const border = this.theme.fg('accent', '─'.repeat(width));
+    if (!this.question) return [];
+    const { prompt } = this.question;
+    if (this.suspended) return [this.theme.fg('accent', line('Private question · waiting for the current Pi prompt')),
+      ...wrapTextWithAnsi(plain(prompt.question), width).slice(0, 3)];
+    const options = prompt.options || [];
+    const title = `Private question${this.items.length > 1 ? ` ${this.items.findIndex((item) => item.id === this.question.id) + 1}/${this.items.length} · Shift+Tab questions` : ''} · reply here`;
+    const selected = !this.writing && options[this.option];
+    const details = [prompt.header, prompt.question, prompt.context,
+      selected && visibleWidth(singleLine(`› ${this.option + 1}. ${selected.label}`)) > width ? `Selected: ${selected.label}` : '',
+      selected?.description ? `Meaning: ${selected.description}` : '',
+      selected?.preview ? `Preview: ${selected.preview}` : ''].filter(Boolean).join('\n\n');
+    const body = wrapTextWithAnsi(plain(details), width);
+    const input = this.writing ? this.input.render(width) : [];
+    // Budget the complete widget, leaving space for Pi's editor, status/footer
+    // and chat. Every detail remains reachable, even in a short terminal.
+    const budget = Math.max(4, Math.min(20, (this.tui.terminal?.rows || 30) - 12));
+    const hint = this.writing
+      ? 'Enter save reply' + (options.length ? ' · Tab choices' : '') + ' · Esc pause'
+      : '↑/↓ choose · Enter save choice · Tab edit · Or type a reply · Esc pause';
+    const activeOption = this.writing ? options.length : this.option;
+    const choiceLine = (i: number) => this.theme.fg(i === activeOption ? 'accent' : 'text',
+      line(`${i === activeOption ? '›' : ' '} ${i + 1}. ${i === options.length ? 'Type something.' : options[i].label}`));
+    if (budget <= 6) {
+      this.pageSize = 1;
+      this.scroll = Math.min(this.scroll, Math.max(0, body.length - 1));
+      const count = options.length ? Math.min(options.length + 1, Math.max(1, budget - 3 - input.length)) : 0;
+      const start = Math.max(0, Math.min(activeOption - Math.floor(count / 2), options.length + 1 - count));
+      return [this.theme.fg('accent', line(title)), body[this.scroll],
+        ...Array.from({ length: count }, (_, i) => choiceLine(start + i)), ...input,
+        this.theme.fg('dim', line('PgUp/PgDn details · ' + hint))].slice(0, budget);
+    }
+    const room = budget - 4 - input.length;
+    const count = options.length ? Math.min(6, options.length + 1, Math.max(1, Math.floor(room / 2))) : 0;
+    const height = Math.max(1, room - count - 1); // reserve the scroll hint too
+    this.pageSize = height;
+    this.scroll = Math.min(this.scroll, Math.max(0, body.length - height));
+    const rows = [border, this.theme.fg('accent', line(title)), ...body.slice(this.scroll, this.scroll + height)];
+    if (body.length > height) rows.push(this.theme.fg('dim', line(`PgUp/PgDn · details ${this.scroll + 1}–${Math.min(body.length, this.scroll + height)}/${body.length}`)));
+    if (count) {
+      const start = Math.max(0, Math.min(activeOption - Math.floor(count / 2), options.length + 1 - count));
+      for (let i = start; i < start + count; i++) rows.push(choiceLine(i));
+    }
+    rows.push(...input, this.theme.fg('dim', line(hint)), border);
+    return rows;
+  }
+  invalidate() { this.input.invalidate(); }
+  dispose() { this.closed = true; this.onRetire?.(); }
+}
+
+/** Escape restores the chat editor, but does not make the pending ask disappear. */
+export function pendingCard(items: any[], tui: any, theme: any) {
+  return {
+    invalidate() {},
+    render(width: number) {
+      width = Math.max(1, width);
+      const rows = [theme.fg('accent', truncateToWidth(`Private questions paused · ${items.length} pending · /asks to reply`, width))];
+      const budget = Math.max(2, Math.min(6, Math.floor((tui.terminal?.rows || 30) / 4)));
+      for (const item of items) rows.push(...wrapTextWithAnsi(plain(item.prompt.question), width));
+      return rows.slice(0, budget);
+    },
+  };
+}

package/extensions/presentation/renderers.ts

@@ -0,0 +1,185 @@
+import { Text, hyperlink, getCapabilities } from '@earendil-works/pi-tui';
+import type { Theme } from '@earendil-works/pi-coding-agent';
+
+// Saved discussions are text, not terminal instructions or Markdown. Keep the
+// original records in the tool/message payload; only this view is abbreviated.
+function literal(value: unknown, multiline = false): string {
+  const text = typeof value === 'string' ? value : value === undefined ? '' : JSON.stringify(value);
+  return (text || '').replace(/[\u0000-\u001f\u007f-\u009f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/g, (char) => {
+    if (char === '\n') return multiline ? '\n' : ' ';
+    if (char === '\t') return '    ';
+    return `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`;
+  });
+}
+function preview(value: unknown, expanded: boolean, multiline = false): string {
+  const text = literal(value, multiline);
+  const limit = expanded ? 4000 : 240;
+  return text.length > limit ? `${text.slice(0, limit)}… [more at the discussion URL]` : text;
+}
+function link(value: unknown): string {
+  if (typeof value !== 'string' || /[\s\u0000-\u001f\u007f-\u009f]/u.test(value)) return '';
+  try {
+    const url = new URL(value);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) return '';
+    // Only our validated HTTP(S) address becomes a terminal hyperlink. Saved
+    // labels and body text never supply escape sequences or hidden targets.
+    return getCapabilities().hyperlinks ? hyperlink(url.href, url.href) : url.href;
+  } catch { return ''; }
+}
+function block(theme: Theme, heading: string, lines: string[], pad = 0) {
+  return new Text([theme.fg('toolTitle', theme.bold(heading)), ...lines.filter(Boolean)].join('\n'), pad, 0);
+}
+function author(node: any, expanded: boolean) {
+  if (!node?.author) return '';
+  // A name, role, session ID, or arbitrary label is provenance, not approval.
+  const label = typeof node.author === 'object' ? node.author.name ?? node.author.id ?? node.author : node.author;
+  return `Author label: ${preview(expanded ? node.author : label, expanded)} (caller-provided; not authenticated approval)`;
+}
+function record(node: any, expanded: boolean, url?: unknown): string[] {
+  if (!node) return [];
+  return [
+    preview(node.title || 'Untitled discussion', expanded),
+    link(url || node.url),
+    expanded ? `Node: ${literal(node.id)}${node.status ? ` · Status: ${literal(node.status)}` : ''}` : node.status ? `Status: ${literal(node.status)}` : '',
+    node.body ? preview(node.body, expanded, expanded) : '',
+    node.presentation ? `Presentation: ${literal(node.presentation.kind)}${expanded && node.presentation.revision ? ` · Revision: ${literal(node.presentation.revision)}` : ''} (open the discussion)` : '',
+    node.presentation?.fallback ? preview(node.presentation.fallback, expanded, expanded) : '',
+    expanded ? author(node, true) : '',
+  ];
+}
+function response(node: any, expanded: boolean): string[] {
+  if (!node) return [];
+  return [
+    `Reply intent: ${literal(node.response?.kind || 'contribution')}`,
+    node.body ? preview(node.body, expanded, expanded) : preview(node.title, expanded),
+    node.response?.selections !== undefined ? `Selections: ${preview(node.response.selections, expanded)}` : '',
+    author(node, expanded),
+    link(node.url),
+    expanded ? `Reply node: ${literal(node.id)}` : '',
+    expanded && node.response?.targetId ? `In reply to: ${literal(node.response.targetId)}` : '',
+    expanded && node.response?.presentationRevision ? `Responded to revision: ${literal(node.response.presentationRevision)}` : '',
+    node.presentation ? `Reply presentation: ${literal(node.presentation.kind)} (open the reply)` : '',
+    node.presentation?.fallback ? preview(node.presentation.fallback, expanded, expanded) : '',
+  ];
+}
+const actions: Record<string, string> = {
+  read: 'Read discussion', browse: 'Discussion outline', publish: 'Contribution saved',
+  reply: 'Reply saved', watch: 'Watching discussion', unwatch: 'Stopped watching in this session', wait: 'Wait finished',
+};
+const outcomes: Record<string, string> = {
+  timeout: 'No reply before the wait ended; the discussion remains saved and watched.',
+  cancelled: 'Wait cancelled; shared history is unchanged.',
+  unavailable: 'Could not establish the wait outcome; shared history is unchanged.',
+  answer: 'Saved reply received · intent: answer', clarification: 'Saved reply received · intent: clarification',
+  defer: 'Saved reply received · intent: defer', reject: 'Saved reply received · intent: reject',
+};
+
+export function renderAskCall(args: any, theme: Theme, context?: any) {
+  return call(args, theme, !!context?.expanded, true);
+}
+export function renderDiscussionCall(args: any, theme: Theme, context?: any) {
+  return call(args, theme, !!context?.expanded, false);
+}
+function call(args: any, theme: Theme, expanded: boolean, ask: boolean) {
+  const input = ask ? args : args.input || {};
+  const presentation = input.presentation;
+  const authored = input.html !== undefined || presentation?.html !== undefined || presentation?.kind === 'html-v1';
+  const scope = input.path || input.project || input.parentId;
+  return block(theme, ask ? 'Ask in Threadroom' : `Threadroom · ${literal(args.action || 'discussion')}`, [
+    preview(input.question || input.title || args.id || args.query || '', expanded),
+    scope ? `Within: ${preview(scope, expanded)}` : '',
+    authored ? 'Authored interaction · source stays out of the terminal' : '',
+    (input.fallback || presentation?.fallback) ? preview(input.fallback || presentation.fallback, expanded, expanded) : '',
+    expanded && input.body ? preview(input.body, true, true) : '',
+    args.waitMs !== undefined ? `Wait: up to ${literal(args.waitMs)} ms; ending the wait does not withdraw saved work` : '',
+  ]);
+}
+
+export function renderToolResult(result: any, options: any, theme: Theme, context?: any) {
+  const expanded = !!options.expanded;
+  if (options.isPartial) return block(theme, 'Threadroom', ['Working…']);
+  const value = result.details;
+  if (!value || typeof value !== 'object') {
+    const text = (result.content || []).filter((part: any) => part.type === 'text').map((part: any) => part.text).join('\n');
+    return block(theme, 'Threadroom', [preview(text || 'No result available.', expanded, expanded)]);
+  }
+  const action = context?.args?.action || 'publish';
+  const lines: string[] = [];
+  let heading = actions[action] || 'Threadroom';
+  if (value.error && !value.outcome) {
+    heading = 'Threadroom · not confirmed';
+    lines.push(preview(value.error, expanded, expanded), literal(value.publication),
+      value.retryKey ? `Retry key: ${literal(value.retryKey)}` : '', ...endpointLines(context?.endpoints));
+  } else if (Array.isArray(value.nodes)) {
+    heading = 'Threadroom · discussion outline';
+    const shown = expanded ? value.nodes : value.nodes.slice(0, 5);
+    for (const node of shown) lines.push(...record(node, false), expanded ? `Node: ${literal(node.id)}` : '');
+    const omitted = (value.omitted || 0) + value.nodes.length - shown.length;
+    if (omitted) lines.push(`${omitted} more discussions${expanded ? '; narrow the browse query to see them' : '; expand for more'}.`);
+    if (!value.nodes.length) lines.push('No matching discussions.');
+  } else {
+    if (value.outcome) {
+      heading = 'Threadroom · wait finished';
+      lines.push(outcomes[value.outcome] || `Wait outcome: ${literal(value.outcome)}`);
+      if (value.error) lines.push(preview(value.error, expanded), ...endpointLines(context?.endpoints));
+    }
+    if (value.deduplicated) lines.push('Already saved; this retry did not publish a duplicate.');
+    if (value.node?.response && action === 'reply') {
+      if (value.target) lines.push(`In discussion: ${preview(value.target.title, expanded)}`, link(value.target.url));
+      lines.push(...response(value.node, expanded));
+    } else {
+      lines.push(...record(value.node, expanded, value.url));
+      if (!value.node) lines.push(value.id ? `Node: ${literal(value.id)}` : '', link(value.url));
+      if (value.response) lines.push(...response(value.response, expanded));
+      else if (value.node?.response) lines.push(...response(value.node, expanded));
+      if (expanded && value.ancestors?.length) lines.push(`Within: ${value.ancestors.map((node: any) => literal(node.title)).join(' / ')}`);
+      const otherChildren = value.children?.filter((child: any) => child.id !== value.response?.id) || [];
+      if (otherChildren.length) {
+        const children = expanded ? otherChildren : otherChildren.slice(-2);
+        lines.push('Saved contributions:');
+        for (const child of children) lines.push(...(child.response ? response(child, expanded) : record(child, expanded)));
+        const omitted = (value.omittedChildren || 0) + otherChildren.length - children.length;
+        if (omitted) lines.push(`${omitted} other contributions; open the discussion for full history.`);
+      }
+    }
+    if (value.note) lines.push(preview(value.note, expanded));
+  }
+  if (expanded) {
+    if (value.receivedResponseIds?.length) lines.push(`Receipt IDs: ${literal(value.receivedResponseIds)}`);
+    if (value.retryKey && !value.error) lines.push(`Retry key: ${literal(value.retryKey)}`);
+    if (value.contextSnapshot) lines.push(`Snapshot: ${literal(value.contextSnapshot)}`);
+    lines.push(...participationLines(value.participation));
+  }
+  return block(theme, heading, lines);
+}
+
+export function renderFeedback(message: any, options: any, theme: Theme) {
+  const value = message.details;
+  const expanded = !!options.expanded;
+  if (!value?.response?.node) return block(theme, 'Saved Threadroom feedback', [
+    preview(typeof message.content === 'string' ? message.content : 'Saved feedback; no readable record available.', expanded, expanded),
+  ], options.outputPad ?? 0);
+  const lines = [
+    `Discussion: ${preview(value.target?.node?.title || 'Untitled discussion', expanded)}`,
+    link(value.target?.url || value.target?.node?.url),
+    ...response(value.response.node, expanded),
+  ];
+  if (expanded) lines.push(`Receipt IDs: ${literal(value.receivedResponseIds)}`,
+    `Delivery event: ${literal(value.delivery?.eventId)} · sequence: ${literal(value.delivery?.sequence)}`);
+  return block(theme, 'Saved Threadroom feedback', lines, options.outputPad ?? 0);
+}
+
+function participationLines(state: any): string[] {
+  if (!state) return [];
+  return [`Connection: ${literal(state.connection)}`, `Watching: ${literal(state.watching || [])}`,
+    state.otherWatches ? `${literal(state.otherWatches)} other watches` : '',
+    state.unconfirmedDeliveries ? `${literal(state.unconfirmedDeliveries)} deliveries awaiting transcript receipt` : ''];
+}
+function endpointLines(endpoints: any): string[] {
+  if (!endpoints) return [];
+  // Notifications are plain text too, not an ANSI or Markdown surface.
+  return [`API: ${literal(endpoints.apiUrl)}`, `Website: ${literal(endpoints.uiUrl)}`];
+}
+export function participationNotice(state: any, endpoints?: any): string {
+  return ['Threadroom', ...endpointLines(endpoints), ...participationLines(state)].filter(Boolean).join('\n');
+}

package/extensions/questions/README.md

@@ -0,0 +1,41 @@
+# Private questions in Pi
+
+A question can need an answer now, or leave the AI free to keep working. This owned SDK-based surface keeps both in the same flat input-area tabs while preserving those execution contracts. Async arrivals stay passive. A blocking question selects and focuses the shared surface; while any blocker remains, Chat cannot reclaim input, but async tabs remain available alongside the required questions. Suggestions stay visible during writing, and clearing the reply restores choice selection.
+
+This is a fresh implementation. The existing questionnaire informed the experience, but is neither a dependency nor implementation source. Copied experiments under `.pi/` are historical evidence, not this module.
+
+## Explicit composition
+
+`registerPrivateQuestions(pi)` registers one `ask_user_question` producer once. Blocking is the default; `blocking: false` uses the same authored shape without waiting. It does not install resources or connect to Threadroom. The package MAIN uses this composition; loading it alongside another producer with the same name would be duplicate wiring. Preparing that entry point does not reload or change the resources of a running Pi session.
+
+Ordinary prompts and saved answers remain in the original Pi session/branch. Threadroom's optional shared discussion tools are a separate lane. A nonblocking result includes stable question IDs; passing one back as the sole `{ questionId }` entry in `questions` leases requiredness to the same pending cell instead of creating or publishing another question. The native source still owns saving. Escape releases the wait while preserving the async question and draft.
+
+In the conversation stream, cyan question cards and violet reply cards use authored titles and identity-based references to connect each exchange. Literal role labels remain readable without color. Operational echoes stay compact; expanding reveals full literal text and structured reply details. “Private” describes the Pi-local audience, not encryption, retention or delivery confirmation; warning/error colors describe actual reported failures rather than the asking or answering role.
+
+The public `index.ts` also exposes the model, view, inline host, blocking producer and domain types for independent consumers. The host accepts question groups: blocking callers await their own outcome, while an async source owns saving through its commit callback. Completion of that callback means persistence, not AI consumption. Question/option indices retain authored identity even when labels duplicate or tabs reorder.
+
+## Interaction and ownership
+
+The question pane has a solid border while it owns input focus and a dotted border while an async-only pane is inactive; a required blocker uses a solid warning border and explicit marker. Its header contains question/review tabs. Tab moves forward through required and async tabs and wraps, so a person can answer ambient questions without leaving the blocking surface. Up/Down retain their choice/text behavior.
+
+Normal Pi needs no SDK patch. Async arrivals appear passively above the editor. Shift+Tab or `/asks` explicitly enters an async-only pane, retaining the exact previous input only as a loan origin—not proof that it is Chat. A blocker takes default selection and claims Chat focus even on stock Pi. Until all blockers resolve or cancel, Shift+Tab and collapse are contained in the shared question surface; pausing an async tab returns to a required tab. Successfully answering the last blocker keeps the pane on its prior async tab, or another remaining async tab, and resumes it if needed; Chat does not reappear between those questions. Cancellation or detachment restores the exact input the blocker claimed, while a blocker that began in an already-owned pane falls back to another visible unpaused async tab when available. Losing or replacing an origin never authorizes a guessed successor, but actually reclaiming an authoritative replacement or explicit `/asks` entry establishes a fresh loan. No editor factory, draft setter, class check or text probe discovers ownership.
+
+Chat keeps native Tab completion for an async-only pane. While async questions are open, Shift+Tab is a global pane toggle; known SDK dialog spans suppress it, and public core-editor identity prevents a blocker from stealing an unannounced foreign prompt. On stock hosts, the exact input captured by an established modal loan provides the same protection; only the initial unannounced input boundary is ambiguous, and explicit `/asks` can deliberately rebind a lost loan. `focusToggleKey` configures or disables the async toggle; plain Tab cannot be used. `/asks` also works without the public raw terminal-input hook. Missing return capabilities omit unsupported hints. With no questions, native keys remain unchanged. Ctrl+] is the separate optional async collapse/reentry shortcut; the former Ctrl+Tab routes and Chat/Questions heading are retired.
+
+Optional public `ui.getCoreEditor()` identity distinguishes Chat from unannounced foreign prompts and recognizes the current core editor for a new focus loan. A blocker preserves its exact return until that origin is lost and an authoritative replacement is actually reclaimed. Async-only focus remains explicit. SDK dialog notifications coordinate ordinary prompts but do not identify arbitrary focused components.
+
+Partial blocking submission retains live checks and notes; cancel affects only that group. Notes use Alt+N where supported, not printable `n`. Our native async source does not offer notes because its persisted answer contract is reply text and optional chosen-option identity. A promoted native question keeps those original limits rather than acquiring questionnaire notes, multi-select, or narrower authoring bounds.
+
+Escape pauses an async question without declining it; when a blocker is pending, focus returns to a required tab instead of Chat. `/asks` selects pending questions, while automatic async bind/navigation/recovery reveal remains passive. All new private admission and unsettled result handoffs close at the first switch/fork/tree/compaction boundary. Positive lifecycle events reopen them; stock Pi reports no cancelled/failed switch, fork, or tree event, so that outcome requires `/reload` after the transition command returns and then `/asks`—idle time is never guessed to mean completion. Collapsing an async-only pane returns to the mounted loan origin or authoritative core and preserves drafts. It requires the public terminal-input hook for reopening; hosts without it keep the pane expanded and can still use `/asks` or pause it. Configured SDK external-editor actions edit the original field through a private temporary file, restore the TUI and sanitize the replacement. UI detachment, shutdown and tool abort are not human Cancel.
+
+Draft editor state belongs to a question incarnation, so reordering retains caret/undo/notes while a new request reusing IDs cannot inherit them. If an unannounced overlay outlives blocker completion, the exact modal return stays deferred until the pane regains focus; its first input is handed to that return target rather than an async draft. A retired pane transfers this debt to a newer question owner before handling stale overlay focus. A blocker claims the initial stock input, then recognizes only that retained origin unless explicit entry establishes a fresh loan.
+
+The presentation port separates pending projection from explicit reveal/focus intent. Terminal widgets do not own storage, results or provider consumption. A future attached FlightDeck UI can replace terminal presentation without redefining those authorities; attachment switching is not implemented here.
+
+## Evidence boundary
+
+Saved/pending truth is independent of UI health. A failed projection or reveal does not undo persistence; a queued send is not a receipt. A saved promoted answer is reserved before projection removes its tab, so one answer is not simultaneously returned by the wait and queued as new async feedback. Its answer-bearing handoff—and a fresh blocking group’s completion—must be accepted by the originating activation immediately before the tool result returns; a session boundary in the settle-to-continuation gap detaches that result instead. If the async route already queued or received it, the later wait reports that state without returning a second answer. Blocking-result receipts carry the exact session/question/answer identity and receive the same physical-journal check as feedback receipts. Real sessions, controlled callbacks, synthetic SDK/TUI tests, physical input, provider consumption, post-exit disk receipts and human acceptance are different evidence.
+
+The SDK can mutate its branch before a failed disk write. Private append failures that changed that branch are therefore **storage unconfirmed**, not answers we can deliver. The backend excludes failed entry identities and blocks further private writes/delivery on that manager/session, including after `/reload`. Persisted feedback receipts also require a complete row in the public SDK session file; memory-only hosts make no disk assertion. A refusal before branch mutation remains retryable. This is fail-closed handling, not SDK journal rollback or repair: recover the original journal before continuing, and preserve/copy the retained draft before any process replacement.
+
+Earlier signed checkpoints passed independent source and extracted-package physical checks for normal saving, external editing, priority, partial review, reload and bounded original-session recovery. Those results do not validate this in-progress focus/SDK-identity refinement. Storage uncertainty, draft retention and before-startup transcript rendering were checked separately through the real SDK and actual filesystem failures; normal-path physical runs did not inject disk failures. No SDK journal repair, hard-crash durability, exactly-once AI action, human acceptance or production activation is claimed here.

package/extensions/questions/compose.ts

@@ -0,0 +1,82 @@
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { registerNativeAsks } from '../native/index.ts';
+import type { NativeQuestionPresentation } from '../native/presentation.ts';
+import { createQuestionHost, supportsQuestionHost } from './host.ts';
+import { registerBlockingQuestions } from './tool.ts';
+
+/** Explicit private-question composition. Registers each producer once; does not
+ * install resources, replace another extension, or connect to Threadroom. */
+export function registerPrivateQuestions(pi: ExtensionAPI) {
+  let host: ReturnType<typeof createQuestionHost> | undefined;
+  let owner: { manager: object; sessionId: string } | undefined;
+  let foreign = false;
+  function ensure(ctx: ExtensionContext) {
+    const sessionId = ctx.sessionManager.getSessionId();
+    if (!host || owner?.manager !== ctx.sessionManager || owner.sessionId !== sessionId) {
+      host?.dispose(); host = createQuestionHost(ctx); owner = { manager: ctx.sessionManager, sessionId }; host.suspend(foreign);
+    }
+    return host;
+  }
+  const presentation: NativeQuestionPresentation = {
+    canPresent(context) { return supportsQuestionHost(context); },
+    connect(binding) {
+      type Handle = { detach(): void; answered(): void; require(value: boolean): void };
+      const captured = ensure(binding.context), handles = new Map<string, Handle>(); let live = true;
+      return {
+        replace(questions, state) {
+          if (!live) return;
+          const pending = new Set(questions.map((question) => question.id));
+          const answered = new Set(state?.answeredQuestionIds || []);
+          const required = new Set(state?.requiredQuestionIds || []);
+          for (const [id, handle] of handles) if (!pending.has(id)) {
+            if (answered.has(id)) handle.answered(); else handle.detach();
+            handles.delete(id);
+          }
+          for (const question of questions) {
+            let handle = handles.get(question.id);
+            if (!handle) {
+              handle = captured.enqueue({ id: `native:${question.id}`, mode: 'async', questions: [{ id: question.id, question: question.prompt.question,
+                header: question.prompt.header, context: question.prompt.context, options: question.prompt.options,
+                multiSelect: question.prompt.multiSelect, plainPreview: true, allowNotes: false }],
+                commit(questionId, answer) {
+                  if (!live) throw Object.assign(new Error('Private source detached.'), { code: 'presentation_detached' });
+                  binding.commit({ questionId, text: answer.answer || '', optionIndex: answer.optionIndex, optionIndices: answer.optionIndices });
+                },
+                releaseRequirement(questionId) {
+                  if (!live) return;
+                  binding.cancelWait(questionId);
+                } });
+              handles.set(question.id, handle);
+            }
+            handle.require(required.has(question.id));
+          }
+        },
+        reveal(questionId, options) {
+          if (!live) return false;
+          // Automatic resume preserves an existing blocker; explicit /asks ID can
+          // select another pending question. Arrival itself does not steal drafts.
+          if (!questionId && captured.snapshot().current?.tab.mode === 'blocking') {
+            if (options?.focus) captured.activate();
+            return true;
+          }
+          const id = questionId || handles.keys().next().value;
+          if (id && handles.has(id)) { captured.select(`native:${id}`, id); if (options?.focus) captured.activate(); return true; }
+          return false;
+        },
+        dispose() { if (!live) return; live = false; captured.dispose(); handles.clear(); if (host === captured) { host = undefined; owner = undefined; } },
+      };
+    },
+  };
+  const native = registerNativeAsks(pi, { presentation, waitToolName: 'ask_user_question', registerStandaloneTool: false });
+  registerBlockingQuestions(pi, async (group, ctx, signal) => {
+    if (!supportsQuestionHost(ctx)) throw Object.assign(new Error('This Pi host does not expose inline widgets; no question was presented and no human declined.'), { code: 'unsupported_host' });
+    const accept = native.captureAdmission(ctx);
+    const handle = ensure(ctx).enqueue(group), detach = () => handle.detach();
+    if (signal?.aborted) detach(); else signal?.addEventListener('abort', detach, { once: true });
+    try { return { result: await handle.outcome!, accept }; } finally { signal?.removeEventListener('abort', detach); }
+  }, native.waitForQuestion, native.captureAdmission,
+  (toolCallId, question, ctx, signal) => native.askQuestion(toolCallId, question, signal, ctx));
+  pi.on('ui_prompt_start', () => { foreign = true; host?.suspend(true); });
+  pi.on('ui_prompt_end', () => { foreign = false; host?.suspend(false); });
+  return { snapshot: () => host?.snapshot(), dispose() { host?.dispose(); host = undefined; owner = undefined; } };
+}

package/extensions/questions/external-editor.ts

@@ -0,0 +1,24 @@
+import { mkdtempSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+/** Explicit user action only. The command is trusted SDK/user configuration;
+ * question/paste text is file data, never shell source. Owns file and TUI cleanup. */
+export function editTextOutsidePi(tui: any, command: string, text: string): string {
+  if (!command.trim()) throw new Error('No external editor is configured.');
+  const directory = mkdtempSync(join(tmpdir(), 'pi-question-edit-')), file = join(directory, 'reply.txt');
+  let stopped = false;
+  try {
+    writeFileSync(file, text, { mode: 0o600 });
+    tui.stop(); stopped = true;
+    const quote = (value: string) => `'${value.replace(/'/gu, `'\\''`)}'`;
+    const child = spawnSync('/bin/sh', ['-c', `${command} ${quote(file)}`], { stdio: 'inherit' });
+    if (child.error) throw child.error;
+    if (child.status !== 0) throw new Error(`External editor exited ${child.signal || child.status}. Original draft retained.`);
+    return readFileSync(file, 'utf8');
+  } finally {
+    try { rmSync(directory, { recursive: true, force: true }); }
+    finally { if (stopped) { tui.start(); tui.requestRender(true); } }
+  }
+}