@canonical/pragma-cli 0.29.0 → 0.31.0

package/README.md

@@ -22,7 +22,7 @@ See [docs/getting-started.md](docs/getting-started.md) for a full walkthrough.
 
 ## CLI Commands
 
-pragma organizes commands into 14 domains. Every command supports three output modes: plain text (default), `--llm` (condensed Markdown), and `--format json` (structured JSON).
+pragma organizes commands into 17 domains — counting every directory under `src/domains/` except `shared/`, which holds cross-domain infrastructure rather than commands. The day-to-day domains are documented below; two are specialised and not covered here: `graphql` (compile TTL ontologies into GraphQL schema artifacts) and `trace` (query access tracing). Every command supports three output modes: plain text (default), `--llm` (condensed Markdown), and `--format json` (structured JSON).
 
 ### Block
 
@@ -36,7 +36,7 @@ pragma organizes commands into 14 domains. Every command supports three output m
 | Command | Description |
 |---------|-------------|
 | `pragma standard list` | List all code standards |
-| `pragma standard lookup <name>` | Show standard with do/don't examples |
+| `pragma standard lookup <name>` | Show standard details (`--detailed` adds do/don't examples) |
 | `pragma standard categories` | List standard categories with counts |
 
 ### Modifier
@@ -46,13 +46,17 @@ pragma organizes commands into 14 domains. Every command supports three output m
 | `pragma modifier list` | List all modifier families |
 | `pragma modifier lookup <name>` | Show modifier family with values |
 
-### Token
+### Tokens
 
 | Command | Description |
 |---------|-------------|
-| `pragma token list` | List all design tokens |
-| `pragma token lookup <name>` | Show token with theme values |
-| `pragma token add-config` | Add Terrazzo config for token build |
+| `pragma tokens add-config` | Add Terrazzo config for token build |
+
+> **Note:** The token *read* commands (`token list`, `token lookup`, `token sample`)
+> are currently disabled behind a feature flag
+> (`src/domains/token/featureFlag.ts`) because the published design-system
+> data does not yet contain token instances. They will return once token
+> data ships.
 
 ### Tier
 
@@ -65,7 +69,10 @@ pragma organizes commands into 14 domains. Every command supports three output m
 | Command | Description |
 |---------|-------------|
 | `pragma ontology list` | List loaded ontology namespaces |
-| `pragma ontology show <prefix>` | Show classes and properties for a namespace |
+| `pragma ontology show <prefix>` | Show the TBox: name, metadata, class hierarchy tree with instance counts and relations |
+| `pragma ontology show <prefix> --properties` | Also show datatype properties (attributes) |
+| `pragma ontology show <prefix> --full-uris` | Show full URIs instead of compact prefixed IRIs |
+| `pragma ontology show <prefix> --class <Class>` | Deep-dive into one class: super chain, direct/inherited properties, reverse references, sample instances, and ready-to-run follow-up queries |
 
 ### Graph
 
@@ -87,6 +94,7 @@ pragma organizes commands into 14 domains. Every command supports three output m
 | Command | Description |
 |---------|-------------|
 | `pragma skill list` | List discovered agent skills from installed packages |
+| `pragma skill lookup <name...>` | Show full SKILL.md instructions for skills by name |
 
 ### LLM
 
@@ -96,15 +104,16 @@ pragma organizes commands into 14 domains. Every command supports three output m
 
 ### Setup
 
-All setup commands support `--dry-run`, `--yes`, and `--undo`.
+All setup commands support `--dry-run`; `--yes` and `--undo` are supported
+where shown below.
 
 | Command | Description |
 |---------|-------------|
-| `pragma setup all` | Run all setup steps (MCP + completions + skills) |
-| `pragma setup mcp` | Configure pragma MCP server for AI harnesses |
-| `pragma setup completions` | Install shell completions (bash/zsh/fish) |
-| `pragma setup skills` | Symlink agent skills into harness config |
-| `pragma setup lsp` | Configure LSP integration |
+| `pragma setup` | Run all setup steps (completions + LSP + MCP); supports `--yes`, `--undo` |
+| `pragma setup mcp` | Configure pragma MCP server for AI harnesses; supports `--yes`, `--undo` |
+| `pragma setup completions` | Install shell completions (bash/zsh/fish); supports `--undo` |
+| `pragma setup skills` | Symlink agent skills into harness config; supports `--yes` |
+| `pragma setup lsp` | Install the Terrazzo LSP VS Code extension; supports `--undo` |
 
 ### Create
 
@@ -112,8 +121,9 @@ Create commands scaffold new code using summon generators. They support `--undo`
 
 | Command | Description |
 |---------|-------------|
-| `pragma create component <name>` | Scaffold a new design system component |
-| `pragma create package <name>` | Scaffold a new monorepo package |
+| `pragma create component <framework> [path]` | Scaffold a new design system component |
+| `pragma create package` | Scaffold a new monorepo package (`--name`, `--type`, …) |
+| `pragma create application [path]` | Scaffold a complete React application with SSR and routing |
 
 ### Doctor
 
@@ -125,8 +135,19 @@ Create commands scaffold new code using summon generators. They support `--undo`
 
 | Command | Description |
 |---------|-------------|
-| `pragma info` | Show pragma version, store summary, installed packages |
-| `pragma info upgrade` | Check for newer pragma versions on the registry |
+| `pragma info` | Show pragma version, config, update status, and store summary |
+
+### Upgrade
+
+| Command | Description |
+|---------|-------------|
+| `pragma upgrade` | Upgrade the pragma CLI to the latest version (`--dry-run` to check only) |
+
+### Refs
+
+| Command | Description |
+|---------|-------------|
+| `pragma update-refs` | Fetch or clone git-referenced semantic packages into the local cache (needed before `skill list` can discover skills) |
 
 ## Global Flags
 
@@ -143,7 +164,7 @@ Setup and create commands support `--undo` to reverse previous operations. The u
 ```bash
 pragma setup mcp --undo             # Remove MCP configuration
 pragma setup completions --undo     # Remove shell completions
-pragma create component Foo --undo  # Remove scaffolded component files
+pragma create component react src/lib/Foo --undo  # Remove scaffolded component files
 ```
 
 ## MCP Integration
@@ -173,27 +194,27 @@ Or add manually to your `.mcp.json`:
 }
 ```
 
-### MCP Tools (29)
+### MCP Tools (28)
 
 All tools return a consistent envelope: `{ ok: true, data, meta }` for success, `{ ok: true, condensed: true, text, tokens }` for condensed mode, or `{ ok: false, error }` with structured recovery on failure.
 
-#### Read Tools (20)
+#### Read Tools (18)
+
+Lookup tools accept a `names` array, so several entities can be fetched in
+one call (partial results are returned alongside per-name errors).
 
 | Tool | Description |
 |------|-------------|
 | `block_list` | List blocks with optional tier filtering and disclosure levels |
 | `block_lookup` | Look up detailed block info (anatomy, modifiers, tokens, standards) |
-| `block_batch_lookup` | Look up multiple blocks by name in a single call |
+| `block_sample` | Return random complete block instances for shape discovery |
 | `standard_list` | List code standards with optional category/search filtering |
 | `standard_lookup` | Look up standard with do/don't code examples |
-| `standard_batch_lookup` | Look up multiple standards by name in a single call |
 | `standard_categories` | List standard categories with counts |
+| `standard_sample` | Return random complete standard instances for shape discovery |
 | `modifier_list` | List modifier families |
 | `modifier_lookup` | Look up modifier family with values |
-| `modifier_batch_lookup` | Look up multiple modifier families by name in a single call |
-| `token_list` | List design tokens with optional category filtering |
-| `token_lookup` | Look up token with theme-resolved values |
-| `token_batch_lookup` | Look up multiple tokens by name in a single call |
+| `modifier_sample` | Return random complete modifier instances for shape discovery |
 | `tier_list` | List all tiers in the hierarchy |
 | `config_show` | Show current tier and channel configuration |
 | `ontology_list` | List loaded ontology namespaces with class/property counts |
@@ -201,8 +222,12 @@ All tools return a consistent envelope: `{ ok: true, data, meta }` for success,
 | `graph_query` | Execute raw SPARQL against the ke store |
 | `graph_inspect` | Inspect all triples for a URI |
 | `skill_list` | List discovered agent skills |
+| `skill_lookup` | Get full SKILL.md content for skills by name |
 
-#### Write Tools (5)
+`token_list`, `token_lookup`, and `token_sample` are feature-flagged off
+until token data ships (see the Tokens note above).
+
+#### Write Tools (6)
 
 | Tool | Description |
 |------|-------------|
@@ -211,6 +236,7 @@ All tools return a consistent envelope: `{ ok: true, data, meta }` for success,
 | `tokens_add_config` | Add Terrazzo token build configuration |
 | `create_component` | Scaffold a new design system component |
 | `create_package` | Scaffold a new monorepo package |
+| `create_application` | Scaffold a complete React application |
 
 #### Orientation Tools (2)
 
@@ -280,12 +306,12 @@ Error responses include a `recovery` object that tells agents what tool to call
 
 ### Batch Results
 
-List tools that accept a `names` filter return partial results — valid items in `results`, failures in `errors`:
+Lookup tools accept a `names` array and return partial results — valid items in `results`, failures in `errors`:
 
 ```json
 {
   "results": [{ "name": "Button", ... }],
-  "errors": [{ "name": "Buton", "code": "ENTITY_NOT_FOUND", "message": "..." }]
+  "errors": [{ "query": "Buton", "code": "ENTITY_NOT_FOUND", "message": "...", "suggestions": ["Button"] }]
 }
 ```
 
@@ -295,27 +321,82 @@ Every subject URI in the ke graph is exposed as a discoverable MCP resource via
 
 ## Configuration
 
-Create a `pragma.config.toml` in your project root:
+Configuration is layered: built-in defaults, then the global file at
+`$XDG_CONFIG_HOME/pragma/config.json` (default `~/.config/pragma/config.json`),
+then the nearest `pragma.config.json` at or above the current directory —
+each field won by the most specific layer that sets it. Install pragma
+globally, configure once, and override per project:
 
-```toml
-tier = "apps/lxd"
-channel = "normal"    # normal | experimental | prerelease
+```json
+{
+  "tier": "apps/lxd",
+  "channel": "normal"
+}
+```
+
+`pragma config tier|channel|framework|trace` writes to the nearest existing
+project file, or to the global file when no project is configured; pass
+`--local` or `--global` to pick the layer explicitly. Every write echoes the
+file it wrote, and `pragma config show` reports which layer supplied each
+value.
+
+### Custom read stories (experimental)
+
+A config (or a semantic package, via `stories/*.json`) can declare
+declarative read stories — any ontology loaded through `packages` gets
+`pragma <noun> list` / `<noun> lookup` on both the CLI and MCP:
+
+```json
+{
+  "prefixes": { "ex": "http://example.org/recipes/" },
+  "packages": [{ "name": "my-recipes", "source": "file:///data/recipes" }],
+  "stories": [
+    {
+      "noun": "recipe",
+      "description": "List recipes",
+      "list": {
+        "query": "SELECT ?uri ?name ?category WHERE { ?uri a ex:Recipe ; ex:name ?name ; ex:category ?category } ORDER BY ?name",
+        "columns": [{ "field": "name" }, { "field": "category" }],
+        "filters": [
+          { "param": "category", "variable": "category", "values": ["breakfast", "soup"] }
+        ]
+      },
+      "lookup": {
+        "type": "ex:Recipe",
+        "by": "ex:name",
+        "fields": [{ "name": "category", "property": "ex:category" }],
+        "sections": [{ "name": "instructions", "property": "ex:instructions" }]
+      }
+    }
+  ]
+}
 ```
 
