pi-weave 0.1.6 → 0.1.7

package/README.md

@@ -50,21 +50,18 @@ attestation ([Publish workflow](.github/workflows/publish.yml)).
 | Command | `/weave-scan` | build/refresh the repository index (light) |
 | Command | `/weave-scan deep` | light index + model-summarized sidecars (opt-in, incremental) |
 | Command | `/weave-scan-cancel` | stop an in-flight `/weave-scan deep` run |
-| Command | `/weave-view` | open the local graph viewer in your browser |
-| Command | `/weave-view tui` | explore the same graph in-terminal (keyboard) |
+| Command | `/weave-view` | explore the local knowledge graph in-terminal (keyboard) |
 | Skill | `weave-notepad` | how the agent should take good notes |
 | Skill | `weave-explore` | how the agent should explore repositories |
 
-**`/weave-view`** starts a loopback-only server (`127.0.0.1`, random port) and opens an interactive graph of your knowledge space: vault
-notes with trust provenance (solid = human, dashed = agent, dimmed = generated), wiki-link edges between notes, and the repository's
-structure anchored to git state. It reads disk live on every refresh — never a stale cache. Zoom/scroll, drag to pan, click nodes to expand;
-notes open in a rendered markdown side panel.
-
-**`/weave-view tui`** explores the same knowledge graph in the terminal: an expandable containment tree (Explore), a 1-hop neighborhood
+**`/weave-view`** explores the knowledge graph in the terminal: an expandable containment tree (Explore), a 1-hop neighborhood
 (Focus), a selected-node detail view with note/`.okf` bodies, and a staleness + link health surface — all keyboard-driven and read-only.
-Same data as the browser viewer (the `GraphModel` assembled from vault + repo index); a pure, harness-free view-model
+It reads disk live (never a stale cache) over the `GraphModel` assembled from the vault + repository index; a pure, harness-free view-model
 (`src/pi/viewer/tui/model.ts`) backs the `WeaveExplorer` component. See `docs/weave-view-tui-design.md`.
 
+> The earlier in-browser graph viewer (`/weave-view` in a browser) has been retired and is being rebuilt on pixi.js; until then
+> `/weave-view` opens the in-terminal explorer.
+
 On session start, pi-weave detects the repository you're in, checks whether `.okf` exists and is fresh, and says so in the status footer — a
 filled `●` marks weave as active (a deep scan spins it while running).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-weave",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "An agent-native knowledge workspace for your life and your code. Smart notepad + repository exploration, readable by humans and agents alike.",
   "type": "module",
   "sideEffects": false,

package/src/pi/index.ts

