@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/tools/skills/scaffold-managed.ts

@@ -5,6 +5,7 @@ import type { SkillSource } from "../../config/skills.js";
 import { loadSkillCatalog } from "../../config/skills.js";
 import { refreshSkillCapabilityMemories } from "../../daemon/skill-memory-refresh.js";
 import { emitNotificationSignal } from "../../notifications/emit-signal.js";
+import { sanitizeMultilineMessagePreview } from "../../notifications/notification-utils.js";
 import { getConversation } from "../../persistence/conversation-crud.js";
 import { upsertSkillCardInsertJob } from "../../persistence/jobs-store.js";
 import { MEMORY_RETROSPECTIVE_ORIGIN } from "../../plugins/defaults/memory/memory-retrospective-constants.js";
@@ -37,6 +38,14 @@ function sanitizeFrontmatterValue(value: string): string {
 const MISSING_ACTIVATION_HINTS =
   'activation_hints is required: pass 1-4 short trigger phrases stating the intent this skill serves (for example "user asks to deploy staging") so it can be found later by intent, not just by name.';
 
+/**
+ * Self-correcting error for a background overwrite of an existing skill with
+ * no change summary. The schema cannot express the condition (a create and a
+ * user-directed edit need none), so the executor is the enforcement point.
+ */
+const MISSING_CHANGE_SUMMARY =
+  'change_summary is required when updating an existing skill: pass one or two short sentences (under 200 characters) for the person who reads the "Skill updated" notice, naming what you changed and what in the trace prompted it (for example "Added the retry after an expired session and the export endpoint that held steady.").';
+
 /**
  * Validate + normalize a string-array input (sanitize, drop blanks, dedupe).
  * Returns `{ error }` on the first invalid element, or `{ value }` holding
@@ -90,6 +99,12 @@ function normalizeOptionalStringArray(
  * scheduled jobs, heartbeat), where a user already looks to see what the
  * assistant did on its own.
  *
+ * `changeSummary` is the pass's own account of what it changed and is the
+ * notice's body: the feed item is the only place the change surfaces, and a
+ * reader triaging it there has no diff to look at, so a notice that only
+ * names the skill sends them into the skill to find out what happened. The
+ * executor refuses the overwrite without one, so this never runs without it.
+ *
  * `sourceContextId` is a conversation id so the feed item's "Go to Convo"
  * target resolves (see `home-feed-side-effect.ts`, which looks it up via
  * `getConversation`): the source conversation when lineage resolved, else the
@@ -102,6 +117,7 @@ function notifyBackgroundSkillUpdate(args: {
   skillId: string;
   name: string;
   conversationId: string;
+  changeSummary: string;
 }): void {
   const day = new Date().toISOString().slice(0, 10);
   void emitNotificationSignal({
@@ -121,13 +137,13 @@ function notifyBackgroundSkillUpdate(args: {
       // background, no interruption) leaves the feed writer with no summary
       // and it skips the item entirely, so the quiet case would surface
       // nothing at all.
-      summary: `Updated the skill "${args.name}" from something learned in an earlier conversation.`,
+      summary: args.changeSummary,
       // Named, not just "Skill updated": the feed sits several rows deep and
       // a generic title is unscannable next to entries that name their
       // subject (`Background job failed: memory.v2.sweep`). The word "Skill"
       // stays because a bare skill name does not always read as one.
       title: `Skill updated: ${args.name}`,
-      body: `Updated the skill "${args.name}" from something learned in an earlier conversation.`,
+      body: args.changeSummary,
       skillId: args.skillId,
     },
     attentionHints: {
@@ -313,6 +329,24 @@ export async function executeScaffoldManagedSkill(
     }
   }
 
+  // The update notice's body. Model-authored text bound for a notification
+  // surface, so it gets the same control-character strip and preview clamp as
+  // any other producer-supplied body; blank collapses to absent so the
+  // requirement below treats it as missing rather than posting an empty notice.
+  let changeSummary: string | undefined;
+  if (input.change_summary !== undefined) {
+    if (typeof input.change_summary !== "string") {
+      return {
+        content: "Error: change_summary must be a string",
+        isError: true,
+      };
+    }
+    const sanitized = sanitizeMultilineMessagePreview(input.change_summary);
+    if (sanitized) {
+      changeSummary = sanitized;
+    }
+  }
+
   const id = skillId.trim();
   const fromRetrospective =
     context.requestOrigin === MEMORY_RETROSPECTIVE_ORIGIN;
@@ -366,6 +400,24 @@ export async function executeScaffoldManagedSkill(
     }
   }
 
+  // A background overwrite announces itself through the notice built in
+  // notifyBackgroundSkillUpdate, whose body is this summary, so the write is
+  // refused without one. The error returns to the pass in the same turn and
+  // it retries with the field, the way a missing activation_hints does.
+  // Checked after the ownership backstop so a pass that may not touch the
+  // skill hears that first, and only for a call that asked to overwrite: a
+  // call without the flag is blocked by the managed store's own overwrite
+  // error, and hearing about the summary instead would cost it a retry that
+  // still cannot succeed. Before any write, so nothing is lost.
+  if (
+    fromRetrospective &&
+    managedSkillExistedBefore &&
+    input.overwrite === true &&
+    !changeSummary
+  ) {
+    return { content: `Error: ${MISSING_CHANGE_SUMMARY}`, isError: true };
+  }
+
   // Conversation lineage (retrospective origin only). The retrospective runs
   // in a background fork of the conversation it distilled the procedure from,
   // so the fork's parent is this skill's durable source conversation.
@@ -450,11 +502,17 @@ export async function executeScaffoldManagedSkill(
   // skill.
   const notifyConversationId =
     sourceConversationId ?? retrospectiveConversationId;
-  if (fromRetrospective && managedSkillExistedBefore && notifyConversationId) {
+  if (
+    fromRetrospective &&
+    managedSkillExistedBefore &&
+    notifyConversationId &&
+    changeSummary
+  ) {
     notifyBackgroundSkillUpdate({
       skillId: id,
       name: normalizedName,
       conversationId: notifyConversationId,
+      changeSummary,
     });
   }
 

package/src/tools/subagent/spawn.ts

@@ -484,9 +484,9 @@ function spawnCancelledResult(label: string): ToolExecutionResult {
  * repeat-spawn guard folds, so a consult has to record it the same way every
  * other spawn does or the guard could never match one consult against another.
  *
- * The context pack is best effort: the parent conversation is looked up only
- * for its warm skill catalog, so an unresolvable one (e.g. evicted) costs the
- * skills section of the pack and nothing else.
+ * The context pack is best effort: each section independently falls back to
+ * null on failure, so a missing workspace or empty catalog costs only that
+ * section, never the consult.
  *
  * The budget is the advisor's alone. It is the only spawn the agent may issue
  * unprompted and the only one that runs on the premium profile, so it is the
@@ -502,21 +502,18 @@ async function buildAdvisorFields(
   maxRuntimeMs: number;
   maxToolCalls: number;
 }> {
-  const parentConversation = findConversation(context.conversationId);
   // Situational awareness for the advisor: the parent's live tool set, the
   // full skill catalog, and its workspace. Assembled off the per-turn
   // ToolContext snapshot (trust, channel) so the personal-memory sections are
   // gated exactly like the runtime injectors. A null pack just means the
-  // consult runs on the brief alone.
+  // consult runs on the brief alone. Skills come from a fresh
+  // `loadSkillCatalog()` inside the context pack, not a conversation snapshot.
   const situationalContext = await buildAdvisorContext({
     conversationId: context.conversationId,
     workingDir: context.workingDir,
     allowedToolNames: context.allowedToolNames,
     trustClass: context.trustClass,
     enabledPluginSet: context.enabledPluginSet,
-    // The parent's warm per-turn catalog keeps the synchronous on-disk catalog
-    // scan out of the spawn path.
-    skillCatalog: parentConversation?.skillProjectionCache?.catalog,
   });
   return {
     requestText: advisorRequestText(objective, situationalContext),

package/src/tools/terminal/__tests__/sanitized-bash.test.ts

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { runSanitizedBash } from "../sanitized-bash.js";
+
+describe("runSanitizedBash", () => {
+  const priorToken = process.env.CES_SERVICE_TOKEN;
+  const priorSocket = process.env.CES_LOCAL_SOCKET;
+
+  afterEach(() => {
+    if (priorToken == null) {
+      delete process.env.CES_SERVICE_TOKEN;
+    } else {
+      process.env.CES_SERVICE_TOKEN = priorToken;
+    }
+    if (priorSocket == null) {
+      delete process.env.CES_LOCAL_SOCKET;
+    } else {
+      process.env.CES_LOCAL_SOCKET = priorSocket;
+    }
+  });
+
+  test("runs a command and returns stdout", async () => {
+    const result = await runSanitizedBash("echo hello", 5_000);
+    expect(result.error).toBeUndefined();
+    expect(result.timedOut).toBe(false);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe("hello");
+  });
+
+  test("forwards CES_SERVICE_TOKEN to the child", async () => {
+    process.env.CES_SERVICE_TOKEN = "vault-bearer";
+    const result = await runSanitizedBash("printenv CES_SERVICE_TOKEN", 5_000);
+    expect(result.error).toBeUndefined();
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe("vault-bearer");
+  });
+
+  test("forwards CES_LOCAL_SOCKET to the child", async () => {
+    process.env.CES_LOCAL_SOCKET = "/tmp/ces.sock";
+    const result = await runSanitizedBash("printenv CES_LOCAL_SOCKET", 5_000);
+    expect(result.error).toBeUndefined();
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout.trim()).toBe("/tmp/ces.sock");
+  });
+
+  test("times out a hung command", async () => {
+    const result = await runSanitizedBash("sleep 5", 200);
+    expect(result.error).toBeUndefined();
+    expect(result.timedOut).toBe(true);
+  });
+
+  test("rejects an empty command", async () => {
+    const result = await runSanitizedBash("");
+    expect(result.error).toBe("command is required");
+    expect(result.exitCode).toBeNull();
+  });
+});

package/src/tools/terminal/sanitized-bash.ts

@@ -0,0 +1,105 @@
+/**
+ * Spawn a shell command with the same sanitized environment the bash tool
+ * forwards to tool-call subprocesses.
+ *
+ * Used by `assistant bash` so a CLI invocation sees the same allowlisted
+ * env, workspace cwd, and platform shell as a bash tool call, without
+ * round-tripping through the assistant HTTP or IPC API.
+ */
+
+import { spawn } from "node:child_process";
+
+import {
+  buildShellInvocation,
+  terminateProcessTree,
+} from "../../util/host-process.js";
+import { getWorkspaceDir } from "../../util/platform.js";
+import { buildSanitizedEnv } from "./safe-env.js";
+
+export const DEFAULT_SANITIZED_BASH_TIMEOUT_MS = 30_000;
+
+export interface SanitizedBashResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  timedOut: boolean;
+  error?: string;
+}
+
+export function runSanitizedBash(
+  command: string,
+  timeoutMs: number = DEFAULT_SANITIZED_BASH_TIMEOUT_MS,
+): Promise<SanitizedBashResult> {
+  if (!command) {
+    return Promise.resolve({
+      stdout: "",
+      stderr: "",
+      exitCode: null,
+      timedOut: false,
+      error: "command is required",
+    });
+  }
+
+  const effectiveTimeout =
+    typeof timeoutMs === "number" && timeoutMs > 0
+      ? timeoutMs
+      : DEFAULT_SANITIZED_BASH_TIMEOUT_MS;
+
+  return new Promise<SanitizedBashResult>((resolve) => {
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
+    let timedOut = false;
+    let settled = false;
+
+    const finish = (result: SanitizedBashResult) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(result);
+    };
+
+    const wrapped = buildShellInvocation(command);
+    const child = spawn(wrapped.command, wrapped.args, {
+      cwd: getWorkspaceDir(),
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: true,
+      env: buildSanitizedEnv(),
+      windowsHide: true,
+    });
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      terminateProcessTree(child);
+    }, effectiveTimeout);
+
+    child.stdout.on("data", (data: Buffer) => {
+      stdoutChunks.push(data);
+    });
+
+    child.stderr.on("data", (data: Buffer) => {
+      stderrChunks.push(data);
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      finish({
+        stdout: Buffer.concat(stdoutChunks).toString(),
+        stderr: Buffer.concat(stderrChunks).toString(),
+        exitCode: code,
+        timedOut,
+      });
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      finish({
+        stdout: "",
+        stderr: "",
+        exitCode: null,
+        timedOut: false,
+        error: err.message,
+      });
+    });
+  });
+}