-When no config file is present, pragma defaults to no tier and `normal` channel.
+The lookup query is generated (user input is escaped, never interpolated by
+the pack), the store stays read-only, and config-declared stories override
+package-shipped ones on noun collisions. Declared `filters` become
+`pragma recipe list --category soup` on the CLI and an enum parameter on the
+MCP tool; they are row predicates applied after the query runs, so filter
+input can never inject SPARQL and the query's ordering is preserved. The
+format is experimental and may change.
 
 ## Error Handling
 
-Errors follow a three-part structure: message, context (suggestions or valid options), and recovery hint.
+Lookup errors report each failed name with typo suggestions:
 
 ```
-Error: block "Buton" not found.
+**Errors:**
+- Buton: block "Buton" not found.
+  Did you mean: Button?
+```
 
-Did you mean?
-  - Button
-  - ButtonGroup
+Other errors carry a code and, where available, a recovery hint:
 
-Run `pragma block list`
+```
+## Error: EMPTY_RESULTS
+No standards found.
+Filters: category=nope
+Recovery: `pragma standard list`
 ```
 
 With `--format json`, errors are returned as structured JSON with error code, suggestions, and recovery. With `--llm`, errors are rendered as Markdown.
@@ -336,7 +417,7 @@ With `--format json`, errors are returned as structured JSON with error code, su
 
 pragma is structured as a domain-driven application using the federation pattern from `@canonical/cli-core`:
 