@@ -12,8 +12,6 @@ import {
 import { registerNoteTool } from "./tools/noteTool";
 import { registerRepoTool } from "./tools/repoTool";
 import { deepScanRepository, formatDeepScanResult } from "./summarize";
-import { openInBrowser } from "./viewer/browser";
-import { startViewer, type ViewerServer } from "./viewer/server";
 import { runWeaveViewTui } from "./viewer/tui/run";
 
 /**
@@ -29,9 +27,9 @@ export default function piWeave(pi: ExtensionAPI): void {
   registerNoteTool(pi);
   registerRepoTool(pi);
 
-  // Session-scoped viewer: lazy start on first /weave-view, never from the
-  // factory (extension rules); idempotent stop on session_shutdown.
-  let viewer: ViewerServer | null = null;
+  // /weave-view is the in-terminal explorer (the old browser viewer was
+  // retired for a pixi.js rewrite); it holds no session resources, so there
+  // is no per-session lifecycle to tear down.
   let lastCtx: ExtensionContext | ExtensionCommandContext | null = null;
   let lastStatusText: string | undefined = undefined;
   let isActive = false;
@@ -60,9 +58,7 @@ export default function piWeave(pi: ExtensionAPI): void {
   }
 
   pi.on("session_shutdown", async () => {
-    const server = viewer;
-    viewer = null;
-    await server?.stop();
+    // The TUI explorer owns no session-scoped resources; nothing to stop.
   });
 
   pi.on("agent_start", async (_event, ctx) => {
@@ -101,20 +97,14 @@ export default function piWeave(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("weave-view", {
-    description: "Open the local knowledge-graph viewer in your browser (vault + repository); '/weave-view tui' explores in-terminal",
+    description: "Open the in-terminal knowledge-graph explorer (vault + repository); reads from disk live",
     handler: async (args, ctx) => {
       const arg = args.trim().toLowerCase();
-      if (arg === "tui") {
-        await runWeaveViewTui(ctx);
-        return;
-      }
-      if (arg !== "") {
+      if (arg !== "" && arg !== "tui") {
         ctx.ui.notify("usage: /weave-view [tui]", "warning");
         return;
       }
-      viewer ??= await startViewer({ cwd: ctx.cwd });
-      ctx.ui.notify(`pi-weave viewer: ${viewer.url} (reads from disk live; refresh the page any time)`, "info");
-      await openInBrowser(pi, ctx, viewer.url);
+      await runWeaveViewTui(ctx);
     },
   });
 

package/src/pi/viewer/tui/bodyStore.ts

@@ -0,0 +1,98 @@
+/**
+ * BodyStore — shared note/.okf body cache (weave-view-tui-v2 §6, §9.1).
+ *
+ * The v1 WeaveExplorer cached bodies in private maps. v2 lifts that cache into
+ * a per-session store so every pane (e.g. two Detail panes reading the same
+ * note) shares one fetch per node id. Behavior is identical to v1's
+ * per-explorer cache: a body load is kicked off once per id, in-flight loads
+ * are deduped, and a refresh busts the cache so the next read re-fetches.
+ *
+ * The store is harness-free (takes injected loaders + an optional
+ * onChange callback), so it is unit-tested with fake loaders exactly like
+ * v1's body tests.
+ */
+
+import type { ViewNote } from "../../../core/graph/current";
+
+/** The body loaders a BodyStore is bound to (bound to vault/cwd by run.ts). */
+export interface BodyLoaders {
+  loadNote: (slug: string) => Promise<ViewNote | null>;
+  loadOkf: (rel: string) => Promise<{ path: string; body: string } | null>;
+}
+
+export interface BodyStoreOptions {
+  loaders: BodyLoaders;
+  /** Invoked (no args) when an async load resolves so the owner can re-render. */
+  onChange?: () => void;
+}
+
+/**
+ * A cache+dedup keyed by node id. `get` never throws and never double-loads.
+ *
+ * - `null` body = the node exists but has no loadable body (or it loaded to
+ *   null); the pane renders nothing for it.
+ * - `undefined` = not yet requested (the pane shows a placeholder and asks the
+ *   store to load, mirroring v1's `bodyLinesFor`).
+ * - `isLoading(id)` = an in-flight request is outstanding (pane shows "loading").
+ */
+export class BodyStore {
+  private readonly loaders: BodyLoaders;
+  private readonly onChange: (() => void) | undefined;
+  private cache = new Map<string, string | null>();
+  private loading = new Set<string>();
+
+  constructor(opts: BodyStoreOptions) {
+    this.loaders = opts.loaders;
+    this.onChange = opts.onChange;
+  }
+
+  /** True when the id is mid-load. */
+  isLoading(id: string): boolean {
+    return this.loading.has(id);
+  }
+
+  /** Cached body for the id, or undefined when not yet requested. */
+  get(id: string): string | null | undefined {
+    return this.cache.get(id);
+  }
+
+  /** True once a body has been requested for the id (cached or failed). */
+  has(id: string): boolean {
+    return this.cache.has(id);
+  }
+
+  /**
+   * Kick off a load for `id` if not already requested/in-flight. Returns true
+   * when a load was started (so the caller can show a placeholder). The load
+   * uses `kind` (note/file) to pick the loader and `ref` (slug/rel path).
+   */
+  load(id: string, kind: "note" | "file", ref: string | undefined): boolean {
+    if (ref === undefined) return false;
+    if (this.cache.has(id) || this.loading.has(id)) return false;
+    this.loading.add(id);
+    if (kind === "note") {
+      void this.loaders
+        .loadNote(ref)
+        .then((note) => this.finish(id, note?.body ?? null))
+        .catch(() => this.finish(id, null));
+    } else {
+      void this.loaders
+        .loadOkf(ref)
+        .then((file) => this.finish(id, file?.body ?? null))
+        .catch(() => this.finish(id, null));
+    }
+    return true;
+  }
+
+  /** Drop all cached bodies and in-flight markers (the `r` refresh). */
+  clear(): void {
+    this.cache.clear();
+    this.loading.clear();
+  }
+
+  private finish(id: string, body: string | null): void {
+    this.cache.set(id, body);
+    this.loading.delete(id);
+    this.onChange?.();
+  }
+}

package/src/pi/viewer/tui/branding.ts

@@ -0,0 +1,154 @@
+/**
+ * branding.ts — weave-view TUI logo & wordmark tiers (weave-view-tui-v2 §5).
+ *
+ * Renders the brand as a small, casual in-bar mark. Three tiers, auto-selected
+ * once per session from terminal capability and cached:
+ *
+ *   1. "kitty"   — the real raster logo via pi-tui's `Image` component (a small
+ *                  ~2×2-cell favicon). The raw JPG is bundled and base64'd once.
+ *   2. "glyph"   — a tiny curated Unicode glyph derived from the logo silhouette.
+ *   3. "plain"   — `🧵` + wordmark, forced by PI_WEAVE_TUI_PLAIN.
+ *
+ * The line-art/unicode constants contain no ESC by construction (decision 1:
+ * the representation fallback is a curated constant, never generated at runtime).
+ */
+
+import { detectCapabilities, getCapabilities, Image, type Component } from "@earendil-works/pi-tui";
+import type { ThemeSlot } from "./theme";
+
+/** Logo render tier. */
+export type LogoTier = "kitty" | "glyph" | "plain";
+
+/** A tiny Unicode mark derived from the logo silhouette (decision 1 fallback). */
+export const MARK_GLYPH = "◈";
+/** Absolute last-resort mark (also the forced plain tier). */
+export const PLAIN_MARK = "🧵";
+/** The wordmark shown after the mark. */
+export const WORDMARK = "weave view";
+
+/** Env var that forces the plain tier. */
+export const PLAIN_ENV = "PI_WEAVE_TUI_PLAIN";
+
+/** MIME of the bundled raster logo asset (downscaled JPEG of the logo). */
+export const LOGO_MIME = "image/jpeg";
+
+/**
+ * Bundled downscaled raster copy of `docs/pi-weave-logo.jpg` (32×32, ~1.3 KB).
+ * Decision 1 (§15): ship a small raster copy and embed it via pi-tui's `Image`
+ * (Kitty graphics) as a small ~2×2-cell favicon in the header strip — a casual
+ * in-bar mark, not a hero splash. Stored base64 so the render path needs no
+ * fs/path resolution and the asset is trivially unit-testable.
+ */
+export const LOGO_B64 =
+  "/9j/4AAQSkZJRgABAQAASABIAAD/4QDORXhpZgAATU0AKgAAAAgABgESAAMAAAABAAEAAAEaAAUAAAABAAAAVgEbAAUAAAABAAAAXgEoAAMAAAABAAIAAAExAAIAAAAVAAAAZodpAAQAAAABAAAAfAAAAAAAAABIAAAAAQAAAEgAAAABUGl4ZWxtYXRvciBQcm8gMi4xLjMAAAAEkAQAAgAAABQAAACyoAEAAwAAAAEAAQAAoAIABAAAAAEAAAAgoAMABAAAAAEAAAAgAAAAADIwMjY6MDg6MjIgMTk6NTY6MjIA/+0AZFBob3Rvc2hvcCAzLjAAOEJJTQQEAAAAAAAsHAFaAAMbJUccAgAAAgACHAI+AAgyMDI2MDgyMhwCPwALMTk1NjIyKzAwMDA4QklNBCUAAAAAABBB7D4+CxrdyaRylkhoEmIW/8AAEQgAIAAgAwEiAAIRAQMRAf/EAB8AAAEFAQEBAQEBAAAAAAAAAAABAgMEBQYHCAkKC//EALUQAAIBAwMCBAMFBQQEAAABfQECAwAEEQUSITFBBhNRYQcicRQygZGhCCNCscEVUtHwJDNicoIJChYXGBkaJSYnKCkqNDU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6g4SFhoeIiYqSk5SVlpeYmZqio6Slpqeoqaqys7S1tre4ubrCw8TFxsfIycrS09TV1tfY2drh4uPk5ebn6Onq8fLz9PX29/j5+v/EAB8BAAMBAQEBAQEBAQEAAAAAAAABAgMEBQYHCAkKC//EALURAAIBAgQEAwQHBQQEAAECdwABAgMRBAUhMQYSQVEHYXETIjKBCBRCkaGxwQkjM1LwFWJy0QoWJDThJfEXGBkaJicoKSo1Njc4OTpDREVGR0hJSlNUVVZXWFlaY2RlZmdoaWpzdHV2d3h5eoKDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uLj5OXm5+jp6vLz9PX29/j5+v/bAEMAAgICAgICAwICAwUDAwMFBgUFBQUGCAYGBgYGCAoICAgICAgKCgoKCgoKCgwMDAwMDA4ODg4ODw8PDw8PDw8PD//bAEMBAgICBAQEBwQEBxALCQsQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEP/dAAQAAv/aAAwDAQACEQMRAD8A/E8Lk4rQsocXcD46SIf/AB4VDbpvYDua95+HfhtZtHn8QpBbXEdvKyM00iKW2RtKY4Vcjc+xGY45wAByQD62FwzqO17Luc0pWPC7yHNzM2Orsf1NUGXBxXu/xH8O/Y7Cy114baCG9m8oNBIrbCYlmCTKmdr7JEbHJwcH5gQPEZ02sR6UsThnTdr3XcIyuf/Q/GHT/JkcQzbQpO7Lccjtn3r0Dwv/AG1fMdH0e+e1e+kRTaEM4uZwTtBXhSRk7c8YOO/PlwJByK14dZvI7dbXcDEpJAKjv79ccetezQxfLHlZw1acn8L1PTPE+nanZpb2Wr6i99JBkw2gV4xbzSk8KuGA3BckgYKjGQMVzPjG70+ygh8LaXFZSQWshuGurdd8kkkqDKGY5YqgABUfKH3ECsW48U6vcWs1k02IbjbvUKBnb0AOMgdsA4xxXOE55oxGJ5lZDjRVk5atH//Z";
+
+/** Terminal capability surface branding probes. */
+export interface BrandCapabilities {
+  /** Kitty graphics protocol available. */
+  kitty: boolean;
+}
+
+/** Pure tier selection; exported for direct unit testing. */
+export function logoTierFor(caps: BrandCapabilities, forcePlain: boolean): LogoTier {
+  if (forcePlain) return "plain";
+  if (caps.kitty) return "kitty";
+  return "glyph";
+}
+
+/**
+ * Resolve the environment (PI_WEAVE_TUI_PLAIN) to a plain flag. Exported as a
+ * small pure function so the env read is testable in isolation.
+ */
+export function plainEnv(env: Record<string, string | undefined> = process.env): boolean {
+  const v = env[PLAIN_ENV];
+  return v !== undefined && v !== "" && v !== "0";
+}
+
+// Session-level probe cache (probed once, reused for the whole session §5.1).
+let cachedTier: LogoTier | null = null;
+let cachedCaps: BrandCapabilities | null = null;
+
+/**
+ * Return the session-cached capabilities (probed once). The probe runs at most
+ * once per process; subsequent calls reuse the cache. `getCaps` is injectable
+ * for tests (defaults to a live kitty probe). Never throws.
+ */
+export function probeGraphics(getCaps: () => BrandCapabilities): BrandCapabilities {
+  if (cachedCaps) return cachedCaps;
+  try {
+    cachedCaps = getCaps();
+  } catch {
+    cachedCaps = { kitty: false };
+  }
+  return cachedCaps;
+}
+
+/**
+ * Resolve the session logo tier, probing terminal capability once and caching
+ * for the process. `env` is injectable for tests.
+ */
+export function logoTier(env: Record<string, string | undefined> = process.env): LogoTier {
+  if (cachedTier) return cachedTier;
+  const caps = probeGraphics(() => getBrandCapabilities());
+  cachedTier = logoTierFor(caps, plainEnv(env));
+  return cachedTier;
+}
+
+/** Reset the session probe cache (test seam). */
+export function resetBrandCache(): void {
+  cachedTier = null;
+  cachedCaps = null;
+}
+
+/** A live kitty-capability probe backed by pi-tui's terminal capability query. */
+export function getBrandCapabilities(): BrandCapabilities {
+  return { kitty: detectCapabilities().images === "kitty" };
+}
+
+/**
+ * The mark rendered as a single header line (≤ width). This is the string the
+ * header strip / empty state embed. For the kitty tier the mark glyph is used
+ * in the text strip; the real raster is emitted via `logoImage()` when a kitty
+ * surface is available.
+ */
+export function renderMark(tier: LogoTier, theme: { fg: (slot: ThemeSlot, text: string) => string }, width: number): string {
+  let mark: string;
+  if (tier === "plain") {
+    mark = theme.fg("muted", PLAIN_MARK);
+  } else {
+    // kitty and glyph tiers share the curated glyph in the text strip.
+    mark = theme.fg("accent", MARK_GLYPH);
+  }
+  return mark.slice(0, Math.max(1, width));
+}
+
+/**
+ * A small pi-tui `Image` component for the kitty tier (decision 1 favicon).
+ * Takes the base64 JPG + mime; renders at ~2×2 cells. Returns a component that
+ * emits the Kitty sequence when the terminal supports it, else a text fallback.
+ */
+export function logoImage(
+  base64Data: string,
+  mimeType: string,
+  theme: { fg: (slot: ThemeSlot, text: string) => string },
+): Component {
+  return new Image(base64Data, mimeType, { fallbackColor: (t) => theme.fg("text", t) }, {
+    maxWidthCells: 2,
+    maxHeightCells: 2,
+  });
+}
+
+/**
+ * Build the bundled kitty raster logo `Image` (decision 1 favicon). Returns a
+ * component only when the terminal supports the Kitty graphics protocol;
+ * `null` otherwise so the caller keeps the one-line glyph header. The render
+ * path splices this component's lines onto their own row(s) — never inlined
+ * into a styled text line. The base64 asset is a compile-time constant, so the
+ * only fallback needed is the Kitty gate (no fs/path reads at runtime).
+ */
+export function bundledLogoImage(
+  theme: { fg: (slot: ThemeSlot, text: string) => string },
+): Component | null {
+  if (getCapabilities().images === "kitty") return logoImage(LOGO_B64, LOGO_MIME, theme);
+  return null;
+}

package/src/pi/viewer/tui/explorer.ts

@@ -13,6 +13,7 @@
  */
 
 import { matchesKey, parseKey, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { BodyStore } from "./bodyStore";
 
 import type { GraphModel, GraphNode, NodeKind } from "../../../core/graph/model";
 import type { NoteSource } from "../../../core/types";
@@ -141,10 +142,8 @@ export class WeaveExplorer implements Component {
   private readonly nowFn: () => number;
 
   state: ExplorerState;
-  /** Cached note/okf bodies keyed by node id; null = not yet loaded. */
-  private bodyCache = new Map<string, string | null>();
-  /** In-flight body loads, keyed by node id. */
-  private bodyLoading = new Set<string>();
+  /** Shared note/okf body cache (dedup by node id, bust-on-refresh). */
+  private readonly bodies: BodyStore;
   /** Render cache keyed by `${width}:${version}`. */
   private renderCache = new Map<string, string[]>();
   wantsKeyRelease = false;
@@ -157,14 +156,21 @@ export class WeaveExplorer implements Component {
     this.done = opts.done;
     this.rows = opts.rows ?? 24;
     this.nowFn = opts.now ?? Date.now;
+    this.bodies = new BodyStore({
+      loaders: opts.loaders,
+      onChange: () => {
+        this.state = { ...this.state, version: this.state.version + 1 };
+        this.invalidate();
+        this.tui.requestRender();
+      },
+    });
     this.state = initialState(graphRoots(this.model));
   }
 
   /** Replace the graph (used by the `r` refresh). Preserves selection by id. */
   setModel(model: GraphModel): void {
     this.model = model;
-    this.bodyCache.clear();
-    this.bodyLoading.clear();
+    this.bodies.clear();
     this.state = reduce(this.state, { type: "refreshDone" });
     // Re-resolve selection: keep id if still present, else first root.
     if (this.state.selectedId && !this.nodeExists(this.state.selectedId)) {
@@ -504,31 +510,12 @@ export class WeaveExplorer implements Component {
   }
 
   private maybeLoadBody(id: string): void {
-    if (this.bodyCache.has(id) || this.bodyLoading.has(id)) return;
     const node = this.model.nodes.find((n) => n.id === id);
     if (!node) return;
     if (node.kind === "note") {
-      const slug = node.detail.slug;
-      if (!slug) return;
-      this.bodyLoading.add(id);
-      void this.loaders.loadNote(slug).then((note) => {
-        this.bodyCache.set(id, note?.body ?? null);
-        this.bodyLoading.delete(id);
-        this.state = { ...this.state, version: this.state.version + 1 };
-        this.invalidate();
-        this.tui.requestRender();
-      });
+      this.bodies.load(id, "note", node.detail.slug);
     } else if (node.kind === "file") {
-      const rel = node.detail.path;
-      if (!rel) return;
-      this.bodyLoading.add(id);
-      void this.loaders.loadOkf(rel).then((file) => {
-        this.bodyCache.set(id, file?.body ?? null);
-        this.bodyLoading.delete(id);
-        this.state = { ...this.state, version: this.state.version + 1 };
-        this.invalidate();
-        this.tui.requestRender();
-      });
+      this.bodies.load(id, "file", node.detail.path);
     }
   }
 
@@ -539,8 +526,8 @@ export class WeaveExplorer implements Component {
     // never completes (maybeLoadBody skips non-note/file kinds).
     const node = this.model.nodes.find((n) => n.id === id);
     if (!node || (node.kind !== "note" && node.kind !== "file")) return [];
-    if (this.bodyLoading.has(id)) return [this.theme.fg("dim", "(loading…)")];
-    const body = this.bodyCache.get(id);
+    if (this.bodies.isLoading(id)) return [this.theme.fg("dim", "(loading…)")];
+    const body = this.bodies.get(id);
     if (body === undefined) {
       // not yet requested — trigger a load (render is sync, so show placeholder)
       queueMicrotask(() => this.maybeLoadBody(id));

package/src/pi/viewer/tui/openNote.ts

@@ -0,0 +1,60 @@
+/**
+ * openNote — open a vault note in the user's editor (weave-view tui).
+ *
+ * Lifted out of the old browser viewer's `server.ts` when the in-browser
+ * viewer was retired in favour of a pixi.js rewrite; the TUI's `openNote`
+ * loader is the only remaining caller. The slug is validated against the
+ * vault (traversal-safe) before any shell-out, so an unsafe or missing
+ * note never reaches the editor.
+ */
+
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+import { promisify } from "node:util";
+import { getNote, resolveNotePath } from "../../../core";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * The OS command used to open a note file in the user's editor. Respects
+ * $EDITOR / $VISUAL (which may carry args, e.g. "code --wait"); falls back
+ * to the platform default opener. `env` and `os` are injectable so the
+ * mapping is unit-testable on any host without stubbing globals.
+ */
+export function openNoteCommand(
+  notePath: string,
+  env: NodeJS.ProcessEnv = process.env,
+  os: NodeJS.Platform = platform(),
+): { command: string; args: string[] } {
+  const editor = (env.EDITOR || env.VISUAL || "").trim();
+  if (editor) {
+    // editor is a trimmed non-empty string, so split+filter always yields a
+    // first segment — assert it rather than leave a dead `?? ""` branch.
+    const parts = editor.split(/\s+/).filter(Boolean);
+    const command = parts[0] as string;
+    return { command, args: [...parts.slice(1), notePath] };
+  }
+  if (os === "darwin") return { command: "open", args: [notePath] };
+  if (os === "win32") return { command: "cmd", args: ["/c", "start", "", notePath] };
+  return { command: "xdg-open", args: [notePath] };
+}
+
+/**
+ * Open a note in the OS editor. The slug is validated against the vault
+ * (traversal-safe) before any shell-out; returns false when the note does
+ * not exist or the slug is unsafe.
+ */
+export async function openNoteInEditor(
+  vaultRoot: string,
+  slug: string,
+  openCommand: (notePath: string) => { command: string; args: string[] } = openNoteCommand,
+): Promise<boolean> {
+  const path = resolveNotePath(vaultRoot, slug);
+  if (path === null) return false; // traversal-safe
+  const note = await getNote(vaultRoot, slug);
+  if (note === null) return false;
+  const { command, args } = openCommand(path);
+  if (!command) return false;
+  await execFileAsync(command, args);
+  return true;
+}

package/src/pi/viewer/tui/run.ts

@@ -17,8 +17,10 @@ import {
   resolveVaultRoot,
   type GraphModel,
 } from "../../../core";
-import { openNoteInEditor } from "../server";
-import { WeaveExplorer, type WeaveLoaders, type WeaveTheme, type WeaveTui } from "./explorer";
+import { openNoteInEditor } from "./openNote";
+import { bundledLogoImage, logoTier, renderMark } from "./branding";
+import { WeaveWorkspace } from "./workspaceRoot";
+import type { WeaveLoaders, WeaveTheme, WeaveTui } from "./explorer";
 import { getWorkspaceStatus, formatStatusLine } from "../../../core";
 
 /** Open the in-terminal knowledge explorer. Returns when the explorer closes. */
@@ -26,7 +28,7 @@ export async function runWeaveViewTui(ctx: ExtensionCommandContext): Promise<voi
   // Guard: the TUI needs an interactive terminal (design §2).
   if (!ctx.hasUI || ctx.mode !== "tui") {
     ctx.ui.notify(
-      "pi-weave: '/weave-view tui' needs an interactive terminal — run /weave-view for the browser viewer.",
+      "pi-weave: '/weave-view' needs an interactive terminal to open the in-terminal explorer.",
       "warning",
     );
     return;
@@ -45,13 +47,20 @@ export async function runWeaveViewTui(ctx: ExtensionCommandContext): Promise<voi
 
   await ctx.ui.custom(
     (tui, theme, _keybindings, done) => {
-      const explorer = new WeaveExplorer({
+      const tier = logoTier();
+      const logo = renderMark(tier, theme as unknown as WeaveTheme, 20);
+      // bundledLogoImage gates on Kitty support itself and returns null (glyph
+      // header) when unavailable.
+      const logoImage = bundledLogoImage(theme as unknown as WeaveTheme);
+      const explorer = new WeaveWorkspace({
         model,
         theme: theme as unknown as WeaveTheme,
         tui: tui as unknown as WeaveTui,
         loaders,
         done,
         rows: tui.terminal.rows,
+        logo,
+        logoImage,
       });
       return explorer;
     },