threadroom-pi 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Meyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# Threadroom for Pi
+
+Ask private questions without making the AI guess or stop useful independent work. `threadroom-pi` owns one `ask_user_question` tool with a shared input-area surface: questions block by default, while `blocking: false` leaves them open as the AI continues. The optional shared Threadroom lane is experimental, off by default, and never starts or contacts its bundled local service during private questions.
+
+This is beta software. The private-question experience is usable and tested on Pi 0.86.x; shared discussions, remote deployment, authentication, and broader host compatibility are still evolving. Pi extensions execute with the same system access as Pi, so review packages before installing them.
+
+## Install
+
+Requires Node 24 or newer. The beta release is intentionally outside npm's `latest` channel:
+
+```sh
+pi install npm:threadroom-pi@beta
+```
+
+Reload or restart Pi after changing packages. `threadroom-pi` must be the only active producer of `ask_user_question`; disable another questionnaire extension before enabling it. To try the current checkout without installation:
+
+```sh
+pi --no-extensions -e ./packages/pi-extension/extensions/index.ts
+```
+
+## Private questions
+
+Blocking questions take priority within the question pane and await only their own group. Nonblocking questions appear automatically while the AI continues working—not in a hidden inbox. Async-only arrivals leave the current input focused: use Shift+Tab or `/asks` to enter the pane. A blocker selects and focuses the same shared surface; Chat remains unavailable until every blocker is answered or cancelled, while pending async tabs remain usable beside it. Answering the last blocker keeps a remaining nonblocking question focused instead of automatically returning to Chat; cancellation still restores the blocker’s input loan. Same-priority arrivals retain the current draft; suggestions stay visible during writing, and clearing the reply restores choice selection.
+
+`ask_user_question({ questions, blocking: false })` returns stable IDs and `waitWith` references. If later work depends on one of those unanswered questions, passing `questions: [{ questionId }]` to the same tool temporarily makes its existing tab required and waits for its native saved answer. It neither republishes nor recreates the question, and its original draft, choices, limits, branch identity, and persistence owner remain intact. Escape releases only the wait and returns the still-pending question to async. If its answer was already queued or received through async feedback, the wait reports that state rather than returning the answer a second time.
+
+Use the SDK select keys to choose/confirm, type or paste a free reply, and Tab to cycle forward through question and group-review tabs. In an async-only pane, Shift+Tab selects/unselects questions while preserving both drafts; a solid border means the pane owns focus, and a dotted border means it does not. A blocker has an explicit required marker and warning border; Shift+Tab and collapse cannot leave it. Chat keeps native Tab completion when no blocker is pending. Blocking review supports partial submission, live checks, custom text and Alt+N notes; cancel affects only that group. Native async does not offer notes because its stored answer contract cannot retain them. Async previews are literal text; blocking previews support Markdown.
+
+Escape pauses async questions without declining them or discarding their drafts; with a blocker pending, that returns to a required tab rather than Chat. `/asks [id]` selects pending questions. Collapse is available only without a blocker and returns to the exact input that lent focus, while it remains mounted. The extension never guesses a replacement from editor methods, classes or text. Normal SDK dialog events suppress question focus while another prompt is active; an established modal loan also recognizes its exact stock input. Hosts with optional public `ui.getCoreEditor()` identity can distinguish Chat from unannounced foreign prompts. A blocker returns to its exact modal loan; actually reclaiming an authoritative replacement or explicit stock `/asks` refreshes that loan, while an overlapping unannounced prompt defers the return without losing it. Normal Pi needs no SDK patch. Configured external-editor actions edit the original field and restore the TUI afterward.
+
+Private prompts and answers remain in the original Pi session/branch, never Threadroom’s API or discoverable outline. Saved native feedback retains its original prompt and answer identity, then steers a busy agent at a legal boundary or wakes an idle one. A closed Pi cannot be woken by this extension, and copied/forked different-session histories do not inherit ownership. Native async requires interactive TUI. Blocking questions also support SDK RPC/ACP dialogs; unsupported hosts and aborts are not human declines.
+
+All private admission closes as soon as Pi announces a switch, fork, tree change, or compaction. Positive lifecycle events reopen it; idle time is not treated as transition completion. Stock Pi does not report a cancelled or failed switch, fork, or tree transition back to extensions, so that rare outcome stays fail-closed: after the transition command itself has returned, use `/reload` and then `/asks`. This reload guidance is only presentation-lifecycle recovery—`/reload` never repairs storage uncertainty.
+
+Saving an answer, queueing feedback and recording its consumption receipt are different outcomes. Process-local submission IDs prevent blind resend across extension reload; they are not durable receipts. Cold recovery can replay unreceipted feedback, so subsequent AI work is not exactly-once. `/asks` exposes pending questions, answer identities and recovery diagnostics—do not submit again to repair delivery.
+
+The SDK can mutate memory before a failed disk write. Native records then remain **storage unconfirmed**: further private writes/delivery are blocked on that manager/session, even after `/reload`. Feedback receipts require a complete physical session-file row; memory-only hosts make no disk assertion. A pre-append refusal without branch mutation remains retryable. Recover the original journal and preserve/copy drafts before replacing the process; do not quit/resume as a storage-error feedback retry. This guard is not SDK journal rollback or repair.
+
+## Optional shared discussions
+
+Threadroom can bring someone a question, an experiment, or an interaction you designed—and let the discussion outlive this chat turn. Plain text is enough. A self-contained HTML/CSS/JS document can be a canvas, prototype, comparison, or something we haven't anticipated.
+
+The shared lane is **off by default**; private questions remain available. `/threadroom` opens the extension’s menu for status, watched discussions, and configuration. It can save a computer-wide default or, in a trusted project, an overriding project value. Direct command arguments are also accepted:
+
+```text
+/threadroom computer on
+/threadroom computer off
+/threadroom computer inherit
+/threadroom project on
+/threadroom project off
+/threadroom project inherit
+/threadroom status
+```
+
+The durable files are `~/.pi/agent/threadroom.json` (or Pi’s configured agent directory) and `<project>/.pi/threadroom.json`. Project configuration is not read before Pi trusts that project. Missing settings inherit downward from the built-in off default. A malformed effective setting fails the shared lane closed without disabling private questions; an explicit valid trusted-project value can still override a malformed computer default, which remains visible as a warning. Run `/reload` after changing the setting. When off, shared tools are absent from the model’s active tool set, configured shared endpoints are not parsed or contacted, restored shared watches do not connect, and no managed service starts.
+
+## Local development
+
+Private nonblocking questions need only normal interactive Pi—no Threadroom API, website, or patched SDK. The checkout command under Install isolates a trial from other extensions; preparing source does not reload a running session. Shared Threadroom tools lazily ensure the bundled local service only after that lane is explicitly enabled, unless an endpoint or startup opt-out assigns service ownership elsewhere.
+
+For normal project loading, first exclude any other producer of `ask_user_question`; do not load duplicate implementations. In a trusted project, Pi’s project package entry overrides an inherited entry with the same npm identity, so a project-local `{ "source": "npm:@juicesharp/rpiv-ask-user-question", "autoload": false, "extensions": ["-index.ts"] }` excludes that package's sole producer without changing global settings. An empty `extensions` delta does not exclude it. This is configuration guidance, not automatic installation or activation. Coordinate reload only after the ordinary editor has focus.
+
+The packed adapter includes the local service runtime. After the shared lane is enabled, the first shared Threadroom request—or restoration of active shared watches—reuses a compatible service or starts a detached API + website at `http://127.0.0.1:4310`. Private questions alone never start it. The detached service uses stable per-user storage and survives Pi reload/shutdown. Concurrent Pi sessions share a startup lease; health checks bind compatibility to the API version, website capability, and selected database rather than adopting an unrelated port owner.
+
+After shared Threadroom is enabled through `/threadroom`, runtime/service configuration uses environment variables:
+
+- `THREADROOM_API_URL`: an explicitly owned API endpoint. Setting it disables automatic local startup, even when it names localhost. Set the literal default URL too when intentionally using a checkout/supervised service with its own database.
+- `THREADROOM_UI_URL`: website address; defaults to the API address. Set it separately for an independently hosted website.
+- `THREADROOM_AUTO_START=0`: keep the default endpoint but require external service ownership.
+- `THREADROOM_DB`: local managed-service database. Relative values resolve against Pi’s invocation directory before the detached service changes directory; otherwise the platform’s per-user Threadroom data path is used.
+
+The experimental `THREADROOM_REPLACE_ASK` API alias has been retired. Threadroom always uses its own tool names; a stale setting cannot redirect ordinary native asks into the shared service.
+
+The current service is single-user and unauthenticated. Keep it local or use a trusted tunnel; author/session metadata is correlation, not permission. No production identity or authorized handoff claim is made here.
+
+Shared tools use owned Node HTTP/HTTPS connections, not host `fetch` or its global dispatcher. This avoids the [known Undici socket-QoS crash](https://github.com/nodejs/undici/issues/5544) without changing host networking or suppressing process exceptions. No new runtime dependency is needed. Native asks still make no HTTP requests; this does not fix unrelated uses of host fetch.
+
+## Participation
+
+`threadroom_ask` publishes a plain question or authored interaction in one call and watches its replies in this session. It returns immediately unless `waitMs` is supplied. There is no required options list, header, or form layout. It is a separate shared capability, not an emulator of the native questionnaire schema.
+
+`threadroom` covers ordinary contributions and replies, readable history, outline browsing, direct-node watches, and waiting on an existing question. Discussions can branch beneath any node, including an answer. Watches cover direct replies; a deeper branch can have its own watch. `/threadroom` shows the chosen API/website addresses, connectivity, and local participation. Connection errors also identify those endpoints. Enabled local use can start the bundled service; explicitly configured endpoints are only connected to, never started or replaced.
+
+Pi shows readable questions, saved reply intent, and durable discussion links—not raw authored programs or JSON envelopes. Expanded views reveal more history and receipt identity. Saved text is literal terminal text, not executable controls or Markdown. The full machine-facing records remain unchanged.
+
+Action results carry durable identities/links, saved status, provenance, and a small view of this session's watches. Large authored source and image values stay at their saved API address instead of being echoed into every turn. Browsing currently filters the full service outline locally and returns at most 50 matches; this isn't a server search/paging implementation.
+
+## What a reply means
+
+Later saved feedback enters the originating Pi session as a custom message. Busy agents receive it at Pi's next safe steering boundary; idle agents can wake. Delivery pauses around compaction and resumes afterward. During tree navigation/summarization it preserves the old watch without waking on the outgoing branch. Because Pi lacks a cancel/failure completion event there, a deferred receipt owns a small idle recheck timer; success rebinds the chosen branch, while cancellation/failure releases the gate when the host becomes idle. A clarification, rejection, or deferral retains its own meaning—it isn't silently turned into approval.
+
+Service events replay on reconnect. Adding a watch currently replays from the beginning, and an unsequenced answer found by a wait conservatively holds the checkpoint there until its transcript receipt exists. That trades transport work for recovery safety; scoped per-watch replay is future scalability work. Local checkpoints remember watched IDs and a safe replay position; they don't become another conversation database. A queued Pi message does **not** advance past an unconfirmed response. Only a corresponding persisted transcript receipt does. Reload reconciles receipts, so an interrupted checkpoint doesn't require asking the person again. The current host does not reliably expose whether a custom steering queue was discarded or remains queued after abort. The adapter therefore does not guess and resend during the same runtime; reading/waiting or a session reload recovers unpersisted feedback. This is not an exactly-once guarantee for whatever an agent does afterward.
+
+Wait results carry the request snapshot that established the outcome, not the original outstanding state beside a saved answer. Timeouts carry the last completed wait read, or the publication snapshot if no read completed; later changes remain readable. Timeout (maximum 120 seconds) and cancellation release the wait, not the question or watch. Connection failure is explicit; an ambiguous write returns a retry key for unchanged content. Reading an old discussion does not automatically inherit its original session's subscription. Forked sessions don't inherit live watches merely by copying a transcript; they can adopt a node explicitly.
+
+## Boundaries and next slice
+
+Threadroom owns saved conversations and presentation isolation. Authored scripts can propose drafts, but host controls own saving feedback. Pi owns session participation and model-message delivery. Neither side grants generated content filesystem, terminal, or model credentials.
+
+Private question state, results and persistence are separate from terminal focus. A future attached FlightDeck presenter can become the primary UI with terminal fallback; attachment selection and handoff are not implemented in this slice.
+
+The Node transport and participation modules under `src/` have no Pi or rendering imports. Another Node host can use them without implementing a Pi TUI. Constructing a `ThreadroomClient` allocates no agents or connections; its first request opens its own HTTP/HTTPS pool. REST deadlines include the response body; SSE stays open until its signal, stream failure, or client closure. Redirects are not followed and HTTPS retains ordinary certificate verification.
+
+A consumer owns the client's lifetime: close its participants first, then `await client.close()`. Client closure cancels its active requests/streams and releases its sockets, is idempotent, and permanently rejects new requests; it does not affect another client. `Participation.close()` ends that subscription, not the reusable client. The Pi extension releases its outgoing client on quit/reload/session replacement, giving a replacement session a fresh lazy client. A future terminal UI can consume the same service; its integration point remains open.
+
+Captured presentations are immutable today. An evolving job dashboard or two-way live workspace needs an explicit service capability, not a hidden local server or a Pi-only conversation store. Hard CPU isolation, authentication, remote deployment, large-history scalability, notification preferences, and broader host lifecycle evidence remain unfinished.
+
+## License
+
+The code distributed in this package, including its bundled local service runtime, is available under the [MIT License](LICENSE).

package/extensions/README.md

@@ -0,0 +1,15 @@
+# Pi host adapter
+
+`index.ts` registers our owned private question producer once, through `questions/`. It blocks by default and uses `blocking: false` for questions that can remain pending while work continues. Separate shared Threadroom tools are inactive by default and bind to Pi’s session/message lifecycle only after the `/threadroom` menu enables them for the computer or trusted project. Ordinary questions share flat input-area tabs; async arrivals stay passive, while any blocker makes that one surface required until it is answered or cancelled. A nonblocking identity can later acquire a blocking wait through the same tool without creating a second tab or changing its private persistence owner. The inline widget retains drafts, keeps async tabs available during a blocker, yields to foreign host prompts, and never replaces an editor or holds a custom-UI promise. `/asks` reopens pending private questions. Exclude other producers with the same ordinary ask name before loading this entry point; preparing source wiring does not activate a running seat. Shared discussions and authored interactions stay in the independent service.
+
+Tool rows and saved-feedback messages show the discussion title, durable website address, and what happened. Expand a row for nearby saved context, provenance labels, receipt identities and participation state. Authored programs never render as terminal source. The original tool result and message details remain unchanged for the model and session replay.
+
+The presentation helpers use Pi's `Text` components, with terminal controls and directional overrides made visible as text. Only validated HTTP(S) addresses become hyperlinks; terminals without hyperlink support still show the address. Author labels describe caller-supplied provenance, not authenticated approval.
+
+`/threadroom` owns the shared lane’s status, watched-discussion, and configuration menu. It writes the computer-wide default or trusted-project override, and `/reload` applies configuration changes. Project configuration is not read before trust. Missing configuration defaults off, and an invalid effective setting fails only the shared lane closed. When enabled, `/threadroom` shows the selected API and website addresses, connection state and session watches. Failed shared-tool operations show those addresses too. With no explicit API configuration, the first enabled shared operation or restored watch ensures a compatible detached local API + website is running. Private-only or disabled use does not parse configured endpoints and remains network- and service-free. Explicit endpoints retain external ownership and are never replaced or auto-started.
+
+The runtime uses the `@earendil-works/pi-tui` peer exposed by Pi's extension loader. Helpers live beneath `presentation/` without an extension entry point.
+
+## Host evidence
+
+`packages/pi-extension/test/presentation.test.js` loads the real adapter through Pi's discovery/loader, executes it against a real service, and renders through Pi's `ToolExecutionComponent` and `CustomMessageComponent`. It checks readable links, wait outcomes, feedback intent/provenance, receipt preservation, terminal safety, expansion and narrow widths. With a local Pi peer installed, the check participates in `npm test`. For a global install, `THREADROOM_PI_SDK_ROOT` names the installed `pi-coding-agent` package directory. A service-only checkout reports these host checks as skipped.

package/extensions/index.ts

@@ -0,0 +1,280 @@
+import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { ThreadroomClient } from '../src/client.js';
+import { Participation } from '../src/participation.js';
+import { renderAskCall, renderDiscussionCall, renderToolResult, renderFeedback, participationNotice } from './presentation/renderers.ts';
+import { registerPrivateQuestions } from './questions/index.ts';
+import { createManagedThreadroomService } from '../src/service-runtime.js';
+import { resolveThreadroomConfig, threadroomConfigPaths, writeThreadroomConfig } from '../src/config.js';
+
+const STATE = 'threadroom.participation.v1';
+const ACTIVITY = 'threadroom.reply.v1';
+
+export default function threadroom(pi: ExtensionAPI) {
+  registerPrivateQuestions(pi);
+  // Ordinary asks are the default. The shared lane is an explicit, reload-bound
+  // computer/project setting and never a prerequisite for private questions.
+  let sharedEnabled = false;
+  const sharedToolNames = new Set(['threadroom_ask', 'threadroom']);
+  function removeSharedTools() {
+    const active = pi.getActiveTools();
+    const privateOnly = active.filter((name) => !sharedToolNames.has(name));
+    if (privateOnly.length !== active.length) pi.setActiveTools(privateOnly);
+  }
+  async function configureShared(args: string, ctx: any) {
+    const trusted = typeof ctx.isProjectTrusted === 'function' && ctx.isProjectTrusted() === true;
+    const paths = threadroomConfigPaths({ cwd: ctx.cwd, agentDir: getAgentDir(), configDirName: CONFIG_DIR_NAME });
+    const words = args.trim().toLowerCase().split(/\s+/u).filter(Boolean);
+    let scope = words[0];
+    if (scope === 'global') scope = 'computer';
+    if (scope === 'local') scope = 'project';
+    if (!['computer', 'project'].includes(scope)) {
+      scope = await ctx.ui.select('Configure shared Threadroom', [
+        'Computer-wide default', ...(trusted ? ['This project'] : []),
+      ]).then((choice: string | undefined) => choice === 'Computer-wide default' ? 'computer' : choice === 'This project' ? 'project' : undefined);
+    }
+    if (!scope) return;
+    if (scope === 'project' && !trusted) { ctx.ui.notify('Project Threadroom overrides require a trusted project.', 'warning'); return; }
+    let setting = words[1];
+    if (!['on', 'off', 'inherit'].includes(setting)) {
+      const choices = scope === 'project' ? ['On', 'Off', 'Inherit computer-wide default'] : ['On', 'Off', 'Use built-in default (off)'];
+      setting = await ctx.ui.select(`${scope === 'project' ? 'Project' : 'Computer-wide'} shared Threadroom`, choices)
+        .then((choice: string | undefined) => choice === 'On' ? 'on' : choice === 'Off' ? 'off' : choice ? 'inherit' : undefined);
+    }
+    if (!setting) return;
+    const path = scope === 'project' ? paths.projectPath : paths.globalPath;
+    writeThreadroomConfig({ path, shared: setting === 'inherit' ? undefined : setting === 'on' });
+    ctx.ui.notify(`Saved ${scope === 'project' ? 'project override' : 'computer-wide default'} in ${path}. Run /reload to apply it.`, 'info');
+  }
+  const askToolName = 'threadroom_ask';
+  pi.registerMessageRenderer(ACTIVITY, renderFeedback);
+  let room: Participation | undefined;
+  let context: any;
+  let paused = false;
+  let navigating = false;
+  let running = false;
+  let navigationTimer: ReturnType<typeof setTimeout> | undefined;
+  let epoch = 0;
+  const configuredApiUrl = process.env.THREADROOM_API_URL;
+  const apiUrl = configuredApiUrl || 'http://127.0.0.1:4310';
+  const uiUrl = process.env.THREADROOM_UI_URL || apiUrl;
+  let endpoints = { apiUrl, uiUrl };
+  let managedService: ReturnType<typeof createManagedThreadroomService> | undefined;
+  let client: ThreadroomClient | undefined;
+  function ensureSharedRuntime() {
+    if (client) return;
+    managedService = !configuredApiUrl && process.env.THREADROOM_AUTO_START !== '0'
+      ? createManagedThreadroomService({ baseUrl: apiUrl, databaseValue: process.env.THREADROOM_DB, invocationCwd: process.cwd() })
+      : undefined;
+    client = new ThreadroomClient(apiUrl, { uiUrl, beforeConnect: managedService ? () => managedService!.ensure() : undefined });
+    endpoints = { apiUrl: client.baseUrl, uiUrl: client.uiUrl };
+  }
+
+  // Only active-branch, same-session checkpoints are inherited. Display names
+  // and copied/forked histories do not automatically confer a live subscription.
+  function receipts(entries: any[]) {
+    return entries.flatMap((entry) => {
+      if (entry.type === 'custom_message' && entry.customType === ACTIVITY) return entry.details?.receivedResponseIds || [];
+      if (entry.type === 'message' && entry.message.role === 'toolResult' &&
+          ['threadroom_ask', 'ask_user_question', 'threadroom'].includes(entry.message.toolName)) {
+        return entry.message.details?.receivedResponseIds || [];
+      }
+      return [];
+    });
+  }
+  // Pi has no tree-cancel/tree-failed event. Its isIdle() does include branch
+  // summarization. A deferred receipt therefore waits for host quiescence,
+  // without closing the old watch or waking a model on the outgoing branch.
+  function afterNavigation(mine: number, ctx: any) {
+    if (navigationTimer) return;
+    navigationTimer = setTimeout(() => {
+      navigationTimer = undefined;
+      if (mine !== epoch) return;
+      if (ctx.isIdle()) { navigating = false; room?.flush(); }
+      else afterNavigation(mine, ctx);
+    }, 100);
+    navigationTimer.unref();
+  }
+  async function bind(ctx: any) {
+    ensureSharedRuntime(); const activeClient = client!;
+    const mine = ++epoch;
+    clearTimeout(navigationTimer); navigationTimer = undefined;
+    const old = room; room = undefined; await old?.close();
+    if (mine !== epoch) return;
+    context = ctx; paused = false; navigating = false; running = false;
+    const sessionId = ctx.sessionManager.getSessionId();
+    const entries = ctx.sessionManager.getBranch();
+    const saved = entries.filter((entry: any) => entry.type === 'custom' && entry.customType === STATE &&
+      entry.data?.sessionId === sessionId && entry.data?.apiUrl === activeClient.baseUrl).at(-1)?.data;
+    const author = saved?.author || { id: `pi:${sessionId}`, sessionId, name: pi.getSessionName() || 'Pi teammate' };
+    room = new Participation(activeClient, { state: saved?.state, received: receipts(entries), author,
+      checkpoint(state: any) {
+        if (mine === epoch) pi.appendEntry(STATE, { sessionId, apiUrl: activeClient.baseUrl, author, state });
+      },
+      deliver(receipt: any) {
+        if (mine !== epoch) return false;
+        if (paused) return false;
+        if (navigating || (!running && !ctx.isIdle())) { afterNavigation(mine, ctx); return false; }
+        const details = { target: receipt.target, response: receipt.response,
+          receivedResponseIds: [receipt.responseId], apiUrl: activeClient.baseUrl,
+          delivery: { eventId: receipt.eventId, sequence: receipt.sequence } };
+        pi.sendMessage({ customType: ACTIVITY, display: true, details,
+          content: `Saved Threadroom feedback (caller-provided author labels; not blanket authorization):\n${JSON.stringify(details)}` },
+          { deliverAs: 'steer', triggerTurn: true });
+        pi.events.emit('threadroom:activity', details);
+      },
+      connection(state: any) {
+        if (mine !== epoch) return;
+        ctx.ui.setStatus('threadroom', `Threadroom: ${state.status}`);
+        pi.events.emit('threadroom:connection', state);
+      },
+    });
+    room.start();
+  }
+  function confirmPersisted(ctx: any) {
+    if (!room || context?.sessionManager.getSessionId() !== ctx.sessionManager.getSessionId()) return;
+    room.acknowledge(receipts(ctx.sessionManager.getBranch()));
+  }
+  async function use(ctx: any) {
+    if (!sharedEnabled) throw Object.assign(new Error('Shared Threadroom is disabled. Use /threadroom, then /reload, to enable it for this computer or project.'), { code: 'threadroom_disabled' });
+    if (!room) await bind(ctx);
+    if (!room) throw new Error('Threadroom session is changing; retry in the active session.');
+    confirmPersisted(ctx);
+    return room;
+  }
+  pi.on('session_start', async (_event, ctx) => {
+    const config = resolveThreadroomConfig({ cwd: ctx.cwd, agentDir: getAgentDir(), configDirName: CONFIG_DIR_NAME,
+      projectTrusted: typeof ctx.isProjectTrusted === 'function' && ctx.isProjectTrusted() === true });
+    sharedEnabled = config.enabled;
+    for (const warning of config.warnings) ctx.ui.notify(`Threadroom configuration warning: ${warning}`, 'warning');
+    if (!sharedEnabled) {
+      removeSharedTools(); ctx.ui.setStatus('threadroom', undefined);
+      const old = room; room = undefined; await old?.close();
+      return;
+    }
+    await bind(ctx);
+  });
+  pi.on('session_shutdown', async () => {
+    sharedEnabled = false; ++epoch; clearTimeout(navigationTimer); navigationTimer = undefined;
+    const old = room; room = undefined;
+    // Session replacement can reuse this factory; the next session gets its own
+    // lazy client while outgoing HTTP work belongs to the captured old client.
+    const oldClient = client; client = undefined; managedService = undefined;
+    try { await old?.close(); } finally { await oldClient?.close(); }
+  });
+  pi.on('session_before_tree', () => { if (sharedEnabled) navigating = true; });
+  pi.on('agent_start', () => { if (sharedEnabled) running = true; });
+  pi.on('session_tree', async (_event, ctx) => { if (sharedEnabled) await bind(ctx); });
+  pi.on('session_before_compact', () => { if (sharedEnabled) paused = true; });
+  pi.on('session_compact', (_event, ctx) => { if (sharedEnabled) { paused = false; confirmPersisted(ctx); room?.flush(); } });
+  pi.on('session_compact_failed', (_event, ctx) => { if (sharedEnabled) { paused = false; confirmPersisted(ctx); room?.flush(); } });
+  // These boundaries occur after messages/tool results have been appended.
+  pi.on('turn_end', (_event, ctx) => { if (sharedEnabled) confirmPersisted(ctx); });
+  pi.on('agent_settled', (_event, ctx) => {
+    running = false;
+    if (sharedEnabled) { confirmPersisted(ctx); room?.flush(); }
+  });
+
+  function renderResult(result: any, options: any, theme: any, context: any) {
+    return renderToolResult(result, options, theme, { ...context, endpoints });
+  }
+  function result(value: any) { return { content: [{ type: 'text' as const, text: JSON.stringify(value) }], details: value }; }
+  function failure(error: any) {
+    return result({ error: error.message, status: error.status, retryKey: error.retryKey,
+      publication: error.ambiguous ? 'unknown; the write may already be saved. Reuse the retry key with unchanged content.' : 'not confirmed',
+      participation: room?.adjacent() });
+  }
+  const timeout = Type.Optional(Type.Integer({ minimum: 0, maximum: 120000,
+    description: 'Wait up to this many milliseconds. Omit to continue immediately; timeout/cancel does not withdraw the question.' }));
+
+  pi.registerTool({
+    name: askToolName, label: 'Ask in Threadroom',
+    renderCall: renderAskCall, renderResult,
+    description: 'Bring the person a question or an interaction you designed. Threadroom saves it and its presentation, returns a durable address, and brings later replies into this session. Returns immediately unless you choose to wait. Authored HTML/JS runs in the service sandbox; its proposals are drafts, while the surrounding host owns saving an answer. Plain text and suggested choices are conveniences, not limits on what you can show.',
+    parameters: Type.Object({
+      question: Type.String({ description: 'What you want to discuss.' }),
+      body: Type.Optional(Type.String({ description: 'Written context.' })),
+      html: Type.Optional(Type.String({ description: 'Self-contained HTML/CSS/JS interaction, captured with the question.' })),
+      fallback: Type.Optional(Type.String({ description: 'Readable meaning of the authored interaction, without running it.' })),
+      choices: Type.Optional(Type.Array(Type.String(), { description: 'Optional suggested answers; the person can respond freely.' })),
+      multiple: Type.Optional(Type.Boolean()),
+      project: Type.Optional(Type.String({ description: 'Convenient scope name; use this, path, or parentId.' })),
+      path: Type.Optional(Type.Array(Type.String(), { description: 'Ancestor titles, resolved or created in the same call.' })),
+      parentId: Type.Optional(Type.String({ description: 'An existing node, including an answer, to continue beneath.' })),
+      waitMs: timeout,
+      retryKey: Type.Optional(Type.String({ description: 'Recover an ambiguous publication with unchanged content.' })),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      try {
+        const active = await use(ctx);
+        const { waitMs, retryKey, ...input } = params;
+        const published = await active.publish(input, { waitMs, signal,
+          key: retryKey || `pi:${ctx.sessionManager.getSessionId()}:${toolCallId}` });
+        pi.events.emit('threadroom:published', published);
+        return result(published);
+      } catch (error) { return failure(error); }
+    },
+  });
+
+  pi.registerTool({
+    name: 'threadroom', label: 'Threadroom',
+    renderCall: renderDiscussionCall, renderResult,
+    description: 'Participate in lasting discussions: read saved work and feedback, browse the outline/history, publish a contribution, reply beneath a node, or watch a node in this session. Waiting is optional and does not change the shared conversation. Action results carry identities, response provenance, durable links, and this session’s nearby participation state. Watches receive direct replies; deeper branches can be watched independently.',
+    parameters: Type.Object({
+      action: Type.Union(['read', 'browse', 'publish', 'reply', 'watch', 'unwatch', 'wait'].map((value) => Type.Literal(value))),
+      id: Type.Optional(Type.String({ description: 'Target node identity.' })),
+      input: Type.Optional(Type.Record(Type.String(), Type.Unknown(), {
+        description: 'Service contribution: title/question, body, authored html/fallback or presentation, and path/parentId scope. Replies may carry response intent (kind), selections and their own presentation.' })),
+      waitMs: timeout,
+      retryKey: Type.Optional(Type.String()),
+      query: Type.Optional(Type.String({ description: 'Filter outline titles locally.' })),
+      status: Type.Optional(Type.String({ description: 'Filter outline answer-request status.' })),
+    }),
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      try {
+        const active = await use(ctx);
+        const key = params.retryKey || `pi:${ctx.sessionManager.getSessionId()}:${toolCallId}`;
+        const id = params.id;
+        if (!['browse', 'publish'].includes(params.action) && !id) throw new Error('This action needs a node id.');
+        switch (params.action) {
+          case 'publish': return result(await active.publish(params.input || {}, { key, signal, waitMs: params.waitMs }));
+          case 'reply': return result(await active.respond(id, params.input || {}, { key, signal }));
+          case 'read': return result(await active.read(id, { signal }));
+          case 'watch': return result(await active.watch(id, { signal }));
+          case 'unwatch': return result(active.unwatch(id));
+          case 'wait': return result({ id, url: client!.link(id), ...await active.wait(id, { timeoutMs: params.waitMs, signal }) });
+          case 'browse': {
+            const tree = await client!.tree({ signal });
+            const nodes = tree.nodes.filter((node: any) => (!params.query || node.title.toLowerCase().includes(params.query.toLowerCase())) &&
+              (!params.status || node.status === params.status));
+            return result({ nodes: nodes.slice(0, 50).map((node: any) => ({ ...node, url: client!.link(node.id) })),
+              omitted: Math.max(0, nodes.length - 50), participation: active.adjacent() });
+          }
+        }
+      } catch (error) { return failure(error); }
+    },
+  });
+
+  pi.registerCommand('threadroom', { description: 'Configure Threadroom or inspect its connectivity and watched discussions.',
+    async handler(args, ctx) {
+      const words = args.trim().toLowerCase().split(/\s+/u).filter(Boolean);
+      if (['computer', 'global', 'project', 'local'].includes(words[0])) { await configureShared(args, ctx); return; }
+      let action = words[0];
+      if (!action) {
+        const trusted = typeof ctx.isProjectTrusted === 'function' && ctx.isProjectTrusted() === true;
+        const choice = await ctx.ui.select(`Threadroom (${sharedEnabled ? 'on' : 'off'})`, [
+          ...(sharedEnabled ? ['Show status and watched discussions'] : []),
+          'Configure computer-wide default', ...(trusted ? ['Configure this project'] : []),
+        ]);
+        if (choice === 'Configure computer-wide default') { await configureShared('computer', ctx); return; }
+        if (choice === 'Configure this project') { await configureShared('project', ctx); return; }
+        if (choice === 'Show status and watched discussions') action = 'status'; else return;
+      }
+      if (action !== 'status') {
+        ctx.ui.notify('Usage: /threadroom, /threadroom status, or /threadroom <computer|project> <on|off|inherit>.', 'warning');
+        return;
+      }
+      if (!sharedEnabled) { ctx.ui.notify('Shared Threadroom is off. Run /threadroom to configure it.', 'info'); return; }
+      ensureSharedRuntime(); await managedService?.ensure(); const active = await use(ctx); ctx.ui.notify(participationNotice(active.adjacent(), endpoints), 'info');
+    } });
+}