-1. **Domains** — 14 domain modules (block, standard, modifier, token, tier, ontology, graph, config, skill, llm, setup, create, doctor, info), each exporting `CommandDefinition[]`
+1. **Domains** — 17 domain modules (block, config, create, doctor, graph, graphql, info, llm, modifier, ontology, refs, setup, skill, standard, tier, token, trace — every directory under `src/domains/` except the `shared/` infrastructure folder), each contributing `CommandDefinition`s
 2. **Operations** — data retrieval functions that query the ke triple store via SPARQL
 3. **Formatters** — three-mode output adapters (plain/llm/json) for each operation
 4. **Commands** — thin wiring layer connecting Commander.js parameters to operations + formatters
@@ -364,13 +445,13 @@ bun build --compile --minify src/bin.ts --outfile dist/pragma
 
 ## Dependencies
 
-- [`@canonical/ke`](../runtime/ke/) — triple store runtime (Oxigraph WASM)
+- [`@canonical/ke`](../../runtime/ke/) — triple store runtime (Oxigraph WASM)
 - [`@canonical/cli-core`](../core/) — shared CLI machinery (Commander.js registration, help formatting)
-- [`@canonical/task`](../../lib/task/) — reversible task trees for setup/create with undo support
-- [`@canonical/harnesses`](../../lib/harnesses/) — AI harness detection (Claude Code, Cursor, Windsurf)
-- [`@canonical/summon-core`](../../lib/summon-core/) — code generation runtime
-- [`@canonical/summon-component`](../../lib/summon-component/) — component generator
-- [`@canonical/summon-package`](../../lib/summon-package/) — package generator
+- [`@canonical/task`](../../runtime/task/) — reversible task trees for setup/create with undo support
+- [`@canonical/harnesses`](../../runtime/harnesses/) — AI harness detection (Claude Code, Cursor, Windsurf)
+- [`@canonical/summon-core`](../../summon/core/) — code generation runtime
+- [`@canonical/summon-component`](../../summon/component/) — component generator
+- [`@canonical/summon-package`](../../summon/package/) — package generator
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/pragma-cli",
   "description": "CLI and MCP server for Canonical's design system.",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -60,9 +60,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.29.0",
