@vellumai/assistant 0.12.2 → 0.12.3-staging.1

package/src/credential-execution/executable-discovery.ts

@@ -1,196 +1,98 @@
 /**
- * CES executable discovery and transport bootstrap.
+ * CES socket discovery and transport bootstrap.
  *
- * Provides two discovery strategies:
- *
- * 1. **Sibling mode** — Locates the CLI-launched CES sibling process via its
- *    Unix socket (`CES_LOCAL_SOCKET`). Used by bare-metal/local instances.
- *
- * 2. **Managed mode** — Locates the bootstrap Unix socket exposed by the CES
- *    sidecar container through a shared emptyDir volume, and returns a
- *    connected Unix socket transport.
- *
- * Both strategies fail closed: if the socket cannot be found, the discovery
- * returns a structured error rather than falling back to in-process
- * credential handling.
+ * Local siblings and managed sidecars share one resolver: `ces.sock` under
+ * `CES_BOOTSTRAP_SOCKET_DIR` (default `/run/ces-bootstrap`). Discovery fails
+ * closed if the socket cannot be found.
  */
 
 import { existsSync } from "node:fs";
-import { join } from "node:path";
 
-import { getIsContainerized } from "../config/env-registry.js";
+import {
+  isNamedPipePath,
+  resolveIpcEndpoint,
+} from "@vellumai/ipc-server-utils";
+
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("ces-discovery");
 
-// ---------------------------------------------------------------------------
-// Well-known paths
-// ---------------------------------------------------------------------------
-
-/** Default directory for the bootstrap socket shared volume. */
+/** Default directory for the CES Unix socket. */
 const DEFAULT_BOOTSTRAP_SOCKET_DIR = "/run/ces-bootstrap";
 
-/** Bootstrap socket filename. */
-const BOOTSTRAP_SOCKET_NAME = "ces.sock";
-
 /**
- * Resolve the CES bootstrap socket path.
+ * Resolve the CES socket path used in every environment.
  *
- * Priority:
- * 1. `CES_BOOTSTRAP_SOCKET_DIR` env var (directory) — appends `ces.sock`
- * 2. `CES_BOOTSTRAP_SOCKET` env var (full file path override)
- * 3. Hardcoded default: `/run/ces-bootstrap/ces.sock`
- *
- * The pod template exports `CES_BOOTSTRAP_SOCKET_DIR`; the full-path
- * override is kept for local testing convenience.
+ * Uses `CES_BOOTSTRAP_SOCKET_DIR` when set, otherwise `/run/ces-bootstrap`.
+ * `ces.sock` is resolved through `resolveIpcEndpoint`.
  */