package/src/tools/ui-surface/channel-variants.ts

@@ -1,68 +1,19 @@
 /**
- * Per-conversation wire projections of the UI surface tool definitions.
+ * Conversation-stable wire projections of the UI surface tool definitions.
  *
- * Slack renders exactly one surface — the task_progress card (everything else
- * is rejected at execution; see `isSlackTaskProgressUiException` in
- * `daemon/conversation-surfaces.ts`) — so Slack conversations get a `ui_show`
- * variant documenting only that shape instead of the full multi-surface docs.
- * Activation-rail conversations additionally get the `activation_moment`
- * telemetry param, which no other conversation pays schema tokens for (the
- * emit path is gated on `isActivationSession` regardless).
+ * `ui_show`, `ui_update`, and `ui_dismiss` keep one definition across every
+ * channel and across live vs clientless turns. Channel renderers enforce the
+ * surfaces they can display at execution. Clientless calls persist surface
+ * content for the next capable client that opens the conversation.
  *
- * Projection contract: shared definition objects are never mutated (variants
- * are module-level constants swapped in via spread-copy), and the projected
- * set is a pure function of per-conversation-stable state, so a
- * conversation's tools+system prompt-cache prefix stays stable across turns.
+ * `activation_moment` is the remaining schema projection. It applies only to
+ * activation-rail conversations, whose marker is written before the first
+ * tool resolution, so the extra property is stable for that conversation's
+ * lifetime. It must not vary by channel or turn presence.
  */
 
 import type { ToolDefinition } from "../../providers/types.js";
 import { ACTIVATION_MOMENT_PARAMS } from "../../telemetry/activation-funnel.js";