-    "@canonical/typescript-config": "^0.29.0",
-    "@canonical/webarchitect": "^0.29.0",
+    "@canonical/biome-config": "^0.31.0",
+    "@canonical/typescript-config": "^0.31.0",
+    "@canonical/webarchitect": "^0.31.0",
     "@types/bun": "^1.3.10",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
@@ -72,16 +72,18 @@
   },
   "dependencies": {
     "@canonical/anatomy-dsl": "^0.2.2",
-    "@canonical/cli-core": "^0.29.0",
+    "@canonical/cli-core": "^0.31.0",
     "@canonical/code-standards": "^0.1.2",
     "@canonical/design-system": "^0.1.2",
-    "@canonical/harnesses": "^0.29.0",
-    "@canonical/ke": "^0.29.0",
-    "@canonical/ke-graphql": "^0.29.0",
-    "@canonical/summon-component": "^0.29.0",
-    "@canonical/summon-core": "^0.29.0",
-    "@canonical/summon-package": "^0.29.0",
-    "@canonical/task": "^0.29.0",
+    "@canonical/harnesses": "^0.31.0",
+    "@canonical/ke": "^0.31.0",
+    "@canonical/ke-graphql": "^0.31.0",
+    "@canonical/summon": "^0.31.0",
+    "@canonical/summon-application": "^0.31.0",
+    "@canonical/summon-component": "^0.31.0",
+    "@canonical/summon-core": "^0.31.0",
+    "@canonical/summon-package": "^0.31.0",
+    "@canonical/task": "^0.31.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
@@ -90,5 +92,5 @@
     "react": "^19.2.4",
     "zod": "^3.25.0"
   },
-  "gitHead": "7c96ac31ff350a3bd099168d249680a8f9632568"
+  "gitHead": "d4a67ebe42e62b8cf3de77f42f537309ca88d672"
 }

package/src/completions/constants.ts

@@ -16,3 +16,10 @@ export const POLL_INTERVAL_MS = 50;
 
 /** Maximum time to wait for a spawned server to become ready. */
 export const SPAWN_TIMEOUT_MS = 5_000;
+
+/**
+ * Maximum time to wait for a query response before giving up. Bounds the
+ * whole client call so a wedged or slow server can never hang the shell's
+ * tab-completion — the query resolves to no candidates instead.
+ */
+export const QUERY_TIMEOUT_MS = 3_000;

package/src/completions/handleQuery.test.ts