-function getManagedBootstrapSocketPath(): string {
-  const dir = process.env["CES_BOOTSTRAP_SOCKET_DIR"];
-  if (dir) {
-    return join(dir, BOOTSTRAP_SOCKET_NAME);
-  }
-  return (
-    process.env["CES_BOOTSTRAP_SOCKET"] ??
-    join(DEFAULT_BOOTSTRAP_SOCKET_DIR, BOOTSTRAP_SOCKET_NAME)
-  );
+function getCesSocketPath(): string {
+  const dir =
+    process.env["CES_BOOTSTRAP_SOCKET_DIR"]?.trim() ||
+    DEFAULT_BOOTSTRAP_SOCKET_DIR;
+  return resolveIpcEndpoint("ces", { workspaceDir: dir }).path;
 }
 
-// ---------------------------------------------------------------------------
-// Discovery result types
-// ---------------------------------------------------------------------------
-
 export interface ManagedDiscoverySuccess {
   mode: "managed";
   socketPath: string;
 }
 
-/**
- * A local CES running as an independent sibling process (not spawned by the
- * assistant), reached over a Unix socket. Transport-identical to managed; the
- * distinct mode records that the assistant does not own this process's
- * lifecycle. This is the default topology for bare-metal/local instances.
- */
-export interface SiblingDiscoverySuccess {
-  mode: "sibling";
-  socketPath: string;
-}
-
 export interface DiscoveryFailure {
   mode: "unavailable";
   reason: string;
 }
 
-export type DiscoveryResult =
-  | ManagedDiscoverySuccess
-  | SiblingDiscoverySuccess
-  | DiscoveryFailure;
-
-// ---------------------------------------------------------------------------
-// Managed discovery
-// ---------------------------------------------------------------------------
+export type DiscoveryResult = ManagedDiscoverySuccess | DiscoveryFailure;
 
 /**
- * Discover the managed CES sidecar via its bootstrap Unix socket.
+ * Discover CES via the shared bootstrap Unix socket.
  *
- * Checks that the well-known socket file exists on disk. Does NOT open a
- * connection — the CES sidecar accepts exactly one connection and then
- * unlinks the socket, so a probe would consume the only slot. The actual
- * connection is made later by `CesProcessManager.start()`.
- *
- * The socket path is derived from `CES_BOOTSTRAP_SOCKET_DIR` (matching the
- * pod template), with `CES_BOOTSTRAP_SOCKET` as a full-path fallback.
+ * Checks that the well-known socket exists. Does not open a connection.
+ * CES serves a multi-connection listener, so the assistant and its child
+ * processes can each connect. The actual connection is made later by
+ * `CesProcessManager.start()`.
  */
 export function discoverManagedCes():
   | ManagedDiscoverySuccess
   | DiscoveryFailure {
-  const socketPath = getManagedBootstrapSocketPath();
+  const socketPath = getCesSocketPath();
 
-  if (!existsSync(socketPath)) {
+  if (!isNamedPipePath(socketPath) && !existsSync(socketPath)) {
     const reason = `CES bootstrap socket not found at ${socketPath}`;
     log.warn(reason);
     return { mode: "unavailable", reason };
   }
 
-  log.info({ socketPath }, "Managed CES bootstrap socket found");
+  log.info({ socketPath }, "CES bootstrap socket found");
   return { mode: "managed", socketPath };
 }
 
-// ---------------------------------------------------------------------------
-// Sibling discovery (local bare-metal topology)
-// ---------------------------------------------------------------------------
-
 /**
- * Discover a CLI-launched local CES sibling via its Unix socket. The CLI sets
- * `CES_LOCAL_SOCKET` on both the sibling and the daemon so they agree on the
- * path. Does not open a connection — that happens in `CesProcessManager.start()`.
- */
-export function discoverLocalSiblingCes():
-  | SiblingDiscoverySuccess
-  | DiscoveryFailure {
-  const socketPath = process.env["CES_LOCAL_SOCKET"];
-  if (!socketPath) {
-    const reason =
-      "CES_LOCAL_SOCKET is not set — cannot locate the CES sibling socket. The CLI should set this during wake/hatch.";
-    log.warn(reason);
-    return { mode: "unavailable", reason };
-  }
-  if (!existsSync(socketPath)) {
-    return {
-      mode: "unavailable",
-      reason: `CES sibling socket not found at ${socketPath}`,
-    };
-  }
-  log.info({ socketPath }, "Local CES sibling socket found");
-  return { mode: "sibling", socketPath };
-}
-
-// ---------------------------------------------------------------------------
-// Auto-discovery
-// ---------------------------------------------------------------------------
-
-/**
- * Automatically discover CES using the appropriate strategy for the
- * current deployment topology.
- *
- * - Containerized environments → managed sidecar discovery
- * - Non-containerized → CLI-launched sibling socket discovery
+ * Discover CES for the current process. Local and managed topologies use
+ * the same bootstrap socket path.
  */
 export function discoverCes(): DiscoveryResult {
-  if (getIsContainerized()) {
-    return discoverManagedCes();
-  }
-  return discoverLocalSiblingCes();
+  return discoverManagedCes();
 }
 
-/** How long to poll for the managed bootstrap socket before giving up. */
+/** How long to poll for the CES socket before giving up. */
 const MANAGED_DISCOVERY_TIMEOUT_MS = 3_000;
 
-/** Delay between managed bootstrap-socket discovery attempts. */
+/** Delay between CES socket discovery attempts. */
 const MANAGED_DISCOVERY_INTERVAL_MS = 100;
 
 /**
- * Discover CES, polling for the managed bootstrap socket with a short
- * backoff before failing.
- *
- * The managed CES sidecar re-binds its bootstrap socket after each assistant
- * session ends — it outlives any single assistant and accepts the next
- * connection (see `credential-executor/src/main.ts`). A reconnecting
- * assistant (e.g. after a container restart) can therefore probe during the
- * brief window before the socket is re-bound. A single existence check would
- * race that window and incorrectly report the sidecar as unavailable; polling
- * absorbs the gap.
+ * Discover CES, polling for the socket with a short backoff before failing.
  *
- * Local discovery is returned immediately — a missing binary will not appear
- * by waiting, so there is nothing to poll for.
+ * CES binds its socket asynchronously. A reconnecting assistant can probe
+ * during the brief window before the socket is re-bound. Polling absorbs
+ * that gap.
  */
 export async function discoverCesWithRetry({
   timeoutMs = MANAGED_DISCOVERY_TIMEOUT_MS,
   intervalMs = MANAGED_DISCOVERY_INTERVAL_MS,
 }: { timeoutMs?: number; intervalMs?: number } = {}): Promise<DiscoveryResult> {
-  // Both the managed bootstrap socket and the CLI-launched sibling socket
-  // are bound asynchronously, so polling is worthwhile. A missing local
-  // binary (the old stdio path) would not appear by waiting, but that path
-  // is gone — the sibling is the only local topology now.
   const deadline = Date.now() + timeoutMs;
   let result = discoverCes();
   while (result.mode === "unavailable" && Date.now() < deadline) {

package/src/credential-execution/process-manager.test.ts

@@ -3,12 +3,10 @@ import { createServer, type Server } from "node:net";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
-  afterAll,
   afterEach,
   beforeEach,
   describe,
   expect,
-  mock,
   test,
 } from "bun:test";
 
@@ -21,22 +19,18 @@ const untilClosed = (predicate: () => boolean) =>
     message: "socket close never propagated to the transport",
   });
 
-// ---------------------------------------------------------------------------
-// onTransportClose tests
-// ---------------------------------------------------------------------------
-
-// Mock executable-discovery so start() connects to our test socket.
-const realDiscovery = await import("./executable-discovery.js");
-
 let mockSocketPath = "";
 
-mock.module("./executable-discovery.js", () => ({
-  ...realDiscovery,
-  discoverCesWithRetry: async () => ({
-    mode: "sibling" as const,
+function discoverTestSocket() {
+  return Promise.resolve({
+    mode: "managed" as const,
     socketPath: mockSocketPath,
-  }),
-}));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// onTransportClose tests
+// ---------------------------------------------------------------------------
 
 describe("CesProcessManager.onTransportClose", () => {
   let tempDir: string;
@@ -67,12 +61,8 @@ describe("CesProcessManager.onTransportClose", () => {
     rmSync(tempDir, { recursive: true, force: true });
   });
 
-  afterAll(() => {
-    mock.module("./executable-discovery.js", () => realDiscovery);
-  });
-
   test("fires handler when the transport dies (socket closed)", async () => {
-    const pm = createCesProcessManager({});
+    const pm = createCesProcessManager({ discover: discoverTestSocket });
     const transport = await pm.start();
     expect(transport.isAlive()).toBe(true);
 
@@ -93,7 +83,7 @@ describe("CesProcessManager.onTransportClose", () => {
   });
 
   test("does not fire handler before the transport dies", async () => {
-    const pm = createCesProcessManager({});
+    const pm = createCesProcessManager({ discover: discoverTestSocket });
     await pm.start();
 
     let closeFired = false;
@@ -109,7 +99,7 @@ describe("CesProcessManager.onTransportClose", () => {
   });
 
   test("fires handler immediately if transport is already dead", async () => {
-    const pm = createCesProcessManager({});
+    const pm = createCesProcessManager({ discover: discoverTestSocket });
     const transport = await pm.start();
 
     // Kill the transport by destroying the server-side socket.
@@ -186,7 +176,10 @@ describe("CesProcessManager transport-death logging", () => {
 
   test("logs WARN when the transport dies unexpectedly (remote close)", async () => {
     const { calls, logger } = makeRecordingLogger();
-    const pm = createCesProcessManager({ logger });
+    const pm = createCesProcessManager({
+      logger,
+      discover: discoverTestSocket,
+    });
     const transport = await pm.start();
 
     // The remote (server) closes the connection: genuinely-unexpected death.
@@ -205,7 +198,10 @@ describe("CesProcessManager transport-death logging", () => {
 
   test("does not log WARN on an intentional stop()", async () => {
     const { calls, logger } = makeRecordingLogger();
-    const pm = createCesProcessManager({ logger });
+    const pm = createCesProcessManager({
+      logger,
+      discover: discoverTestSocket,
+    });
     await pm.start();
 
     await pm.stop();

package/src/credential-execution/process-manager.ts

@@ -1,17 +1,17 @@
 /**
  * CES process manager.
  *
- * Creates transport connections to the CES process — either a CLI-launched
- * sibling over a Unix socket (bare-metal/local), or a managed sidecar over
- * its bootstrap socket (containerized). The process manager owns only the
- * transport connection lifecycle; the CES process itself is managed by the
- * CLI (sibling) or the pod infrastructure (managed).
+ * Creates a transport connection to the CES process over the shared bootstrap
+ * socket. Local CLI siblings and managed sidecars bind the same path under
+ * `CES_BOOTSTRAP_SOCKET_DIR`. The process manager owns only the transport
+ * connection lifecycle; the CES process itself is managed by the CLI
+ * (sibling) or the pod infrastructure (managed).
  *
- * Managed env contract:
- * - CES_BOOTSTRAP_SOCKET  — Path to the bootstrap Unix socket (shared emptyDir)
- * - /assistant-data-ro     — Assistant data mounted read-only into the CES sidecar
- * - /ces-data              — CES private data directory (separate PVC)
- * - CES_HEALTH_PORT        — Health check port exposed by the CES sidecar
+ * Env contract:
+ * - CES_BOOTSTRAP_SOCKET_DIR: directory containing `ces.sock`
+ * - /assistant-data-ro: assistant data mounted read-only into CES
+ * - /ces-data: CES private data directory (separate PVC)
+ * - CES_HEALTH_PORT: health check port exposed by the CES sidecar
  */
 
 import { createConnection, type Socket } from "node:net";
@@ -24,7 +24,6 @@ import {
   discoverCesWithRetry,
   type DiscoveryResult,
   type ManagedDiscoverySuccess,
-  type SiblingDiscoverySuccess,
 } from "./executable-discovery.js";
 
 const log = getLogger("ces-process-manager");
@@ -62,6 +61,12 @@ export interface CesProcessManagerConfig {
 
   /** Logger override. Defaults to the module logger; injected in tests. */
   logger?: PmLogger;
+
+  /**
+   * Socket discovery. Defaults to `discoverCesWithRetry`. Tests inject a
+   * stub that returns a known socket path.
+   */
+  discover?: typeof discoverCesWithRetry;
 }
 
 // ---------------------------------------------------------------------------
@@ -70,7 +75,7 @@ export interface CesProcessManagerConfig {
 
 export interface CesProcessManager {
   /**
-   * Connect to the CES process (sibling socket or managed sidecar socket).
+   * Connect to the CES bootstrap socket.
    * Returns a CesTransport ready for use with createCesClient().
    *
    * Throws if CES is unavailable.
@@ -107,6 +112,7 @@ export function createCesProcessManager(
   config: CesProcessManagerConfig,
 ): CesProcessManager {
   const pmLog = config.logger ?? log;
+  const discover = config.discover ?? discoverCesWithRetry;
   let managedSocket: Socket | null = null;
   let discoveryResult: DiscoveryResult | null = null;
   let running = false;
@@ -119,16 +125,15 @@ export function createCesProcessManager(
         throw new Error("CES process manager is already running");
       }
 
-      // Poll for the socket with a short backoff. Both the managed bootstrap
-      // socket and the CLI-launched sibling socket are bound asynchronously,
-      // so a reconnecting assistant can briefly race the re-bind.
-      discoveryResult = await discoverCesWithRetry();
+      // Poll for the socket with a short backoff. CES binds
+      // asynchronously, so a reconnecting assistant can briefly race
+      // the re-bind.
+      discoveryResult = await discover();
 
       if (discoveryResult.mode === "unavailable") {
         throw new CesUnavailableError(discoveryResult.reason);
       }
 
-      // managed sidecar or CLI-launched sibling — both connect to a socket.
       const transport = await connectManagedSocket(discoveryResult);
       currentTransport = transport;
       wireTransportClose(transport);
@@ -200,11 +205,11 @@ export function createCesProcessManager(
   }
 
   // -------------------------------------------------------------------------
-  // Socket connection — managed sidecar or CLI-launched local sibling
+  // Socket connection
   // -------------------------------------------------------------------------
 
   async function connectManagedSocket(
-    discovery: ManagedDiscoverySuccess | SiblingDiscoverySuccess,
+    discovery: ManagedDiscoverySuccess,
   ): Promise<SocketTransport> {
     pmLog.info(
       { socketPath: discovery.socketPath, mode: discovery.mode },

package/src/daemon/__tests__/conversation-tool-setup.test.ts

@@ -6,6 +6,7 @@
 
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
+import { CONSOLIDATION_ALLOWED_TOOLS } from "../../plugins/defaults/memory/substrate/consolidation-tool-surface.js";
 import type { Conversation } from "../conversation.js";
 import type { ChannelCapabilities } from "../conversation-runtime-assembly.js";
 
@@ -779,3 +780,45 @@ describe("isToolActiveForContext — allowlist-only tools (delete_memory_page)",
     ).toBe(false);
   });
 });
+
+describe("isToolActiveForContext — memory consolidation surface resolves onto the wire", () => {
+  // A background job conversation is not a subagent, so SUBAGENT_ONLY tools
+  // are filtered off before the allowlist applies. Every name the
+  // consolidation run allowlists must survive that gate, or the tool is
+  // silently missing from the run while the allowlist still claims it.
+  const consolidationCtx = () =>
+    makeCtx({
+      subagentAllowedTools: new Set(CONSOLIDATION_ALLOWED_TOOLS),
+      subagentToolGateMode: "wire",
+    });
+
+  test("every allowlisted tool is active for a background conversation", () => {
+    for (const name of CONSOLIDATION_ALLOWED_TOOLS) {
+      expect(isToolActiveForContext(name, consolidationCtx()), name).toBe(true);
+    }
+  });
+
+  test("the shell and the page-delete primitive are on the surface", () => {
+    expect(isToolActiveForContext("bash", consolidationCtx())).toBe(true);
+    expect(
+      isToolActiveForContext("delete_memory_page", consolidationCtx()),
+    ).toBe(true);
+  });
+
+  test("network egress and host-proxy tools stay off the wire", () => {
+    for (const name of [
+      "web_fetch",
+      "web_search",
+      "network_request",
+      "host_bash",
+      "host_file_read",
+      "host_file_write",
+      "host_file_edit",
+      "host_cu",
+    ]) {
+      expect(isToolActiveForContext(name, consolidationCtx()), name).toBe(
+        false,
+      );
+    }
+  });
+});

package/src/daemon/__tests__/turn-tail-deleted-conversation.test.ts

@@ -128,6 +128,7 @@ async function runSettle(): Promise<Message[]> {
     ctx,
     state: {
       lastAssistantMessageId: ASSISTANT_MESSAGE_ID,
+      assistantMessageIdsToSync: new Set(),
       inflightWriters: new Map<string, InflightContentWriter>(),
     },
     rlog,
@@ -169,4 +170,39 @@ describe("settleTurnContent conversation deleted after the terminal SSE", () =>
     expect(diskSyncCalls).toEqual([ASSISTANT_MESSAGE_ID]);
     expect(messages).toEqual(TRUNCATED_MESSAGES);
   });
+
+  test("exports a queued attachment target only once when it is the final row", async () => {
+    const ctx = { conversationId: CONVERSATION_ID, messages: [] as Message[] };
+
+    await settleTurnContent({
+      ctx,
+      state: {
+        lastAssistantMessageId: ASSISTANT_MESSAGE_ID,
+        assistantMessageIdsToSync: new Set([ASSISTANT_MESSAGE_ID]),
+        inflightWriters: new Map<string, InflightContentWriter>(),
+      },
+      rlog,
+    });
+
+    expect(diskSyncCalls).toEqual([ASSISTANT_MESSAGE_ID]);
+  });
+
+  test("exports an earlier attachment target before the final private row", async () => {
+    const ctx = { conversationId: CONVERSATION_ID, messages: [] as Message[] };
+
+    await settleTurnContent({
+      ctx,
+      state: {
+        lastAssistantMessageId: ASSISTANT_MESSAGE_ID,
+        assistantMessageIdsToSync: new Set(["msg-delivered-reply"]),
+        inflightWriters: new Map<string, InflightContentWriter>(),
+      },
+      rlog,
+    });
+
+    expect(diskSyncCalls).toEqual([
+      "msg-delivered-reply",
+      ASSISTANT_MESSAGE_ID,
+    ]);
+  });
 });

package/src/daemon/assistant-attachments.ts

@@ -109,8 +109,8 @@ export function classifyKind(mimeType: string): "image" | "video" | "document" {
 // Validation / cap enforcement
 // ---------------------------------------------------------------------------
 
-interface ValidatedDrafts {
-  accepted: AssistantAttachmentDraft[];
+interface ValidatedDrafts<T extends AssistantAttachmentDraft> {
+  accepted: T[];
   warnings: string[];
 }
 
@@ -119,10 +119,10 @@ interface ValidatedDrafts {
  *
  * - Rejects individual drafts that exceed `MAX_ASSISTANT_ATTACHMENT_BYTES`.
  */
-export function validateDrafts(
-  drafts: AssistantAttachmentDraft[],
-): ValidatedDrafts {
-  const accepted: AssistantAttachmentDraft[] = [];
+export function validateDrafts<T extends AssistantAttachmentDraft>(
+  drafts: T[],
+): ValidatedDrafts<T> {
+  const accepted: T[] = [];
   const warnings: string[] = [];
 
   for (const draft of drafts) {
@@ -800,6 +800,16 @@ function toolNameToFilePrefix(toolName?: string): string {
     .toLowerCase();
 }
 
+/** Shared download name for an image produced by a tool result. */
+export function toolImageFilename(
+  mediaType: string,
+  toolName?: string,
+  title?: string,
+): string {
+  const ext = mediaType.split("/")[1] ?? "png";
+  return `${title || toolNameToFilePrefix(toolName)}.${ext}`;
+}
+
 /**
  * Convert tool content blocks (images/files from tool results) into
  * attachment drafts. Blocks that aren't image or file types are skipped.
@@ -820,12 +830,10 @@ export function contentBlocksToDrafts(
       const src = b.source as ImageBlock["source"];
       const data = src.data;
       const mimeType = src.media_type;
-      const ext = mimeType.split("/")[1] ?? "png";
       const title = typeof b._title === "string" ? b._title : undefined;
-      const prefix = title || toolNameToFilePrefix(toolName);
       drafts.push({
         sourceType: "tool_block",
-        filename: `${prefix}.${ext}`,
+        filename: toolImageFilename(mimeType, toolName, title),
         mimeType,
         dataBase64: data,
         sizeBytes: estimateBase64Bytes(data),
@@ -918,9 +926,9 @@ export function cleanAssistantContent(content: readonly unknown[]): {
  * data from being attached twice when it appears as both a directive tag
  * (user-chosen name) and an auto-converted tool block ("tool-output.png").
  */
-export function deduplicateDrafts(
-  drafts: AssistantAttachmentDraft[],
-): AssistantAttachmentDraft[] {
+export function deduplicateDrafts<T extends AssistantAttachmentDraft>(
+  drafts: T[],
+): T[] {
   const seenKeys = new Set<string>();
   const seenDirectiveHashes = new Set<string>();
   return drafts.filter((d) => {

package/src/daemon/chat-credential-redaction.ts

@@ -10,7 +10,8 @@
  *
  *   1. While a turn runs, every shell-style tool command is scanned for
  *      `credentials reveal` invocations and the referenced credentials
- *      (`--service`/`--field` flags or a positional UUID) are recorded as
+ *      (`--service`/`--field` flags, a positional UUID, or a legacy
+ *      `service/field` path) are recorded as
  *      *candidates* ({@link collectRevealRefsFromCommand}).
  *   2. At persist time, only those candidates' plaintexts are fetched from
  *      the credential store — a scoped read of secrets that were already in
@@ -55,6 +56,7 @@ import {
 } from "../security/secret-scanner.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getCredentialMetadataById } from "../tools/credentials/metadata-store.js";
+import { parseServiceFieldRef } from "../tools/credentials/ref-parse.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("chat-credential-redaction");
@@ -106,6 +108,12 @@ const SERVICE_FLAG_RE = new RegExp(String.raw`--service(?:=|\s+)${FLAG_VALUE}`);
 const FIELD_FLAG_RE = new RegExp(String.raw`--field(?:=|\s+)${FLAG_VALUE}`);
 const UUID_RE =
   /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+// The CLI's single positional argument, directly after `reveal`. A UUID is
+// handled above; anything else is tried as a legacy `service/field` path via
+// the shared grammar in `parseServiceFieldRef`. The route rejects that form
+// as an id today, so no plaintext prints; staging the ref is defense in depth
+// so a future lookup that does succeed is already proof-gated.
+const POSITIONAL_RE = /\breveal\s+([^\s"'\\()<>`-][^\s"'\\()<>`]*)/;
 
 /**
  * Extract a flag's value from a segment, undoing the shell quoting the
@@ -265,6 +273,13 @@ export function collectRevealRefsFromCommand(
       const id = UUID_RE.exec(invocation)?.[0];
       if (id) {
         refs.push({ id });
+        continue;
+      }
+      const positional = POSITIONAL_RE.exec(invocation)?.[1];
+      const pathRef =
+        positional === undefined ? undefined : parseServiceFieldRef(positional);
+      if (pathRef) {
+        refs.push(pathRef);
       }
       // No parseable identity → no ref. The span still gets redacted at
       // persist; it just won't be revealable.