@xingular/harness 2.0.0 → 2.1.1

package/dist/terminal-pi.js

@@ -18,7 +18,7 @@ function connectionFromEnv(env = process.env) {
   if (!socket || !token) throw new SocketError("not_configured", `This command only works inside a terminal session the harness started (${SOCKET_ENV} and ${TOKEN_ENV} are not set).`);
   return { socket, token };
 }
-function request(connection, body, what, timeoutMs) {
+function request(connection, body2, what, timeoutMs) {
   return new Promise((resolve, reject) => {
     const stream = createConnection(connection.socket);
     let buffer = "";
@@ -34,7 +34,7 @@ function request(connection, body, what, timeoutMs) {
       stream.destroy();
       finish(() => reject(new SocketError("timeout", `The harness did not answer ${what}.`)));
     }, timeoutMs);
-    stream.on("connect", () => stream.write(`${JSON.stringify({ token: connection.token, ...body })}
+    stream.on("connect", () => stream.write(`${JSON.stringify({ token: connection.token, ...body2 })}
 `));
     stream.on("data", (chunk) => {
       buffer += chunk.toString("utf8");
@@ -177,13 +177,13 @@ async function addAccount(ui, call) {
   if (await attempt(ui, () => call("accounts.create", { label: label.trim(), authKind: "subscription" }))) ui.notify("Account added. Sign in to use it.", "info");
 }
 async function accountMenu(ui, call, session, accountId) {
-  const isSession = session.accountId === accountId;
+  const isSession2 = session.accountId === accountId;
   for (; ; ) {
     const overview = await call("accounts.list");
     const account = overview.accounts.find((candidate) => candidate.id === accountId);
     if (!account) return;
     const actions = [
-      ...isSession ? [] : [USE_HERE],
+      ...isSession2 ? [] : [USE_HERE],
       ...account.isDefault ? [] : [MAKE_DEFAULT],
       RENAME,
       CHECK,
@@ -193,7 +193,7 @@ async function accountMenu(ui, call, session, accountId) {
       ...account.state.piProviders.length ? [REMOVE_PROVIDER] : [],
       SIGN_OUT,
       // The session's own account is in use, so it cannot be removed from inside the session.
-      ...isSession ? [] : [REMOVE],
+      ...isSession2 ? [] : [REMOVE],
       BACK
     ];
     const action = await ui.select(`${account.label} \xB7 ${HEALTH[account.state.health] ?? HEALTH.unknown}`, actions);
@@ -278,16 +278,16 @@ async function followLogin(ui, call, accountId, loginId) {
   const deadline = Date.now() + LOGIN_TIMEOUT_MS;
   let shownRevision = -1;
   for (; ; ) {
-    const snapshot = await call("accounts.loginStatus", { accountId });
-    if (!snapshot || snapshot.loginId !== loginId) return;
-    if (snapshot.status !== "running") return reportLogin(ui, snapshot);
-    if (snapshot.prompt) {
-      await answerPrompt(ui, call, loginId, snapshot.prompt);
+    const snapshot2 = await call("accounts.loginStatus", { accountId });
+    if (!snapshot2 || snapshot2.loginId !== loginId) return;
+    if (snapshot2.status !== "running") return reportLogin(ui, snapshot2);
+    if (snapshot2.prompt) {
+      await answerPrompt(ui, call, loginId, snapshot2.prompt);
       continue;
     }
-    const step = [...snapshot.events].reverse().map(loginStep).find((text3) => text3 !== null);
-    if (step && snapshot.revision !== shownRevision) {
-      shownRevision = snapshot.revision;
+    const step = [...snapshot2.events].reverse().map(loginStep).find((text3) => text3 !== null);
+    if (step && snapshot2.revision !== shownRevision) {
+      shownRevision = snapshot2.revision;
       const choice = await ui.select(`${step}
 
 Finish in your browser, then choose Check status.`, [CHECK_STATUS, CANCEL_SIGN_IN]);
@@ -306,10 +306,10 @@ Finish in your browser, then choose Check status.`, [CHECK_STATUS, CANCEL_SIGN_I
     await new Promise((resolve) => setTimeout(resolve, POLL_MS));
   }
 }
-function reportLogin(ui, snapshot) {
-  if (snapshot.status === "completed") ui.notify("Signed in.", "info");
-  else if (snapshot.status === "cancelled") ui.notify("Sign-in was cancelled.", "warning");
-  else ui.notify(snapshot.error ?? "Sign-in failed.", "error");
+function reportLogin(ui, snapshot2) {
+  if (snapshot2.status === "completed") ui.notify("Signed in.", "info");
+  else if (snapshot2.status === "cancelled") ui.notify("Sign-in was cancelled.", "warning");
+  else ui.notify(snapshot2.error ?? "Sign-in failed.", "error");
 }
 async function answerPrompt(ui, call, loginId, prompt) {
   const promptId = String(prompt.promptId ?? "");
@@ -838,6 +838,59 @@ function askUserTool(run2) {
   };
 }
 
+// src/core/frontmatter.ts
+import { parse as parseYaml, stringify } from "yaml";
+
+// src/memory/store.ts
+import { stringify as stringify2 } from "yaml";
+
+// src/skills/registry.ts
+var MAX_SKILL_IMPORT_BYTES = 10 * 1024 * 1024;
+
+// src/prompt/compile.ts
+var SECTION_ORDER = { blocks: 30, rules: 40, references: 50, skills: 60, knowledge: 80, tools: 90 };
+var BUILT_IN_DYNAMIC = [
+  { id: "blocks", order: SECTION_ORDER.blocks },
+  { id: "references", order: SECTION_ORDER.references },
+  { id: "knowledge", order: SECTION_ORDER.knowledge }
+];
+
+// src/sessions/planMode.ts
+var PLAN_READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
+  "read",
+  "grep",
+  "find",
+  "ls",
+  ASK_USER,
+  "ask_user_question",
+  "history_search",
+  "history_read",
+  "trajectory_search",
+  "trajectory_read",
+  "wiki_entrypoint",
+  "wiki_search",
+  "wiki_read",
+  "wiki_list",
+  "memory_facts",
+  "skill_load",
+  "mcp_list_tools"
+]);
+var PLAN_OPEN_TAG = "<proposed_plan>";
+var PLAN_CLOSE_TAG = "</proposed_plan>";
+var PLAN_INSTRUCTIONS = `Plan mode is on for this request. Investigate and design; do not carry out the work.
+- Read, search and recall freely. When a decision belongs to the user, ask with ${ASK_USER} instead of guessing.
+- Do not change files, run commands, write memory, delegate, or call connected apps. Such calls are refused while plan mode is on.
+- When the plan is ready, end the reply with exactly one block in this form, after any other text:
+${PLAN_OPEN_TAG}
+# <Plan title>
+<Markdown: the context, the steps with the files they change, and how to verify the result>
+${PLAN_CLOSE_TAG}
+- If you need the user's input before a plan is possible, ask instead of proposing one.`;
+function planRefusal(tool, readOnly) {
+  if (PLAN_READ_ONLY_TOOLS.has(tool) || readOnly.has(tool)) return null;
+  return `Plan mode is read-only: ${tool} is not available until the user leaves plan mode. Continue investigating, or finish with a ${PLAN_OPEN_TAG} block.`;
+}
+
 // src/terminal/piExtension.ts
 function resultSize(result) {
   const content = result?.content;
@@ -857,7 +910,7 @@ async function withParentCancellation(signal, work) {
     signal?.removeEventListener("abort", stop);
   }
 }
-async function piExtension_default(pi) {
+async function piExtension_default(pi, planRun) {
   await terminalCall("startup", { phase: "Pi extension loaded" });
   let context = null;
   let nativeSubagents = false;
@@ -982,6 +1035,10 @@ async function piExtension_default(pi) {
       await controlCall("terminal.subagents.register", { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) });
       subagentParent = true;
     }
+    if (planRun && event.messageType === "user") {
+      if (planRun.active) event.systemPromptOptions.sections.plan = PLAN_INSTRUCTIONS;
+      else delete event.systemPromptOptions.sections.plan;
+    }
   });
   const deliverChildren = async (event, ctx, settle) => {
     if (!nativeSubagents || settle && event.outcome !== "completed" || ctx.signal?.aborted) return;
@@ -1039,6 +1096,10 @@ async function piExtension_default(pi) {
     requestStartedAt = Date.now();
   });
   pi.on("tool_call", async (event) => {
+    if (planRun?.active && !planRun.allowedTools.has(event.toolName)) {
+      const reason = planRefusal(event.toolName, /* @__PURE__ */ new Set()) ?? `Plan mode is read-only: ${event.toolName} is not available in this session.`;
+      return { block: true, reason };
+    }
     try {
       const policy = await controlCall("terminal.policy", { tool: event.toolName, args: event.input });
       if (policy.requiresApproval) {

package/docs/decisions/ADR-0003-shared-asynchronous-subagents.md

@@ -59,10 +59,12 @@ recovery windows. Real scripted Pi tests in `conversation.test.ts` cover async d
 receipts and interruption during a child question. `runtime.socket.test.ts` exercises the real
 terminal socket, private controls, native execution and child decision routing. RPC and App host
 regressions cover protocol shapes and ancestry. Tests use disposable storage without external
-model requests. These are working-tree changes, not a publication or live-provider acceptance claim.
+model requests. These changes shipped in `@xingular/harness` 2.0.0 (commit `44471bc`); release does not imply live-provider acceptance.
 
 Verification on 2026-10-18: Harness typecheck, 455 tests (two skipped), unchanged golden fixtures,
 build and standalone proof passed. App typecheck, layer/UI checks, sidecar build, 30 sidecar tests
 and 217 Rust tests passed (one ignored). The renderer suite passed 491 tests and retained its
 pre-existing `PendingRequestDock.test.ts` heading-text assertion failure. No live account or
 user-data-root testing was performed.
+
+Release verification on 2026-10-18: npm 10 clean install, typecheck, 515 tests (two skipped), build and standalone proof passed. GitHub CI passed on Ubuntu and macOS, and the npm publish workflow released version 2.0.0 with provenance. No live provider requests were made during release verification.

package/docs/terminal-tui.md

@@ -87,16 +87,22 @@ The decision and its consequences are recorded in
 
 ## Plan mode and thinking keys
 
-Shift+Tab switches the terminal between normal and plan mode. The switch is announced in the
-transcript. Plan mode narrows the session to read-only inspection (`read`, `grep`, `find`, `ls`),
-questions (`ask_user`, `ask_user_question`) and recall (history and Wiki reads, `memory_facts`). Edits,
-writes, shell commands, memory writes, subagents and connected-app tools are withdrawn until plan mode
-is switched off, and switching back restores the tools the session had. Plan mode belongs to the open
-conversation: a new or resumed session starts in normal mode.
-
-The model is not yet told about the mode through the prompt; it only sees the narrower tool set. That
-instruction belongs in the prompt compiler, the one place model instructions are built. Shift+Up and
-Shift+Down step the thinking level within the levels the model supports, and do not wrap.
+Use `/plan <brief>` for one read-only planning request. A plan waits outside Pi's native follow-up
+queue until the active response settles, then runs by itself. Later messages remain behind it, even
+when Pi's follow-up mode is `all`. During that run the session narrows to read-only inspection
+(`read`, `grep`, `find`, `ls`), questions (`ask_user`, `ask_user_question`) and recall (history and
+Wiki reads, `memory_facts`); edits, writes, shell commands, memory writes, subagents and connected-app
+tools are blocked. The plan instructions arrive as a request-scoped prompt section, which the next
+ordinary request withdraws. `/plan` without a brief and the old on/off/toggle forms are rejected.
+
+While typing, a recognized leading slash command uses the selected theme's link color. This
+includes built-in commands, loaded extension and prompt commands, and enabled skill invocations
+written as `/skill:name`. Unknown slash tokens keep the normal text color.
+
+SDK session runs receive plan instructions as a dynamic context update, leaving the stable system
+prompt unchanged; their session gate refuses calls outside the read-only set. The standalone
+terminal applies the same one-run instructions and tool restrictions. Shift+Up and Shift+Down step
+the thinking level within the levels the model supports, and do not wrap.
 
 ## Reference and reproduced presentation
 
@@ -302,9 +308,9 @@ The [live report and capture](evidence/terminal-2026-10-17-followup/live-codex/R
 this quota failure explicitly. Successful live streaming/tool acceptance remains open until
 account capacity is available. GitHub gist publication, actual OS clipboard/image transfer,
 Windows behavior and every terminal emulator remain unverified. Rich image/diff rendering and clipboard adapters have
-focused compatibility tests; that does not establish OS interaction. These working-tree changes
-are not a published release and the complete plan's acceptance remains open while required
-integration/provider evidence is outstanding.
+focused compatibility tests; that does not establish OS interaction. These changes shipped in
+`@xingular/harness` 2.0.0 (commit `44471bc`), while the complete plan's acceptance remains
+open pending the required integration and provider evidence.
 
 To reproduce the controlled scenario after building:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xingular/harness",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "type": "module",
   "description": "Xingular Harness — a Pi agent harness with multi-account sign-in, a compiled system prompt, a memory lifecycle (Wiki), tools, MCP, and skills",
   "repository": {

package/src/hub/hub.test.ts

@@ -40,6 +40,8 @@ describe('Hub installation', () => {
     expect(existsSync(join(root, 'config', 'plugin-attachments.json'))).toBe(false)
     writeFileSync(join(root, 'hub', 'documents', receipt.document!), '{"edited":true}')
     expect(() => hub.readDocument('example/review', '1.0.0')).toThrow('differs')
+    expect((await hub.list()).installed[0]).toMatchObject({ state: 'changed' })
+    await expect(hub.install('example/review', '1.0.0')).rejects.toThrow('Uninstall it before installing')
   })
   it('imports complete skills disabled and refuses overwriting local files', async () => {
     const { hub, root } = fixture([entry('registry', skill())])
@@ -90,12 +92,58 @@ describe('Hub installation', () => {
     expect(preview.delivery.kind !== 'pi-package' && preview.delivery.bundled).toContain('data only')
     expect(existsSync(join(root, 'hub'))).toBe(false)
   })
+  it('returns bounded UTF-8-safe preview pages and reuses the verified download for install', async () => {
+    const content = `"${'é'.repeat(20_000)}"`
+    const item = entry('document', content)
+    if (item.delivery.kind !== 'pi-package') delete item.delivery.bundled
+    const fetcher = vi.fn(async () => new Response(content)) as typeof fetch
+    const { hub, root } = fixture([item], fetcher)
+    const pages = []
+    let offset = 0
+    while (true) {
+      const page = await hub.preview(item.id, item.version, offset)
+      expect(Buffer.byteLength(page.content)).toBeLessThanOrEqual(16 * 1024)
+      pages.push(page.content)
+      if (page.done) break
+      offset = page.nextOffset
+    }
+    expect(pages.join('')).toBe(content)
+    expect(fetcher).toHaveBeenCalledTimes(1)
+    await hub.install(item.id, item.version)
+    expect(fetcher).toHaveBeenCalledTimes(1)
+    expect(existsSync(join(root, 'hub', 'documents'))).toBe(true)
+  })
+  it('uninstalls only its receipt-owned document, including local edits', async () => {
+    const first = entry()
+    const second = { ...entry(), id: 'example/second', title: 'Second' }
+    const { hub, root } = fixture([first, second])
+    const owned = await hub.install(first.id, first.version)
+    const other = await hub.install(second.id, second.version)
+    writeFileSync(join(root, 'hub', 'documents', owned.document!), '{"local":true}')
+    await hub.uninstall(first.id, first.version)
+    expect(existsSync(join(root, 'hub', 'documents', owned.document!))).toBe(false)
+    expect(existsSync(join(root, 'hub', 'documents', other.document!))).toBe(true)
+    expect((await hub.list()).installed.map((receipt) => receipt.entry.id)).toEqual([second.id])
+  })
+  it('uninstalls only receipt-owned registry resources and leaves unrelated files', async () => {
+    const { hub, root } = fixture([entry('registry', skill())])
+    const receipt = await hub.install('example/review', '1.0.0')
+    const unrelated = join(root, 'registry', 'skills', 'unrelated', 'SKILL.md')
+    mkdirSync(join(root, 'registry', 'skills', 'unrelated'), { recursive: true })
+    writeFileSync(unrelated, '---\nname: unrelated\ndescription: Local.\n---\n')
+    await hub.uninstall('example/review', '1.0.0')
+    expect(existsSync(join(root, 'registry', 'skills', 'review'))).toBe(false)
+    expect(readFileSync(unrelated, 'utf8')).toContain('unrelated')
+    expect((await hub.list()).installed).toEqual([])
+    expect(receipt.resourceIds).toEqual(['skills/review'])
+  })
   it('can reinstall deleted resources and clears stale attachment grants', async () => {
     const { hub, root } = fixture([entry('registry', skill())])
     await hub.install('example/review', '1.0.0')
     registry.setEnabled(root, null, ['skills/review'])
     rmSync(join(root, 'registry', 'skills', 'review'), { recursive: true })
-    expect((await hub.list()).installed).toEqual([])
+    expect((await hub.list()).installed[0]).toMatchObject({ state: 'incomplete' })
+    await hub.uninstall('example/review', '1.0.0')
     await hub.install('example/review', '1.0.0')
     expect(registry.enabledFor(root, null)).toEqual([])
     expect((await hub.list()).installed).toHaveLength(1)

package/src/hub/hub.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { closeSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { watch } from 'node:fs'
 
@@ -12,7 +12,7 @@ import * as registry from '../skills/registry'
 import * as attachments from '../plugins/attachments'
 import { version as harnessVersion } from '../../package.json'
 import bundled from './catalog.json'
-import { HUB_CATALOG_URL, HUB_MAX_BYTES, hubCatalogSchema, hubEntrySchema, hubReceiptSchema, meetsMinimum, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './schema'
+import { HUB_CATALOG_URL, HUB_MAX_BYTES, HUB_PREVIEW_PAGE_BYTES, hubCatalogSchema, hubEntrySchema, hubReceiptSchema, meetsMinimum, type HubCatalog, type HubEntry, type HubOverview, type HubReceipt } from './schema'
 
 export interface HubOptions {
   catalogUrl?: string
@@ -60,6 +60,7 @@ export class Hub {
   private watcher: ReturnType<typeof watch> | null = null
   private refresh: Promise<HubOverview> | null = null
   private installing = false
+  private cachedPayload: { key: string; bytes: Buffer; expiresAt: number } | null = null
   get busy(): boolean { return this.installing }
 
   constructor(private readonly harness: Harness, options: HubOptions = {}) {
@@ -80,12 +81,25 @@ export class Hub {
     const cached = readJsonOr<{ catalog: unknown; at: string } | null>(join(this.harness.stateDir, 'hub', 'catalog.json'), null)
     const parsed = hubCatalogSchema.safeParse(cached?.catalog)
     const catalog = parsed.success ? parsed.data : this.fallback
-    const installed = this.receipts().filter((receipt) => this.present(receipt))
+    const installed = this.receipts().map((receipt) => ({ ...receipt, state: this.receiptState(receipt) }))
     const entries = new Map(catalog.entries.map((entry) => [`${entry.id}@${entry.version}`, entry]))
     for (const receipt of installed) if (!entries.has(`${receipt.entry.id}@${receipt.entry.version}`)) entries.set(`${receipt.entry.id}@${receipt.entry.version}`, receipt.entry)
     return { entries: [...entries.values()], installed, origin: parsed.success ? 'cached' : 'bundled', refreshedAt: parsed.success ? cached!.at : null, error: null, dataRoot: this.harness.dataRoot, stateDir: this.harness.stateDir }
   }
 
+  private receiptState(receipt: HubReceipt): 'installed' | 'changed' | 'incomplete' {
+    if (receipt.document && receipt.entry.delivery.kind === 'document') {
+      if (receipt.document !== `${receiptName(receipt.entry)}.json`) return 'incomplete'
+      try {
+        const path = join(this.harness.dataRoot!, 'hub', 'documents', receipt.document)
+        const stat = lstatSync(path)
+        if (!stat.isFile() || stat.size > HUB_MAX_BYTES) return 'incomplete'
+        return digest(readFileSync(path)) === receipt.entry.delivery.sha256 ? 'installed' : 'changed'
+      } catch { return 'incomplete' }
+    }
+    return this.present(receipt) ? 'installed' : 'incomplete'
+  }
+
   private present(receipt: HubReceipt): boolean {
     const root = this.harness.dataRoot
     if (!root) return false
@@ -169,6 +183,28 @@ export class Hub {
     return { ...entry, delivery: { ...entry.delivery, bundled: this.decode(bytes) } }
   }
 
+  private async verifiedPayload(entry: HubEntry): Promise<Buffer> {
+    if (entry.delivery.kind === 'pi-package') throw invalid('Packages do not have a JSON payload preview.')
+    const key = `${entry.id}@${entry.version}`
+    if (this.cachedPayload?.key === key && this.cachedPayload.expiresAt > Date.now()) return this.cachedPayload.bytes
+    const bytes = entry.delivery.bundled === undefined ? await this.bytes(entry.delivery.url) : Buffer.from(entry.delivery.bundled)
+    if (digest(bytes) !== entry.delivery.sha256) throw invalid('The downloaded item differs from the reviewed version. Nothing was installed.')
+    this.decode(bytes)
+    this.cachedPayload = { key, bytes, expiresAt: Date.now() + 5 * 60 * 1000 }
+    return bytes
+  }
+
+  async preview(id: string, version: string, offset = 0) {
+    if (!Number.isSafeInteger(offset) || offset < 0) throw invalid('Preview offset must be a non-negative byte position.')
+    const entry = this.find(id, version)
+    const bytes = await this.verifiedPayload(entry)
+    if (offset > bytes.length || offset < bytes.length && (bytes[offset] & 0xc0) === 0x80) throw invalid('Preview offset is outside the payload or splits a UTF-8 character.')
+    let end = Math.min(offset + HUB_PREVIEW_PAGE_BYTES, bytes.length)
+    while (end > offset && end < bytes.length && (bytes[end] & 0xc0) === 0x80) end -= 1
+    const content = this.decode(bytes.subarray(offset, end))
+    return { entry, content, offset, nextOffset: end, totalBytes: bytes.length, done: end >= bytes.length }
+  }
+
   async install(id: string, version: string): Promise<HubReceipt> {
     const root = this.harness.env.root
     const entry = hubEntrySchema.parse(this.find(id, version))
@@ -181,6 +217,7 @@ export class Hub {
       const records = this.receipts()
       const existing = records.find((receipt) => receipt.entry.id === id && receipt.entry.version === version)
       if (existing && this.present(existing)) return existing
+      if (existing) throw invalid('This Hub receipt is changed or incomplete. Uninstall it before installing this version again.')
       const remaining = records.filter((record) => record !== existing)
       const receipt: HubReceipt = { entry, installedAt: now(), resourceIds: [], document: null }
       const choicesBefore = attachments.load(root)
@@ -195,13 +232,14 @@ export class Hub {
         if (!receipt.resourceIds.length) throw invalid('The package did not add an installable plugin. No hub installation was recorded.')
       } else {
         const delivery = entry.delivery
-        const bytes = delivery.bundled === undefined ? await this.bytes(delivery.url) : Buffer.from(delivery.bundled)
-        if (digest(bytes) !== delivery.sha256) throw invalid('The downloaded item differs from the reviewed version. Nothing was installed.')
+        const bytes = await this.verifiedPayload(entry)
         const text = this.decode(bytes)
         if (delivery.kind === 'document') {
           JSON.parse(text)
           receipt.document = `${receiptName(entry)}.json`
-          atomicWrite(join(root, 'hub', 'documents', receipt.document), bytes)
+          const documentPath = join(root, 'hub', 'documents', receipt.document)
+          try { lstatSync(documentPath); throw invalid('A file already exists at the Hub document path. Review or remove it before installing.') } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+          atomicWrite(documentPath, bytes)
         } else {
           const payload = JSON.parse(text)
           const previous = new Set(registry.list(root).map((item) => item.id))
@@ -232,6 +270,84 @@ export class Hub {
     } finally { this.installing = false; releaseData?.(); releaseState() }
   }
 
+  async uninstall(id: string, version: string): Promise<HubReceipt> {
+    const root = this.harness.env.root
+    const releaseState = acquire(join(this.harness.stateDir, 'hub', 'install.lock'))
+    this.installing = true
+    let releaseData: (() => void) | null = null
+    try {
+      releaseData = acquire(join(root, 'hub', 'install.lock'))
+      const records = this.receipts()
+      const receipt = records.find((item) => item.entry.id === id && item.entry.version === version)
+      if (!receipt) throw invalid('This Hub installation receipt no longer exists.')
+      const staged = mkdtempSync(join(root, 'hub', '.uninstall-'))
+      const moves: Array<{ source: string; staged: string }> = []
+      let choicesBefore: ReturnType<typeof attachments.load> | null = null
+      let committed = false
+      let rollbackComplete = true
+      try {
+        const ownedPaths: string[] = []
+        if (receipt.document) {
+          if (receipt.entry.delivery.kind !== 'document' || receipt.document !== `${receiptName(receipt.entry)}.json`) throw invalid('The Hub receipt has an invalid document path.')
+          const path = join(root, 'hub', 'documents', receipt.document)
+          try {
+            const stat = lstatSync(path)
+            if (!stat.isFile()) throw invalid('The receipt-owned document path is not a regular file; it was left untouched.')
+            ownedPaths.push(path)
+          } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+        }
+        if (receipt.entry.delivery.kind === 'registry') {
+          const expectedKind = receipt.entry.delivery.registryKind
+          for (const id of receipt.resourceIds) {
+            if (!/^(skills|prompts|rules)\/[a-z0-9-]{1,64}$/.test(id)) throw invalid('The Hub receipt contains an invalid registry resource path.')
+            const [kind, name] = id.split('/')
+            if (kind !== expectedKind) throw invalid('The Hub receipt contains a resource outside its registry kind.')
+            const path = join(root, 'registry', kind, kind === 'skills' ? name : `${name}.md`)
+            try { lstatSync(path); ownedPaths.push(path) } catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error }
+          }
+          choicesBefore = attachments.load(root)
+          const choices = structuredClone(choicesBefore)
+          const owned = new Set(receipt.resourceIds)
+          for (const scope of [choices.global, ...Object.values(choices.agents), ...Object.values(choices.projects)]) {
+            scope.on = scope.on.filter((value) => !owned.has(value))
+            scope.off = scope.off.filter((value) => !owned.has(value))
+          }
+          for (let index = 0; index < ownedPaths.length; index += 1) {
+            const source = ownedPaths[index]
+            const destination = join(staged, String(index))
+            renameSync(source, destination)
+            moves.push({ source, staged: destination })
+          }
+          attachments.save(root, choices)
+        } else {
+          for (let index = 0; index < ownedPaths.length; index += 1) {
+            const source = ownedPaths[index]
+            const destination = join(staged, String(index))
+            renameSync(source, destination)
+            moves.push({ source, staged: destination })
+          }
+        }
+        if (receipt.entry.delivery.kind === 'pi-package') for (const pluginId of receipt.resourceIds) await packages.remove(this.harness, { pluginId })
+        writeJson(join(root, 'hub', 'installed.json'), records.filter((item) => item !== receipt))
+        committed = true
+        try { rmSync(staged, { recursive: true, force: true }) } catch { /* The receipt is removed; leave the staged copy for disk recovery. */ }
+        this.cachedPayload = this.cachedPayload?.key === `${id}@${version}` ? null : this.cachedPayload
+        this.harness.bus.emit({ type: 'hub.changed' })
+        this.harness.bus.emit({ type: 'plugins.changed' })
+        return receipt
+      } catch (error) {
+        if (!committed) {
+          if (choicesBefore) try { attachments.save(root, choicesBefore) } catch { /* Preserve the original failure and restore the owned files below. */ }
+          for (const move of moves.reverse()) {
+            try { lstatSync(move.staged); renameSync(move.staged, move.source) } catch { rollbackComplete = false }
+          }
+          if (rollbackComplete) try { rmSync(staged, { recursive: true, force: true }) } catch { /* Keep the staging directory for recovery. */ }
+        }
+        throw error
+      }
+    } finally { this.installing = false; releaseData?.(); releaseState() }
+  }
+
   readDocument(id: string, version: string): { entry: HubEntry; content: string } {
     const receipt = this.receipts().find((item) => item.entry.id === id && item.entry.version === version)
     if (!receipt?.document || receipt.document !== `${receiptName(receipt.entry)}.json`) throw invalid('Install this document before opening it.')

package/src/hub/schema.ts

@@ -2,6 +2,7 @@ import { z } from 'zod'
 
 export const HUB_CATALOG_URL = 'https://raw.githubusercontent.com/tanntnny/xingular-hub/main/catalog.json'
 export const HUB_MAX_BYTES = 16 * 1024 * 1024
+export const HUB_PREVIEW_PAGE_BYTES = 16 * 1024
 
 const httpsUrl = z.string().max(2000).url().refine((value) => {
   const url = new URL(value)
@@ -53,7 +54,17 @@ export const hubReceiptSchema = z.object({
   entry: hubEntrySchema,
   installedAt: z.string(),
   resourceIds: z.array(z.string()),
-  document: z.string().nullable()
+  document: z.string().nullable(),
+  state: z.enum(['installed', 'changed', 'incomplete']).optional()
+}).strict()
+
+export const hubPreviewPageSchema = z.object({
+  entry: hubEntrySchema,
+  content: z.string(),
+  offset: z.number().int().nonnegative(),
+  nextOffset: z.number().int().nonnegative(),
+  totalBytes: z.number().int().nonnegative(),
+  done: z.boolean()
 }).strict()
 
 export const hubOverviewSchema = z.object({
@@ -69,6 +80,7 @@ export const hubOverviewSchema = z.object({
 export type HubEntry = z.infer<typeof hubEntrySchema>
 export type HubCatalog = z.infer<typeof hubCatalogSchema>
 export type HubReceipt = z.infer<typeof hubReceiptSchema>
+export type HubPreviewPage = z.infer<typeof hubPreviewPageSchema>
 export type HubOverview = z.infer<typeof hubOverviewSchema>
 
 export function meetsMinimum(actual: string, minimum: string): boolean {

package/src/server/methods.ts

@@ -83,6 +83,8 @@ export function methods(harness: Harness): Record<string, Handler> {
     'hub.list': (params: Params) => harness.hub.list(params.refresh === true),
     'hub.get': (params: Params) => harness.hub.get(text(params, 'id'), text(params, 'version'), params.preview === true),
     'hub.install': (params: Params) => harness.hub.install(text(params, 'id'), text(params, 'version')),
+    'hub.preview': (params: Params) => harness.hub.preview(text(params, 'id'), text(params, 'version'), typeof params.offset === 'number' ? params.offset : 0),
+    'hub.uninstall': (params: Params) => harness.hub.uninstall(text(params, 'id'), text(params, 'version')),
     'hub.readDocument': (params: Params) => harness.hub.readDocument(text(params, 'id'), text(params, 'version')),
 
     // ---- Accounts --------------------------------------------------------------------------------

package/src/sessions/planMode.test.ts

@@ -0,0 +1,40 @@
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+import { CONTEXT_MESSAGE_TYPE, CONTEXT_SNAPSHOT_KEY } from '../prompt/compile'
+import { PLAN_INSTRUCTIONS, PLAN_SECTION_ID, planModeTools, planRefusal, planSection } from './planMode'
+
+function history(sectionIds: string[]): string {
+  const file = join(mkdtempSync(join(tmpdir(), 'plan-history-')), 'session.jsonl')
+  const snapshot = sectionIds.map((id) => ({ id, title: id, body: 'x', sources: [], budget: 100, size: 1, cut: false }))
+  writeFileSync(file, [
+    JSON.stringify({ type: 'session', id: 'session' }),
+    JSON.stringify({ type: 'custom_message', id: 'c1', parentId: null, customType: CONTEXT_MESSAGE_TYPE, details: { [CONTEXT_SNAPSHOT_KEY]: snapshot } })
+  ].join('\n'))
+  return file
+}
+
+describe('plan mode', () => {
+  it('keeps read-only inspection, questions and recall, plus provider tools marked read-only', () => {
+    const normal = ['read', 'bash', 'edit', 'write', 'grep', 'ask_user', 'wiki_search', 'memory_append', 'spawn_subagent', 'files_read', 'files_write', 'skill_load']
+    expect(planModeTools(normal, ['files_read'])).toEqual(['read', 'grep', 'ask_user', 'wiki_search', 'files_read', 'skill_load'])
+  })
+
+  it('refuses changes, commands, memory writes and delegation with a reason the model can act on', () => {
+    const readOnly = new Set(['files_read'])
+    for (const tool of ['read', 'grep', 'wiki_read', 'files_read', 'ask_user']) expect(planRefusal(tool, readOnly), tool).toBeNull()
+    for (const tool of ['bash', 'write', 'edit', 'memory_append', 'wiki_propose', 'spawn_subagent', 'mcp_call_tool', 'files_write']) {
+      expect(planRefusal(tool, readOnly), tool).toContain('Plan mode is read-only')
+    }
+  })
+
+  it('adds its instructions while on, withdraws them once after, and is absent otherwise', () => {
+    expect(planSection(true, null)).toMatchObject({ id: PLAN_SECTION_ID, body: PLAN_INSTRUCTIONS, dynamic: true })
+    expect(PLAN_INSTRUCTIONS).toContain('<proposed_plan>')
+    expect(planSection(false, null)).toBeNull()
+    expect(planSection(false, history(['blocks']))).toBeNull()
+    expect(planSection(false, history(['blocks', PLAN_SECTION_ID]))).toMatchObject({ id: PLAN_SECTION_ID, body: null, dynamic: true })
+  })
+})