@@ -37,6 +37,16 @@ function makeTree(): CompletionTree {
             );
           },
         },
+        {
+          name: "detailed",
+          description: "Show full detail",
+          type: "boolean",
+        },
+        {
+          name: "anatomyOnly",
+          description: "Show anatomy only",
+          type: "boolean",
+        },
       ],
       execute: async () => createExitResult(0),
     },
@@ -90,4 +100,26 @@ describe("handleQuery", () => {
     const result = await handleQuery("block list something", makeTree(), ctx);
     expect(result).toBe("");
   });
+
+  it("strips the leading program name shells forward", async () => {
+    // Every generated shell script forwards the full command line, so the
+    // program name arrives as the first word.
+    const result = await handleQuery("pragma blo", makeTree(), ctx);
+    expect(result).toBe("block");
+  });
+
+  it("lists nouns when only the program name is present", async () => {
+    const result = await handleQuery("pragma", makeTree(), ctx);
+    expect(result).toBe("block\nstandard");
+  });
+
+  it("completes verb flags when the word starts with a dash", async () => {
+    const result = await handleQuery("block get --", makeTree(), ctx);
+    expect(result).toBe("--anatomy-only\n--detailed");
+  });
+
+  it("filters verb flags by the dash-prefixed partial", async () => {
+    const result = await handleQuery("block get --d", makeTree(), ctx);
+    expect(result).toBe("--detailed");
+  });
 });

package/src/completions/handleQuery.ts

@@ -1,5 +1,24 @@
 import type { CommandContext, CompletionTree } from "@canonical/cli-core";
 import { resolveCompletion } from "@canonical/cli-core";