-import { TASK_PROGRESS_TEMPLATE_SHAPE } from "./surface-shape-docs.js";
-
-const SLACK_UI_SHOW_DESCRIPTION = `Show a live task-progress card for the current work — the only surface this channel renders. data: { template: "task_progress", templateData: ${TASK_PROGRESS_TEMPLATE_SHAPE} }. Show it early on multi-step turns and advance step statuses via ui_update as work progresses.`;
-
-const SLACK_UI_SHOW_INPUT_SCHEMA = {
-  type: "object",
-  properties: {
-    surface_type: {
-      type: "string",
-      enum: ["card"],
-      description: "Always card on this channel",
-    },
-    title: {
-      type: "string",
-      description: "Optional surface title",
-    },
-    data: {
-      type: "object",
-      description:
-        'Card data: { template: "task_progress", templateData: { title, status, steps } }',
-    },
-  },
-  required: ["surface_type", "data"],
-};
-
-/**
- * Swap UI surface tool definitions for channel-appropriate variants. Returns
- * the input array unchanged (same identity) for channels without a variant.
- */
-export function projectUiToolsForChannel(
-  definitions: ToolDefinition[],
-  channel: string | undefined,
-): ToolDefinition[] {
-  if (channel !== "slack") {
-    return definitions;
-  }
-  return definitions.map((def) =>
-    def.name === "ui_show"
-      ? {
-          ...def,
-          description: SLACK_UI_SHOW_DESCRIPTION,
-          input_schema: SLACK_UI_SHOW_INPUT_SCHEMA,
-        }
-      : def,
-  );
-}
 
 const ACTIVATION_MOMENT_PROPERTY = {
   type: "string",
@@ -73,7 +24,7 @@ const ACTIVATION_MOMENT_PROPERTY = {
 
 /**
  * Add the optional `activation_moment` param to ui_show's schema. Applied
- * only for activation-rail conversations (`isActivationSession`) — the rail
+ * only for activation-rail conversations (`isActivationSession`). The rail
  * bootstrap prompt instructs the tagging, and the daemon's emit path reads
  * the tag from tool input independently of this schema.
  */

package/src/tools/watch/watch-retro-report.ts

@@ -14,14 +14,6 @@ import type {
 /**
  * How a watch retrospective hands its report to the daemon.
  *
- * **The card cannot come from `ui_show`.** A retrospective runs as a
- * `clientless` wake, which pins the turn non-interactive, and
- * `conversation-tool-setup` gates the whole `ui_surface` tool family on a
- * client being present (`return channelCapabilities?.supportsDynamicUi ??
- * !hasNoClient`). So `ui_show` is not merely denied in this turn, it is absent
- * from the tool set, and a retrospective told to call it can only report that
- * it cannot. This tool is an ordinary one and passes that gate untouched.
- *
  * **It records; it does not render.** The executor validates the payload and
  * returns, and nothing here writes to the conversation. What makes the card is
  * `watch-retro.ts` reading this call back out of the turn's own history once

package/src/types/host-capabilities.ts

@@ -16,6 +16,7 @@ export const HOST_PROXY_CAPABILITIES = [
   "host_file",
   "host_cu",
   "host_cu_window_capture",
+  "host_cu_sequence",
   "host_cu_annotate",
   "host_browser",
   "host_app_control",
@@ -24,11 +25,12 @@ export const HOST_PROXY_CAPABILITIES = [
 
 export type HostProxyCapability = (typeof HOST_PROXY_CAPABILITIES)[number];
 
-/** Every host capability except the three macOS-only ones. */
+/** Every host capability except the macOS-only ones. */
 const DESKTOP_SHARED_CAPABILITIES = HOST_PROXY_CAPABILITIES.filter(
   (capability) =>
     capability !== "host_app_control" &&
     capability !== "host_cu_window_capture" &&
+    capability !== "host_cu_sequence" &&
     capability !== "host_cu_annotate",
 );
 
@@ -47,8 +49,8 @@ export type HostProxyInterfaceId = "macos" | "windows" | "linux";
  * (web, ios, android, and every messaging transport) provide none.
  *
  * Windows and Linux run the same host proxy as macOS minus app control. The
- * two window-scoped CU capabilities ride the host_cu transport and are
- * negotiated per connection; only the macOS native helper answers them, so a
+ * negotiated CU capabilities ride the host_cu transport and are claimed per
+ * connection; only the macOS native helper answers them, so a
  * request elsewhere would reach that helper as an unknown action.
  *
  * macOS additionally provisions its `host_browser` proxy via the assistant

package/src/util/__tests__/language-subtag.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from "bun:test";
 
-import { baseLanguageSubtag, localizedOrDefault } from "../language-subtag.js";
+import {
+  baseLanguageSubtag,
+  fixedPhraseLanguage,
+  localizedOrDefault,
+} from "../language-subtag.js";
 
 describe("baseLanguageSubtag", () => {
   test("lowercases a bare tag", () => {
@@ -52,3 +56,21 @@ describe("localizedOrDefault", () => {
     expect(localizedOrDefault(table, "__proto__", "fallback")).toBe("fallback");
   });
 });
+
+describe("fixedPhraseLanguage", () => {
+  const table = { en: "one", es: "uno" };
+
+  test("pins English when the speaker's language has no table entry", () => {
+    expect(fixedPhraseLanguage(table, "ko")).toBe("en");
+    expect(fixedPhraseLanguage(table, "ar-EG")).toBe("en");
+  });
+
+  test("rides the speaker's language when the table covers it", () => {
+    expect(fixedPhraseLanguage(table, "es")).toBeUndefined();
+    expect(fixedPhraseLanguage(table, "es-419")).toBeUndefined();
+  });
+
+  test("carries no hint when the language is unknown", () => {
+    expect(fixedPhraseLanguage(table, undefined)).toBeUndefined();
+  });
+});

package/src/util/ca-bundle.ts

@@ -0,0 +1,13 @@
+import { readFile, writeFile } from "node:fs/promises";
+
+export async function writeCombinedCABundle(
+  systemBundlePath: string,
+  extraCAPath: string,
+  outputPath: string,
+): Promise<void> {
+  const [systemCAs, extraCAs] = await Promise.all([
+    readFile(systemBundlePath, "utf-8"),
+    readFile(extraCAPath, "utf-8"),
+  ]);
+  await writeFile(outputPath, `${systemCAs}\n${extraCAs}`, { mode: 0o644 });
+}

package/src/util/language-subtag.ts

@@ -41,3 +41,19 @@ export function localizedOrDefault<T>(
     ? (table[baseLanguageSubtag(language)!] as T)
     : fallback;
 }
+
+/**
+ * The TTS language hint for a fixed phrase picked from a localized table:
+ * "en" when the speaker has a language the table does not cover (the
+ * picker fell back to English text, which must not be synthesized under
+ * an ar/ko/ta hint), undefined otherwise (the phrase rides the speaker's
+ * language, or carries no hint at all when the language is unknown).
+ */
+export function fixedPhraseLanguage(
+  table: Readonly<Record<string, unknown>>,
+  language: string | undefined,
+): string | undefined {
+  return language !== undefined && !hasLocalizedEntry(table, language)
+    ? "en"
+    : undefined;
+}

package/src/util/platform.ts

@@ -470,6 +470,14 @@ export function getWorkspaceConfigPath(): string {
   return join(getWorkspaceDir(), "config.json");
 }
 
+/** Filename for the user-owned Agent Plugins MCP document. */
+export const WORKSPACE_MCP_FILENAME = "mcp.json";
+
+/** Returns $VELLUM_WORKSPACE_DIR/mcp.json */
+export function getWorkspaceMcpConfigPath(): string {
+  return join(getWorkspaceDir(), WORKSPACE_MCP_FILENAME);
+}
+
 /** Returns $VELLUM_WORKSPACE_DIR/skills */
 export function getWorkspaceSkillsDir(): string {
   return join(getWorkspaceDir(), "skills");

package/src/util/unicode.ts

@@ -126,6 +126,15 @@ export interface DeepSanitizeResult<T> {
   fixedStringCount: number;
 }
 
+export interface DeepSanitizeOptions {
+  /**
+   * Skip a plain-object property entirely: its value is neither scanned nor
+   * copied. For fields known to hold ASCII (base64 payloads), scanning is
+   * pure cost.
+   */
+  skipKey?: (key: string, parent: Record<string, unknown>) => boolean;
+}
+
 /**
  * Recursively walk arrays and plain objects, replacing orphaned surrogates in
  * every string value. Non-plain objects (class instances, Date, Buffer, Map,
@@ -136,8 +145,10 @@ export interface DeepSanitizeResult<T> {
  */
 export function stripOrphanedSurrogatesDeep<T>(
   input: T,
+  options: DeepSanitizeOptions = {},
 ): DeepSanitizeResult<T> {
   let fixedStringCount = 0;
+  const { skipKey } = options;
 
   const walk = (value: unknown): { value: unknown; changed: boolean } => {
     if (typeof value === "string") {
@@ -178,7 +189,10 @@ export function stripOrphanedSurrogatesDeep<T>(
       let next: Record<string, unknown> | null = null;
       for (let i = 0; i < keys.length; i++) {
         const key = keys[i]!;
-        const result = walk(source[key]);
+        const result =
+          skipKey?.(key, source) === true
+            ? { value: source[key], changed: false }
+            : walk(source[key]);
         if (result.changed && next === null) {
           next = {};
           for (let j = 0; j < i; j++) {

package/src/watch/watch-retro.ts

@@ -61,14 +61,12 @@ const WATCH_RETRO_WAKE_SOURCE = "watch-retro";
  * under the `watch_retro` template, which the client draws as a paged card: the
  * record on the first page, one question per page after it.
  *
- * **The daemon appends the card; the model never reaches `ui_show`.** This wake
- * is `clientless`, and `conversation-tool-setup` gates the whole `ui_surface`
- * family on a client being present, so `ui_show` is absent from this turn's
- * tool set rather than merely denied. A retrospective told to call it can only
- * report that it cannot. `watch_retro_report` is an ordinary tool and passes
- * that gate, and the surface is appended here, the way the memory
- * retrospective's `skill_card` is appended by the daemon rather than requested
- * by the model.
+ * **The daemon appends the card; the model calls `watch_retro_report`.** This
+ * wake is `clientless`. `ui_show` stays on the wire so background surfaces can
+ * persist, but this flow still reports through `watch_retro_report` so the
+ * daemon can append the card after the turn ends. The memory retrospective's
+ * `skill_card` is appended the same way: the daemon writes the surface, the
+ * model does not request it.
  *
  * **The append waits for the turn to end.** A `ui_surface` row written mid-turn
  * can land between a persisted `tool_use` and its `tool_result`, an ordering

package/src/watch/watch-timeline.ts

@@ -366,8 +366,8 @@ export function appendNarration(
  * timeline of a session where observation stalled is simply a sparser one.
  *
  * The screenshot is stored only when `attachScreenshot` asks for it, and
- * carrying one is not asking. The host captures a screenshot on every observe
- * with no opt-out, so an observation always has pixels available and a policy
+ * carrying one is not asking. Watch requests a screenshot on every observe, so
+ * an observation normally has pixels available and a policy
  * of "store what arrives" is a policy of storing every frame. Which frames are
  * worth an image is a cadence decision, and it belongs to the caller driving
  * the session rather than to the row writer.

package/src/workflows/run-manager.ts

@@ -33,6 +33,7 @@ import type { TrustContext } from "../daemon/trust-context-types.js";
 import { wakeAgentForOpportunity } from "../runtime/agent-wake.js";
 import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import { getLogger } from "../util/logger.js";
+import { safeStringSlice } from "../util/unicode.js";
 import type { CapabilityManifest } from "./capabilities.js";
 import {
   normalizeCapabilityManifest,
@@ -611,7 +612,7 @@ function truncateForSummary(s: string, runId: string): string {
   }
   const omitted = s.length - MAX_SUMMARY_RESULT_CHARS;
   return (
-    `${s.slice(0, MAX_SUMMARY_RESULT_CHARS)}… ` +
+    `${safeStringSlice(s, 0, MAX_SUMMARY_RESULT_CHARS)}… ` +
     `[truncated ${omitted} chars — fetch the full result with manage_workflows ` +
     `{ action: "get_result", run_id: "${runId}" }]`
   );