@gmickel/gno 2.6.0 → 2.7.1

package/src/cli/commands/status.ts

@@ -8,6 +8,7 @@
 import type { ContentTypeBoostStatus } from "../../config/content-types";
 import type { ActivationStatus } from "../../core/activation-status";
 import type { MemoryStatus } from "../../core/memory-diagnostics";
+import type { BackgroundIssue } from "../../serve/status-model";
 import type { IndexStatus } from "../../store/types";
 
 import { getIndexDbPath, getModelsCachePath } from "../../app/constants";
@@ -24,11 +25,18 @@ import {
   buildMemoryStatus,
   formatMemoryStatusLines,
 } from "../../core/memory-diagnostics";
+import { formatVectorPartitionLines } from "../../core/vector-partition-status";
 import { ModelCache } from "../../llm/cache";
 import { getActivePreset, resolveModelUri } from "../../llm/registry";
 import { getConnectorVerificationTargets } from "../../serve/connectors";
 import { createStandaloneResidentStatus } from "../../serve/resident-status";
 import { SqliteAdapter } from "../../store/sqlite/adapter";
+import {
+  formatBackgroundIssue,
+  residentIssues,
+  resolveProcessPaths,
+  statusProcess,
+} from "../detach";
 
 /**
  * Options for status command.
@@ -54,9 +62,35 @@ export type StatusResult =
       activation: ActivationStatus;
       contentTypeBoost: ContentTypeBoostStatus;
       memory: MemoryStatus;
+      backgroundIssues: ResidentBackgroundIssue[];
     }
   | { success: false; error: string };
 
+/** A background issue reported by (or about) a running detached resident. */
+export type ResidentBackgroundIssue = BackgroundIssue & {
+  process: "serve" | "daemon";
+  pid: number;
+};
+
+/**
+ * Ask each detached resident for its background issues. Each request is
+ * bounded (500ms), so a hung resident is reported, never waited on.
+ */
+async function collectResidentIssues(): Promise<ResidentBackgroundIssue[]> {
+  const statuses = await Promise.all(
+    (["serve", "daemon"] as const).map((kind) =>
+      statusProcess({ kind, ...resolveProcessPaths(kind) })
+    )
+  );
+  return statuses.flatMap((processStatus) =>
+    residentIssues(processStatus).map((issue) => ({
+      process: processStatus.cmd,
+      pid: processStatus.pid ?? 0,
+      ...issue,
+    }))
+  );
+}
+
 function connectorProjectionLine(activation: ActivationStatus): string | null {
   const { projected, total, truncated } = activation.connectorProjection;
   if (!truncated) {
@@ -117,6 +151,12 @@ function formatTerminal(
   if (indexStatus.embeddingBacklog > 0) {
     lines.push(`Embedding backlog: ${indexStatus.embeddingBacklog} chunks`);
   }
+  lines.push(
+    ...formatVectorPartitionLines(
+      indexStatus.vectorPartitions,
+      indexStatus.vectorRuntime
+    )
+  );
 
   const chunking = formatChunkingStatus(indexStatus.chunking);
   if (chunking) lines.push(chunking);
@@ -205,6 +245,11 @@ function formatMarkdown(
   lines.push(`- **Documents**: ${indexStatus.activeDocuments}`);
   lines.push(`- **Chunks**: ${indexStatus.totalChunks}`);
   lines.push(`- **Embedding backlog**: ${indexStatus.embeddingBacklog}`);
+  for (const line of formatVectorPartitionLines(
+    indexStatus.vectorPartitions,
+    indexStatus.vectorRuntime
+  ))
+    lines.push(`- ${line.trim()}`);
   if (indexStatus.typedMetadata)
     lines.push(
       `- **Typed metadata**: ${indexStatus.typedMetadata.pending} pending sync, ${indexStatus.typedMetadata.invalid} invalid`
@@ -318,6 +363,7 @@ export async function status(
       activation,
       contentTypeBoost: buildContentTypeBoostStatus(config.contentTypes ?? []),
       memory: await buildMemoryStatus(store, config.collections),
+      backgroundIssues: await collectResidentIssues(),
     };
   } finally {
     await store.close();
@@ -356,6 +402,8 @@ export function formatStatus(
         totalDocuments: s.activeDocuments,
         totalChunks: s.totalChunks,
         embeddingBacklog: s.embeddingBacklog,
+        vectorPartitions: s.vectorPartitions,
+        vectorRuntime: s.vectorRuntime,
         typedMetadata: s.typedMetadata,
         chunking: s.chunking,
         lastUpdated: s.lastUpdatedAt,
@@ -363,6 +411,9 @@ export function formatStatus(
         contentTypeBoost: result.contentTypeBoost,
         activation: result.activation,
         memory: result.memory,
+        ...(result.backgroundIssues.length
+          ? { backgroundIssues: result.backgroundIssues }
+          : {}),
       },
       null,
       2
@@ -378,10 +429,17 @@ export function formatStatus(
     );
   }
 
-  return formatTerminal(
-    result.status,
-    result.activation,
-    result.contentTypeBoost,
-    result.memory
+  const issueLines = result.backgroundIssues.map(
+    (issue) =>
+      `  ${issue.process} (pid ${issue.pid}): ${formatBackgroundIssue(issue)}`
   );
+  return [
+    formatTerminal(
+      result.status,
+      result.activation,
+      result.contentTypeBoost,
+      result.memory
+    ),
+    ...(issueLines.length ? ["", "Background issues:", ...issueLines] : []),
+  ].join("\n");
 }

package/src/cli/commands/vec.ts

@@ -13,6 +13,10 @@ import {
   createVectorIndexPort,
   createVectorStatsPort,
 } from "../../store/vector";
+import {
+  dropVectorPartition,
+  type VectorPartitionStatus,
+} from "../../store/vector/status";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types
@@ -294,3 +298,53 @@ export function formatVecRebuild(
 
   return `Vec index rebuilt: ${result.count.toLocaleString()} vectors`;
 }
+
+export type VecDropResult =
+  | { success: true; partition: VectorPartitionStatus }
+  | { success: false; error: string };
+
+/**
+ * Drop an abandoned vector partition (shadow or legacy). Active partitions
+ * that retrieval uses are refused.
+ */
+export async function vecDrop(
+  partition: string,
+  options: VecOptions = {}
+): Promise<VecDropResult> {
+  if (!(await isInitialized(options.configPath)))
+    return { success: false, error: "GNO not initialized. Run: gno init" };
+  const configResult = await loadConfig(options.configPath);
+  if (!configResult.ok)
+    return { success: false, error: configResult.error.message };
+  const store = new SqliteAdapter();
+  const openResult = await store.open(
+    getIndexDbPath(options.indexName),
+    configResult.value.ftsTokenizer,
+    configResult.value.busyTimeoutMs
+  );
+  if (!openResult.ok)
+    return { success: false, error: openResult.error.message };
+  try {
+    const dropped = await dropVectorPartition(store.getRawDb(), partition);
+    return dropped.ok
+      ? { success: true, partition: dropped.partition }
+      : { success: false, error: dropped.error };
+  } finally {
+    await store.close();
+  }
+}
+
+export function formatVecDrop(
+  result: VecDropResult,
+  options: { json?: boolean }
+): string {
+  if (!result.success) {
+    return options.json
+      ? JSON.stringify({ error: { code: "RUNTIME", message: result.error } })
+      : `Error: ${result.error}`;
+  }
+  const { partition } = result;
+  return options.json
+    ? JSON.stringify({ dropped: partition }, null, 2)
+    : `Dropped ${partition.state} partition ${partition.id.slice(0, 12)} (${partition.provenance}, ${partition.owners} chunks)`;
+}

package/src/cli/detach.ts

@@ -20,7 +20,7 @@ import { mkdir, stat, unlink } from "node:fs/promises";
 // node:path — no Bun path utils.
 import { dirname, join } from "node:path";
 
-import type { ResidentStatus } from "../serve/status-model";
+import type { BackgroundIssue, ResidentStatus } from "../serve/status-model";
 
 import { VERSION, resolveDirs } from "../app/constants";
 import { toAbsolutePath } from "../config/paths";
@@ -840,6 +840,34 @@ export async function statusProcess(
   };
 }
 
+/** Issues a running detached resident reports, or that it failed to answer at all. */
+export function residentIssues(status: ProcessStatus): BackgroundIssue[] {
+  if (!status.running) return [];
+  if (!status.resident)
+    return [
+      {
+        job: "resident",
+        state: "unresponsive",
+        consecutiveFailures: 0,
+        runningSeconds: null,
+      },
+    ];
+  return status.resident.backgroundIssues ?? [];
+}
+
+export function formatBackgroundIssue(issue: BackgroundIssue): string {
+  switch (issue.state) {
+    case "unresponsive":
+      return "resident did not answer its status request within 500ms (busy or hung)";
+    case "failing":
+      return `background embed failing (${issue.consecutiveFailures} failed passes in a row; details in the log)`;
+    case "parked":
+      return `background embed parked after ${issue.consecutiveFailures} failed passes; pending chunks wait for new changes or \`gno embed\``;
+    case "overrunning":
+      return `background embed pass running for ${issue.runningSeconds ?? 0}s`;
+  }
+}
+
 /**
  * Inspect the pid-file for a "live-foreign" signal — a live pid whose
  * recorded gno version disagrees with the currently running binary. Returns

package/src/cli/errors.ts

@@ -9,15 +9,19 @@
 // Error Types
 // ─────────────────────────────────────────────────────────────────────────────
 
-export type CliErrorCode =
-  | "VALIDATION"
-  | "RUNTIME"
-  | "NOT_RUNNING"
-  | "BUSY"
-  | "AUDIT_FINDINGS"
-  | "AUDIT_PARTIAL"
-  | "CONTEXT_STALE"
-  | "CONTEXT_CONFLICT";
+/** Every code the CLI error model can emit; `error.schema.json` must list each. */
+export const CLI_ERROR_CODES = [
+  "VALIDATION",
+  "RUNTIME",
+  "NOT_RUNNING",
+  "BUSY",
+  "AUDIT_FINDINGS",
+  "AUDIT_PARTIAL",
+  "CONTEXT_STALE",
+  "CONTEXT_CONFLICT",
+] as const;
+
+export type CliErrorCode = (typeof CLI_ERROR_CODES)[number];
 
 export interface CliErrorOptions {
   details?: Record<string, unknown>;

package/src/cli/program.ts

@@ -41,7 +41,11 @@ import {
   type GlobalOptions,
   parseGlobalOptions,
 } from "./context";
-import { DETACHED_CHILD_FLAG } from "./detach";
+import {
+  DETACHED_CHILD_FLAG,
+  formatBackgroundIssue,
+  residentIssues,
+} from "./detach";
 import { CliError } from "./errors";
 import {
   assertFormatSupported,
@@ -3544,6 +3548,10 @@ function wireManagementCommands(program: Command): void {
       .option("--model <uri>", "embedding model URI")
       .option("--batch-size <num>", "batch size", "32")
       .option("--force", "regenerate all embeddings")
+      .option(
+        "--new-partition",
+        "confirm building a separate vector partition for an incompatible runtime"
+      )
       .option("--dry-run", "show what would be done")
       .option("--json", "JSON output")
   ).action(
@@ -3567,6 +3575,7 @@ function wireManagementCommands(program: Command): void {
         force: Boolean(cmdOpts.force),
         dryRun: Boolean(cmdOpts.dryRun),
         yes: globals.yes,
+        newPartition: Boolean(cmdOpts.newPartition),
         json: format === "json",
         verbose: globals.verbose,
         offline: globals.offline,
@@ -3675,6 +3684,43 @@ function wireVecCommands(program: Command): void {
     );
   });
 
+  // vec drop
+  addWriteLeaseFlags(
+    vecCmd
+      .command("drop <partition>")
+      .description(
+        "Drop an abandoned shadow vector partition (id prefix from gno status)"
+      )
+      .option("--json", "JSON output")
+  ).action(async (partition: string, cmdOpts: Record<string, unknown>) => {
+    const format = getFormat(cmdOpts);
+    const globals = getGlobals();
+
+    const { vecDrop, formatVecDrop } = await import("./commands/vec");
+    const lease = parseWriteLeaseFlags(cmdOpts);
+    const result = await withCliWriteLease(
+      {
+        indexName: globals.index,
+        lockWaitMs: lease.lockWaitMs,
+        noWait: lease.noWait,
+      },
+      () =>
+        vecDrop(partition, {
+          configPath: globals.config,
+          indexName: globals.index,
+        })
+    );
+    throwIfWriteLeaseBusy(result, format === "json");
+
+    if (!result.success) {
+      throw new CliError("VALIDATION", result.error);
+    }
+
+    process.stdout.write(
+      `${formatVecDrop(result, { json: format === "json" })}\n`
+    );
+  });
+
   // vec rebuild
   addWriteLeaseFlags(
     vecCmd
@@ -5017,6 +5063,9 @@ async function runDaemonStatus(deps: DaemonStatusDeps): Promise<void> {
     } else {
       process.stdout.write(` (${status.log_size_bytes} bytes)\n`);
     }
+    for (const issue of residentIssues(status)) {
+      process.stdout.write(`  issue    ${formatBackgroundIssue(issue)}\n`);
+    }
     if (findings) {
       process.stdout.write(
         `  findings ${formatFindingsRunStatusLine(findings)}\n`
@@ -5372,6 +5421,9 @@ async function runServeStatus(deps: ServeStatusDeps): Promise<void> {
     } else {
       process.stdout.write(` (${status.log_size_bytes} bytes)\n`);
     }
+    for (const issue of residentIssues(status)) {
+      process.stdout.write(`  issue    ${formatBackgroundIssue(issue)}\n`);
+    }
 
     if (foreign) {
       // Terminal mode: emit the operator-facing warning on stderr. JSON

package/src/core/capture-sync.ts

@@ -10,6 +10,7 @@ import type { Collection, Config } from "../config/types";
 import type { StorePort } from "../store/types";
 import type { CaptureIndexStatus } from "./capture";
 
+import { buildUri } from "../app/constants";
 import {
   type CollectionSyncResult,
   defaultSyncService,
@@ -30,9 +31,14 @@ export class CaptureSyncError extends Error {
   /** The sync failure itself, without the write half of the message. */
   readonly syncError: string;
 
-  constructor(input: { absPath: string; relPath: string; cause: string }) {
+  constructor(input: {
+    absPath: string;
+    relPath: string;
+    uri: string;
+    cause: string;
+  }) {
     super(
-      `Capture written to ${input.absPath} but lexical sync failed: ${input.cause}. Run gno update to retry indexing.`
+      `Capture written to ${input.uri} but lexical sync failed: ${input.cause}. Run gno update to retry indexing.`
     );
     this.name = "CaptureSyncError";
     this.absPath = input.absPath;
@@ -82,6 +88,7 @@ export async function syncCapturedFile(
     throw new CaptureSyncError({
       absPath: input.absPath,
       relPath: input.relPath,
+      uri: buildUri(input.collection.name, input.relPath),
       cause,
     });
   };

package/src/core/host-paths.ts

@@ -0,0 +1,49 @@
+/**
+ * Host path redaction for callers that are not on the owner's machine.
+ *
+ * Result payloads name a source file's host location in `absPath`
+ * (`source.absPath` on search/get results, top-level on capture, memory and
+ * peek receipts). A remote caller identifies documents by `uri` and
+ * collection-relative `relPath` instead, so every `absPath` key is removed
+ * before a payload leaves a remote-reachable surface.
+ *
+ * Status, collection, and connector payloads also name owner configuration
+ * locations: `configPath`, `dbPath`, and `path` (collection roots, suggested
+ * folders, model cache and model files, connector targets). A remote caller
+ * identifies a collection by `name`, so those keys are removed from those
+ * payloads too.
+ */
+
+/** Document host path key of result payloads. */
+export const HOST_PATH_FIELDS: ReadonlySet<string> = new Set(["absPath"]);
+
+/** Owner configuration path keys of status, collection, and connector payloads. */
+export const OWNER_CONFIG_PATH_FIELDS: ReadonlySet<string> = new Set([
+  "configPath",
+  "dbPath",
+  "path",
+]);
+
+const isPlainObject = (value: object): boolean => {
+  const proto = Object.getPrototypeOf(value) as object | null;
+  return proto === Object.prototype || proto === null;
+};
+
+/** Deep copy of a JSON-shaped value with every key in `fields` removed. */
+export function withoutFields<T>(value: T, fields: ReadonlySet<string>): T {
+  if (Array.isArray(value)) {
+    return value.map((item: unknown) => withoutFields(item, fields)) as T;
+  }
+  if (value === null || typeof value !== "object" || !isPlainObject(value)) {
+    return value;
+  }
+  const copy: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (!fields.has(key)) copy[key] = withoutFields(entry, fields);
+  }
+  return copy as T;
+}
+
+/** Deep copy of a JSON-shaped value with every `absPath` key removed. */
+export const withoutHostPaths = <T>(value: T): T =>
+  withoutFields(value, HOST_PATH_FIELDS);

package/src/core/memory-remember.ts

@@ -24,6 +24,7 @@ import type {
   RememberResult,
 } from "./memory-types";
 
+import { buildUri } from "../app/constants";
 import { defaultSyncService, withContentTypeRules } from "../ingestion";
 import { withWriteLock } from "./file-lock";
 import { atomicCreate } from "./file-ops";
@@ -399,7 +400,7 @@ export async function rememberFact(
     if (sync.status === "failed") {
       throw new MemoryError(
         "MEMORY_SYNC_FAILED",
-        `Memory record written to ${absPath} but lexical sync failed: ${sync.error}. Run gno update to retry indexing.`
+        `Memory record written to ${buildUri(collection.name, relPath)} but lexical sync failed: ${sync.error}. Run gno update to retry indexing.`
       );
     }
     const written = (doc as { value: DocumentRow }).value;
@@ -415,13 +416,13 @@ export async function rememberFact(
       if (!projected) {
         throw new MemoryError(
           "MEMORY_SUPERSEDE_PROJECTION_FAILED",
-          `Successor written to ${absPath} but its supersedes edge did not project${projectionErrors ? ` (${projectionErrors})` : ""}; the predecessor still reads as current. Run gno update to retry the projection.`
+          `Successor written to ${buildUri(collection.name, relPath)} but its supersedes edge did not project${projectionErrors ? ` (${projectionErrors})` : ""}; the predecessor still reads as current. Run gno update to retry the projection.`
         );
       }
     } else if (projectionErrors.length > 0) {
       throw new MemoryError(
         "MEMORY_SYNC_FAILED",
-        `Memory record written to ${absPath} but typed-edge projection failed: ${projectionErrors}. Run gno update to retry indexing.`
+        `Memory record written to ${buildUri(collection.name, relPath)} but typed-edge projection failed: ${projectionErrors}. Run gno update to retry indexing.`
       );
     }
     const record: MemoryFact = {

package/src/core/request-receipts.ts

@@ -11,14 +11,18 @@
  */
 
 import { Database } from "bun:sqlite";
-// node:fs/promises chmod/mkdir: filesystem structure ops, no Bun equivalent
-import { chmod, mkdir } from "node:fs/promises";
+// node:fs/promises chmod/mkdir/lstat/readdir: filesystem structure ops, no Bun equivalent
+import { chmod, lstat, mkdir, readdir } from "node:fs/promises";
 // node:path has no Bun path utilities
 import { basename, dirname, join } from "node:path";
 
 import { MCP_ERRORS } from "./errors";
 import { withWriteLock } from "./file-lock";
-import { windowsPrivatePath } from "./windows-private-path";
+import {
+  isOwnerOnlyDescriptor,
+  windowsDirectoryDescriptor,
+  windowsPrivatePath,
+} from "./windows-private-path";
 import { writeLeasePath } from "./write-lease";
 
 /** Committed receipts keep their full outcome this long, then become tombstones. */
@@ -221,25 +225,75 @@ CREATE TABLE IF NOT EXISTS request_receipts (
 /** Ledger directories whose owner-only Windows DACL this process verified. */
 const privateLedgerDirs = new Set<string>();
 
+/** Inside the ledger directory: what the last authoritative check verified. */
+const LEDGER_DIR_MARKER = ".owner-only-verified";
+
+export interface PrivateDirAcl {
+  /** Authoritative check (spawns PowerShell); `create` sets the owner-only DACL first. */
+  verify: (dir: string, create: boolean) => Promise<void>;
+  /** In-process owner and DACL bytes, or null when they cannot be read. */
+  descriptor: (dir: string) => Uint8Array | null;
+}
+
+const WINDOWS_ACL: PrivateDirAcl = {
+  verify: windowsPrivatePath,
+  descriptor: windowsDirectoryDescriptor,
+};
+
+/** Directory identity plus descriptor digest; null unless owner-only. */
+async function ledgerDirStamp(
+  dir: string,
+  acl: PrivateDirAcl
+): Promise<string | null> {
+  const { dev, ino } = await lstat(dir, { bigint: true });
+  const descriptor = acl.descriptor(dir);
+  if (!descriptor || !isOwnerOnlyDescriptor(descriptor)) return null;
+  const digest = new Bun.CryptoHasher("sha256")
+    .update(descriptor)
+    .digest("hex");
+  return `${dev}:${ino}:${digest}`;
+}
+
 /**
  * Windows ignores POSIX modes: give a new ledger directory the current-user
  * DACL before SQLite creates the database or its WAL/SHM (they inherit it),
  * and refuse an existing one that grants another principal access.
+ *
+ * The PowerShell check costs a process start, so its success is recorded in a
+ * marker inside the directory. A later open skips it only when the directory
+ * is the same object and its owner and DACL are byte-identical to the verified
+ * ones and still owner-only; reading the marker at all requires access that
+ * owner-only DACL grants. Anything else re-runs the authoritative check.
+ *
+ * An existing but empty directory is secured like a new one: a first open
+ * interrupted before its DACL was set leaves exactly that, and nothing inside
+ * it could have been exposed.
  */
-async function secureLedgerDir(
+export async function securePrivateLedgerDir(
   dir: string,
-  created: string | undefined
+  created: boolean,
+  acl: PrivateDirAcl = WINDOWS_ACL
 ): Promise<void> {
-  if (process.platform !== "win32" || privateLedgerDirs.has(dir)) return;
-  await windowsPrivatePath(dir, created !== undefined);
-  privateLedgerDirs.add(dir);
+  const marker = Bun.file(join(dir, LEDGER_DIR_MARKER));
+  if (!created) {
+    const stamp = await ledgerDirStamp(dir, acl);
+    if (stamp !== null && stamp === (await marker.text().catch(() => null)))
+      return;
+  }
+  const secure = created || (await readdir(dir)).length === 0;
+  await acl.verify(dir, secure);
+  const stamp = await ledgerDirStamp(dir, acl);
+  if (stamp !== null) await Bun.write(marker, stamp);
 }
 
 async function openLedger(path: string): Promise<Database> {
   try {
     const dir = dirname(path);
     const created = await mkdir(dir, { recursive: true, mode: 0o700 });
-    await secureLedgerDir(dir, created);
+    if (process.platform === "win32" && !privateLedgerDirs.has(dir)) {
+      await securePrivateLedgerDir(dir, created !== undefined);
+      privateLedgerDirs.add(dir);
+    }
     const db = new Database(path, { create: true, strict: true });
     try {
       // POSIX: private before any journal file exists (they inherit this mode).

package/src/core/shutdown-budget.ts

@@ -4,6 +4,12 @@ export const SHUTDOWN_ABORT_MS = 5_000;
 export const SHUTDOWN_EXIT_MS = 1_000;
 // The detached parent must not be killed before it can reap its native child.
 export const RESIDENT_STOP_GRACE_MS = 12_000;
+/**
+ * Longest synchronous SQLite busy wait a resident allows itself. A signal is
+ * handled only after the wait in progress ends, so this plus the shutdown
+ * clock must fit inside the stop grace (asserted in shutdown-budget tests).
+ */
+export const RESIDENT_BUSY_TIMEOUT_MS = 500;
 
 /** Observe settlement without abandoning rejection handling or retaining a timer. */
 export async function settlesBy(

package/src/core/vector-partition-status.ts

@@ -0,0 +1,52 @@
+import type {
+  VectorPartitionStatus,
+  VectorRuntimeStatus,
+} from "../store/vector/status";
+
+const shortId = (id: string): string => id.slice(0, 12);
+
+function runtimeLine(runtime: VectorRuntimeStatus): string {
+  const label = runtime.label ? ` (${runtime.label})` : "";
+  if (runtime.state === "vectors")
+    return `  This runtime${label} reads ${shortId(runtime.partition ?? "")}`;
+  if (runtime.state === "unavailable")
+    return `  This runtime${label} uses lexical retrieval only: ${runtime.reason}`;
+  return "  This runtime has not resolved a partition yet; run a query or `gno embed`";
+}
+
+/**
+ * The caller's runtime, then one line per partition. The healthy case (one
+ * current partition this runtime reads) prints nothing, so default status
+ * output is unchanged.
+ */
+export function formatVectorPartitionLines(
+  partitions?: VectorPartitionStatus[],
+  runtime?: VectorRuntimeStatus
+): string[] {
+  if (!partitions?.length) return [];
+  const [only] = partitions;
+  if (
+    partitions.length === 1 &&
+    only?.retrieval &&
+    !only.legacy &&
+    !only.incompatibleRuntimes.length
+  )
+    return [];
+  const lines = ["Vector partitions:"];
+  if (runtime) lines.push(runtimeLine(runtime));
+  for (const p of partitions) {
+    const role = p.retrieval
+      ? " (used by this runtime's retrieval)"
+      : p.droppable
+        ? ` (drop with: gno vec drop ${shortId(p.id)})`
+        : "";
+    lines.push(
+      `  ${p.retrieval ? "*" : " "} ${shortId(p.id)} ${p.state}${p.legacy ? " legacy" : ""}, ${p.owners} chunks, ${p.provenance}${role}`
+    );
+    if (p.compatibleRuntimes.length)
+      lines.push(`      read by: ${p.compatibleRuntimes.join("; ")}`);
+    if (p.incompatibleRuntimes.length)
+      lines.push(`      incompatible: ${p.incompatibleRuntimes.join("; ")}`);
+  }
+  return lines;
+}