+import { PROGRAM_NAME } from "../constants.js";
+
+/**
+ * Split a raw shell partial into completion words, dropping the leading
+ * program name.
+ *
+ * Every generated shell script forwards the full command line — including the
+ * `pragma` program name as the first word — so without this strip the resolver
+ * mistakes `pragma` for the noun and returns no candidates. An empty partial
+ * (first-Tab, no word yet) resolves to a single empty word so noun completion
+ * still fires.
+ *
+ * @param partial - The raw partial input string from the shell.
+ * @returns The completion words with any leading program name removed.
+ */
+function splitCompletionWords(partial: string): string[] {
+  const words = partial.length === 0 ? [""] : partial.split(" ");
+  return words.at(0) === PROGRAM_NAME ? words.slice(1) : words;
+}
 
 /**
  * Resolve a partial CLI input against a completion tree and return
@@ -22,7 +41,7 @@ export default async function handleQuery(
   tree: CompletionTree,
   ctx: CommandContext,
 ): Promise<string> {
-  const words = partial.length === 0 ? [""] : partial.split(" ");
+  const words = splitCompletionWords(partial);
   const result = resolveCompletion(tree, words);
   if (!result.completer) return "";
   const candidates = await result.completer(result.partial, ctx);

package/src/completions/queryCompletions.test.ts

@@ -26,12 +26,15 @@ vi.mock("./waitForSocket.js", () => ({
 
 describe("queryCompletions", () => {
   let stdoutSpy: ReturnType<typeof vi.spyOn>;
+  const unrefMock = vi.fn();
 
   beforeEach(() => {
     vi.clearAllMocks();
     stdoutSpy = vi
       .spyOn(process.stdout, "write")
       .mockImplementation(() => true);
+    // The spawned server handle is unref'd so the client can exit immediately.
+    spawnMock.mockReturnValue({ unref: unrefMock });
     vi.stubGlobal("Bun", { spawn: spawnMock });
   });
 
@@ -67,6 +70,8 @@ describe("queryCompletions", () => {
 
     expect(unlinkSyncMock).toHaveBeenCalledWith("/tmp/pragma-completions.sock");
     expect(spawnMock).toHaveBeenCalledTimes(1);
+    // The server handle is detached so the client is not held alive by it.
+    expect(unrefMock).toHaveBeenCalledTimes(1);
     expect(waitForSocketMock).toHaveBeenCalled();
     expect(querySocketMock).toHaveBeenCalledTimes(2);
     expect(stdoutSpy).toHaveBeenCalledWith("block\n");

package/src/completions/queryCompletions.ts

@@ -38,12 +38,26 @@ export default async function queryCompletions(partial: string): Promise<void> {
     }
   }
 
-  // No running server — spawn one.
-  const binPath = resolve(import.meta.dirname, "../bin.ts");
-  Bun.spawn(["bun", "run", binPath, "_completions-server"], {
+  // No running server — spawn one. Re-invoke THIS executable so completion
+  // works from the shipped binary as well as from source: when the entry file
+  // exists on disk (source run) spawn `bun run bin.ts`; otherwise (a compiled
+  // standalone binary, where bin.ts is embedded, not a file) spawn the binary
+  // itself. The old code always spawned `bun run <dir>/../bin.ts`, which does
+  // not exist inside a compiled binary, so its server never started and every
+  // completion silently returned nothing.
+  const entryPath = resolve(import.meta.dirname, "../bin.ts");
+  const spawnArgs = existsSync(entryPath)
+    ? [process.execPath, "run", entryPath, "_completions-server"]
+    : [process.execPath, "_completions-server"];
+  const server = Bun.spawn(spawnArgs, {
     stdio: ["ignore", "ignore", "ignore"],
     cwd: process.cwd(),
   });
+  // Detach the server from the client's lifecycle. Without this the child keeps
+  // the client's event loop alive until the server's idle timeout (~10s) fires,
+  // so every tab-completion appears to hang for ~10s and the client tears the
+  // server down on exit — defeating the persistent-server fast path entirely.
+  server.unref();
 
   const ready = await waitForSocket(socketPath, SPAWN_TIMEOUT_MS);
   if (!ready) {

package/src/completions/querySocket.test.ts

@@ -67,4 +67,35 @@ describe("querySocket", () => {
       "connect failed",
     );
   });
+
+  it("times out and closes the socket when the server never replies", async () => {
+    vi.useFakeTimers();
+    const end = vi.fn();
+
+    connectMock.mockImplementation(
+      (options: {
+        socket: {
+          open: (socket: {
+            write: () => void;
+            flush: () => void;
+            end: () => void;
+          }) => void;
+        };
+      }) => {
+        // Open but never send data or close — simulate a wedged server.
+        options.socket.open({ write: () => {}, flush: () => {}, end });
+        return Promise.resolve({});
+      },
+    );
+
+    try {
+      const promise = querySocket("/tmp/pragma.sock", "blo");
+      const assertion = expect(promise).rejects.toThrow(/timed out/);
+      await vi.advanceTimersByTimeAsync(5000);
+      await assertion;
+      expect(end).toHaveBeenCalledTimes(1);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });

package/src/completions/querySocket.ts

@@ -1,10 +1,14 @@
+import { QUERY_TIMEOUT_MS } from "./constants.js";
+
 /**
  * Connect to a Unix domain socket, send a partial string, and
  * collect the response.
  *
- * Opens a Bun TCP connection to the socket, writes the partial
- * terminated by a newline, and accumulates response chunks until
- * the server closes the connection.
+ * Opens a Bun connection to the socket, writes the partial terminated by a
+ * newline, and accumulates response chunks until the server closes the
+ * connection. The whole exchange is bounded by {@link QUERY_TIMEOUT_MS}: if a
+ * wedged or slow server never replies, the promise rejects rather than hanging
+ * the shell's tab-completion indefinitely.
  *
  * @param socketPath - Absolute path to the Unix domain socket.
  * @param partial - The partial CLI input to send for completion.
@@ -18,10 +22,31 @@ export default function querySocket(
 ): Promise<string> {
   return new Promise<string>((resolve, reject) => {
     const chunks: Buffer[] = [];
+    let settled = false;
+    let openSocket: { end: () => void } | undefined;
+
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      // Close the connection so a hung server does not leak an open socket.
+      openSocket?.end();
+      reject(
+        new Error(`Completion query timed out after ${QUERY_TIMEOUT_MS}ms`),
+      );
+    }, QUERY_TIMEOUT_MS);
+
+    const settle = (run: () => void): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      run();
+    };
+
     Bun.connect({
       unix: socketPath,
       socket: {
         open(socket) {
+          openSocket = socket;
           socket.write(`${partial}\n`);
           socket.flush();
         },
@@ -29,16 +54,18 @@ export default function querySocket(
           chunks.push(Buffer.from(data));
         },
         close() {
-          resolve(
-            Buffer.concat(chunks)
-              .toString("utf-8")
-              .replace(/\r?\n$/, ""),
+          settle(() =>
+            resolve(
+              Buffer.concat(chunks)
+                .toString("utf-8")
+                .replace(/\r?\n$/, ""),
+            ),
           );
         },
         error(_socket, err) {
-          reject(err);
+          settle(() => reject(err));
         },
       },
-    }).catch(reject);
+    }).catch((err) => settle(() => reject(err)));
   });
 }