@vellumai/assistant 0.7.2 → 0.8.0

package/ARCHITECTURE.md

@@ -21,6 +21,20 @@ This document owns assistant-runtime architecture details. The repo-level archit
 - Voice calls mirror the same prompt contract: `CallController` receives guardian context on setup and refreshes it immediately after successful voice challenge verification, so the first post-verification turn is grounded as `actor_role: guardian`.
 - Voice-specific behavior (DTMF/speech verification flow, relay state machine) remains voice-local; only actor-role resolution is shared.
 
+### Safe Storage Limits
+
+Safe storage limits are gated by the assistant feature flag `safe-storage-limits`, default off. When the flag is off, the disk pressure guard reports a disabled status and no runtime path blocks work, injects cleanup guidance, or changes tool access.
+
+**Disk pressure state:** `src/daemon/disk-pressure-guard.ts` samples workspace storage usage every 60 seconds through `src/util/disk-usage.ts`. At or above the 95% critical threshold it creates an in-memory lock with `lockId`, usage snapshot, `acknowledged`, `overrideActive`, `effectivelyLocked`, and the blocked capabilities `agent-turns`, `background-work`, and `remote-ingress`. The lock clears when usage drops below the threshold or the process restarts. `acknowledgeDiskPressureLock()` only lets the guardian enter cleanup mode; `overrideDiskPressureLock()` requires the exact phrase `I understand the risks` and disables the effective lock while usage remains critical.
+
+**Runtime API and events:** `src/runtime/routes/disk-pressure-routes.ts` exposes `GET /v1/disk-pressure/status`, `POST /v1/disk-pressure/acknowledge`, and `POST /v1/disk-pressure/override`. Route auth policies require normal runtime protection, and `disk_pressure_status_changed` events are emitted when the status changes so clients can update live.
+
+**Turn policy:** `src/daemon/disk-pressure-policy.ts` classifies turns before the main agent loop. Local guardian/owner turns are allowed in cleanup mode; trusted contacts, non-guardian actors, unknown remote senders, background conversations, direct wakes, and non-main LLM call sites are blocked while `effectivelyLocked` is true. Blocked turns emit terminal conversation errors rather than reaching the provider.
+
+**Background work:** Heartbeats, scheduled tasks, filing work, retry sweeps, and background tool completions call `src/daemon/disk-pressure-background-gate.ts` before starting work. While effectively locked they skip the wake or job and log throttled disk-pressure fields.
+
+**Prompt and tools:** Cleanup-mode turns carry `diskPressureContext` through runtime assembly and receive the `<disk_pressure_warning>` injector in `src/plugins/defaults/injectors.ts`. The instruction tells the assistant to warn first, focus only on freeing storage, inspect before deleting, ask for deletion approval, and explain that background processes and trusted-contact messages are blocked. Tool setup marks the turn as cleanup mode; `src/tools/tool-approval-handler.ts` rejects non-cleanup-safe tools, and foreground shell inspection remains available while background `bash` and `host_bash` modes are rejected. When a new lock is created, active background terminal tools are cancelled with reason `disk_pressure`.
+
 ### Single-Header JWT Auth Model
 
 All HTTP API requests use a single `Authorization: Bearer <jwt>` header for authentication. The JWT carries identity, permissions, and policy versioning in a unified token.
@@ -966,6 +980,7 @@ The daemon emits two distinct error message types via SSE:
 | -------------------------------- | ----------------------------------------------------------------------- | --------- |
 | `PROVIDER_NETWORK`               | Unable to reach the LLM provider (connection refused, timeout, DNS)     | Yes       |
 | `PROVIDER_RATE_LIMIT`            | LLM provider rate-limited the request (HTTP 429)                        | Yes       |
+| `MANAGED_USAGE_LIMIT`            | Vellum managed inference usage limit or quota was exceeded (HTTP 429)   | Yes       |
 | `PROVIDER_API`                   | Provider returned a server error (5xx) or retryable 4xx                 | Yes       |
 | `PROVIDER_BILLING`               | Invalid/expired API key or insufficient credits (HTTP 401, billing 4xx) | No        |
 | `CONTEXT_TOO_LARGE`              | Request exceeds the model's context window (HTTP 413, token limit)      | No        |
@@ -980,7 +995,7 @@ The daemon classifies errors via `classifyConversationError()` in `conversation-
 
 Classification uses a two-tier strategy:
 
-1. **Structured provider errors**: If the error is a `ProviderError` with a `statusCode`, the status code determines the category deterministically — `413` maps to `CONTEXT_TOO_LARGE` (not retryable), `401` maps to `PROVIDER_BILLING` (not retryable, invalid/expired key), `429` maps to `PROVIDER_RATE_LIMIT` (retryable), `5xx` to `PROVIDER_API` (retryable), other `4xx` to `PROVIDER_API` (retryable) unless a message pattern matches a more specific non-retryable category (context-too-large, billing/auth).
+1. **Structured provider errors**: If the error is a `ProviderError` with a `statusCode`, the status code determines the category deterministically — `413` maps to `CONTEXT_TOO_LARGE` (not retryable), `401` maps to `PROVIDER_BILLING` (not retryable, invalid/expired key), `429` maps to `MANAGED_USAGE_LIMIT` when the provider is routed through the managed proxy or the payload matches a Vellum managed quota/limit response, otherwise `PROVIDER_RATE_LIMIT` (retryable), `5xx` to `PROVIDER_API` (retryable), other `4xx` to `PROVIDER_API` (retryable) unless a message pattern matches a more specific non-retryable category (context-too-large, billing/auth).
 2. **Regex fallback**: For non-provider errors or `ProviderError` without a status code, regex pattern matching against the error message detects network failures, rate limits, and API errors. Phase-specific overrides handle regeneration contexts.
 
 Debug details are capped at 4,000 characters to prevent oversized payloads.
@@ -1263,7 +1278,7 @@ graph TB
 - Managed-store writes are atomic (tmp file + rename) to prevent partial `SKILL.md` or `SKILLS.md` files.
 - After persist or delete, the file watcher triggers conversation eviction; the next turn runs in a fresh conversation. The model's system prompt instructs it to continue normally.
 - macOS UI shows Inspect and Delete controls for managed skills only (source = "managed").
-- `skill_load` validates the recursive include graph (via `include-graph.ts`) before emitting output. Missing children and cycles produce `isError: true` with no `<loaded_skill>` marker. Valid includes produce an "Included Skills (immediate)" metadata section showing child ID, name, description, and path.
+- `skill_load` resolves the recursive include graph (via `include-graph.ts`) before emitting output. Missing children are listed as suggested skills without child `<loaded_skill>` markers; cycles still produce `isError: true` with no marker. Valid includes produce an "Included Skills (immediate)" metadata section showing child ID, name, description, and path.
 
 ### Skills Authoring via HTTP
 
@@ -1274,32 +1289,33 @@ The Skills page in the macOS client can author managed skills through the daemon
 
 ### Include Graph Validation
 
-Skills can declare child relationships via the `includes` frontmatter field (a JSON array of skill IDs). When `skill_load` loads a parent skill, it validates the full recursive include graph before emitting output.
+Skills can declare child relationships via the `includes` frontmatter field (a JSON array of skill IDs). When `skill_load` loads a parent skill, it attempts to resolve and auto-install missing includes before emitting output. Available includes are appended to the loaded skill output; unavailable includes are surfaced as suggestions instead of blocking the parent skill.
 
 ```mermaid
 graph LR
     LOAD["skill_load(parent)"] --> CATALOG["loadSkillCatalog()"]
     CATALOG --> INDEX["indexCatalogById()"]
-    INDEX --> VALIDATE["validateIncludes(rootId, index)"]
-    VALIDATE -->|"ok"| OUTPUT["Emit output +<br/>Included Skills (immediate)<br/>+ loaded_skill marker"]
-    VALIDATE -->|"missing child"| ERR_MISSING["isError: true<br/>no loaded_skill marker"]
-    VALIDATE -->|"cycle detected"| ERR_CYCLE["isError: true<br/>no loaded_skill marker"]
+    INDEX --> AUTOINSTALL["Attempt catalog auto-install<br/>for missing includes"]
+    AUTOINSTALL --> RESOLVE["collectAllMissing(rootId, index)<br/>+ validateIncludeCycles(rootId, index)"]
+    RESOLVE -->|"ok + no missing child"| OUTPUT["Emit output +<br/>Included Skills (immediate)<br/>+ loaded_skill markers"]
+    RESOLVE -->|"ok + missing child"| OUTPUT_MISSING["Emit parent output +<br/>Suggested Included Skills<br/>without child markers"]
+    RESOLVE -->|"cycle detected"| ERR_CYCLE["isError: true<br/>no loaded_skill marker"]
 ```
 
 **Validation rules:**
 
-- **Missing children**: If any skill in the recursive graph references an `includes` ID not found in the catalog, validation fails with the full path from root to the missing reference.
+- **Missing children**: Missing includes trigger catalog auto-install attempts. Any include still unavailable is listed under "Suggested Included Skills (not loaded)" and does not receive a `<loaded_skill>` marker.
 - **Cycles**: Three-state DFS (unseen → visiting → done) detects direct and indirect cycles. The error includes the cycle path.
-- **Fail-closed**: On any validation error, `skill_load` returns `isError: true` with no `<loaded_skill>` marker, preventing the agent from using a skill with broken dependencies.
+- **Fail-closed cycles**: Circular include chains still return `isError: true` with no `<loaded_skill>` marker.
 
-**Key constraint**: Include metadata is metadata-only. Child skills are **not** auto-activated — the agent must explicitly call `skill_load` for each child. The `projectSkillTools()` function only projects tools for skills with explicit `<loaded_skill>` markers in conversation history.
+**Key constraint**: Include metadata is advisory. Available included skills are appended to the parent output and receive explicit `<loaded_skill>` markers; unavailable included skills remain suggestions so the agent can search for and install them if the task needs their guidance or tools.
 
-| Source File                             | Purpose                                                                                    |
-| --------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `assistant/src/skills/include-graph.ts` | `indexCatalogById()`, `getImmediateChildren()`, `validateIncludes()`, `traverseIncludes()` |
-| `assistant/src/tools/skills/load.ts`    | Include validation integration in `skill_load` execute path                                |
-| `assistant/src/config/skills.ts`        | `includes` field parsing from SKILL.md frontmatter                                         |
-| `assistant/src/skills/managed-store.ts` | `includes` emission in `buildSkillMarkdown()`                                              |
+| Source File                             | Purpose                                                                                                               |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `assistant/src/skills/include-graph.ts` | `indexCatalogById()`, `getImmediateChildren()`, `validateIncludes()`, `validateIncludeCycles()`, `traverseIncludes()` |
+| `assistant/src/tools/skills/load.ts`    | Include resolution integration in `skill_load` execute path                                                           |
+| `assistant/src/config/skills.ts`        | `includes` field parsing from SKILL.md frontmatter                                                                    |
+| `assistant/src/skills/managed-store.ts` | `includes` emission in `buildSkillMarkdown()`                                                                         |
 
 ---
 
@@ -1538,19 +1554,19 @@ Every layer in the pipeline defaults to rejection rather than silent degradation
 
 ### Key Source Files
 
-| File                                                | Role                                                                                       |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `assistant/src/config/skills.ts`                    | Skill catalog loading: bundled, managed, workspace, extra directories                      |
-| `assistant/src/config/bundled-skills/`              | Bundled skill directories (browser, gmail, computer-use, weather, etc.)                    |
-| `assistant/src/skills/tool-manifest.ts`             | `TOOLS.json` parser and validator                                                          |
-| `assistant/src/skills/active-skill-tools.ts`        | `deriveActiveSkills()` — scans history for `<loaded_skill>` markers                        |
-| `assistant/src/skills/include-graph.ts`             | Include graph builder: `indexCatalogById()`, `validateIncludes()`, cycle/missing detection |
-| `assistant/src/daemon/conversation-skill-tools.ts`  | `projectSkillTools()` — per-turn projection, register/unregister lifecycle                 |
-| `assistant/src/tools/skills/skill-tool-factory.ts`  | `createSkillToolsFromManifest()` — manifest entries to Tool objects                        |
-| `assistant/src/tools/skills/skill-script-runner.ts` | Host runner: dynamic import + `run()` call                                                 |
-| `assistant/src/tools/skills/sandbox-runner.ts`      | Sandbox runner: isolated subprocess execution                                              |
-| `assistant/src/tools/registry.ts`                   | `registerSkillTools()` / `unregisterSkillTools()` — global tool registry                   |
-| `assistant/src/permissions/checker.ts`              | Skill-origin default-ask permission policy                                                 |
+| File                                                | Role                                                                                         |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `assistant/src/config/skills.ts`                    | Skill catalog loading: bundled, managed, workspace, extra directories                        |
+| `assistant/src/config/bundled-skills/`              | Bundled skill directories (browser, gmail, computer-use, weather, etc.)                      |
+| `assistant/src/skills/tool-manifest.ts`             | `TOOLS.json` parser and validator                                                            |
+| `assistant/src/skills/active-skill-tools.ts`        | `deriveActiveSkills()` — scans history for `<loaded_skill>` markers                          |
+| `assistant/src/skills/include-graph.ts`             | Include graph builder: `indexCatalogById()`, `validateIncludes()`, `validateIncludeCycles()` |
+| `assistant/src/daemon/conversation-skill-tools.ts`  | `projectSkillTools()` — per-turn projection, register/unregister lifecycle                   |
+| `assistant/src/tools/skills/skill-tool-factory.ts`  | `createSkillToolsFromManifest()` — manifest entries to Tool objects                          |
+| `assistant/src/tools/skills/skill-script-runner.ts` | Host runner: dynamic import + `run()` call                                                   |
+| `assistant/src/tools/skills/sandbox-runner.ts`      | Sandbox runner: isolated subprocess execution                                                |
+| `assistant/src/tools/registry.ts`                   | `registerSkillTools()` / `unregisterSkillTools()` — global tool registry                     |
+| `assistant/src/permissions/checker.ts`              | Skill-origin default-ask permission policy                                                   |
 
 ---
 

package/Dockerfile

@@ -22,6 +22,7 @@ COPY packages/service-contracts ./packages/service-contracts
 COPY packages/credential-storage ./packages/credential-storage
 COPY packages/egress-proxy ./packages/egress-proxy
 COPY packages/gateway-client ./packages/gateway-client
+COPY packages/ipc-server-utils ./packages/ipc-server-utils
 COPY packages/skill-host-contracts ./packages/skill-host-contracts
 COPY packages/slack-text ./packages/slack-text
 COPY packages/twilio-client ./packages/twilio-client

package/__tests__/permissions/gateway-threshold-reader.test.ts

@@ -31,18 +31,70 @@ mock.module("../../src/ipc/gateway-client.js", () => ({
   },
 }));
 
-// Suppress logger output in tests
-mock.module("../../src/util/logger.js", () => ({
-  getLogger: () => ({
-    warn: () => {},
-    info: () => {},
-    error: () => {},
-    debug: () => {},
-  }),
-}));
+// Capture logger output so coalescing tests can assert on it. Existing
+// tests don't read the array, so capturing is invisible to them.
+//
+// Bun's `mock.module("../../src/util/logger.js", ...)` does not intercept
+// transitive imports (see comment in stt-hints.test.ts and avatar-e2e.test.ts).
+// Mocking `pino` at the package level works because getLogger uses pino
+// child loggers under the hood — intercepting pino captures everything.
+interface LogCall {
+  level: "warn" | "info" | "error" | "debug";
+  fields: Record<string, unknown>;
+  message: string;
+}
+const logCalls: LogCall[] = [];
+
+function makeLogFn(level: LogCall["level"]) {
+  return (
+    fieldsOrMsg: Record<string, unknown> | string,
+    maybeMsg?: string,
+  ) => {
+    if (typeof fieldsOrMsg === "string") {
+      logCalls.push({ level, fields: {}, message: fieldsOrMsg });
+    } else {
+      logCalls.push({
+        level,
+        fields: fieldsOrMsg,
+        message: maybeMsg ?? "",
+      });
+    }
+  };
+}
+
+const mockChildLogger = {
+  debug: () => {},
+  info: makeLogFn("info"),
+  warn: makeLogFn("warn"),
+  error: makeLogFn("error"),
+  fatal: () => {},
+  trace: () => {},
+  silent: () => {},
+  // pino loggers are themselves callable as a no-op shorthand; child() returns
+  // another logger.
+  child(): typeof mockChildLogger {
+    return mockChildLogger;
+  },
+  bindings: () => ({}),
+  level: "info",
+};
+
+const mockPinoLogger = Object.assign(() => mockChildLogger, {
+  destination: () => ({}),
+  multistream: () => ({}),
+  stdTimeFunctions: { isoTime: () => "" },
+  stdSerializers: {},
+  symbols: {},
+});
+
+mock.module("pino", () => ({ default: mockPinoLogger }));
+mock.module("pino-pretty", () => ({ default: () => ({}) }));
 
 import {
   _clearGlobalCacheForTesting,
+  _getFailureStateForTesting,
+  _resetFailureCoalesceForTesting,
+  _setFailureWarnIntervalForTesting,
   getAutoApproveThreshold,
 } from "../../src/permissions/gateway-threshold-reader.js";
 
@@ -51,7 +103,9 @@ import {
 function resetMocks(): void {
   ipcCallLog.length = 0;
   ipcHandler = () => undefined;
+  logCalls.length = 0;
   _clearGlobalCacheForTesting();
+  _resetFailureCoalesceForTesting();
 }
 
 afterEach(resetMocks);
@@ -221,3 +275,176 @@ describe("getAutoApproveThreshold", () => {
     expect(ipcCallLog).toEqual(["/v1/permissions/thresholds"]);
   });
 });
+
+// ── Failure coalescing ───────────────────────────────────────────────────────
+
+describe("failure-coalescing log behavior", () => {
+  test("first failure WARNs immediately and starts a streak", async () => {
+    ipcHandler = () => {
+      throw new Error("Connection refused");
+    };
+
+    expect(await getAutoApproveThreshold(undefined, "background")).toBe("none");
+
+    const warns = logCalls.filter((c) => c.level === "warn");
+    expect(warns.length).toBe(1);
+    expect(warns[0]?.fields).toMatchObject({
+      op: "global_thresholds",
+      consecutiveFailures: 1,
+      event: "ipc_threshold_failure",
+    });
+
+    const state = _getFailureStateForTesting("global_thresholds");
+    expect(state).toBeDefined();
+    expect(state?.consecutiveFailures).toBe(1);
+  });
+
+  test("subsequent failures within the WARN window do not log but still increment state", async () => {
+    // 1-hour window so the test never accidentally crosses it.
+    _setFailureWarnIntervalForTesting(60 * 60 * 1000);
+    ipcHandler = () => {
+      throw new Error("ENOENT");
+    };
+
+    for (let i = 0; i < 100; i++) {
+      _clearGlobalCacheForTesting(); // force re-fetch each call
+      await getAutoApproveThreshold(undefined, "background");
+    }
+
+    const warns = logCalls.filter((c) => c.level === "warn");
+    // At most one WARN — the very first call. All 99 follow-ups suppressed.
+    expect(warns.length).toBe(1);
+
+    const state = _getFailureStateForTesting("global_thresholds");
+    expect(state?.consecutiveFailures).toBe(100);
+  });
+
+  test("a fresh WARN fires once the cadence window elapses", async () => {
+    // 5ms window so the test runs fast.
+    _setFailureWarnIntervalForTesting(5);
+    ipcHandler = () => {
+      throw new Error("ENOENT");
+    };
+
+    await getAutoApproveThreshold(undefined, "background");
+    expect(logCalls.filter((c) => c.level === "warn").length).toBe(1);
+
+    // Wait past the window then fail again.
+    await new Promise((r) => setTimeout(r, 20));
+    _clearGlobalCacheForTesting();
+    await getAutoApproveThreshold(undefined, "background");
+
+    const warns = logCalls.filter((c) => c.level === "warn");
+    expect(warns.length).toBe(2);
+    // Second WARN includes the streak metadata so dashboards can see how
+    // many failures were swallowed in between.
+    expect(warns[1]?.fields).toMatchObject({
+      op: "global_thresholds",
+      consecutiveFailures: 2,
+      event: "ipc_threshold_failure",
+    });
+    expect(warns[1]?.fields.streakDurationMs).toBeDefined();
+  });
+
+  test("recovery emits an INFO with the swallowed-failure count and clears state", async () => {
+    _setFailureWarnIntervalForTesting(60 * 60 * 1000);
+    let working = false;
+    ipcHandler = (method) => {
+      if (working && method === "get_global_thresholds") {
+        return { interactive: "medium", autonomous: "low" };
+      }
+      throw new Error("ENOENT");
+    };
+
+    // Three failures, then it recovers.
+    for (let i = 0; i < 3; i++) {
+      _clearGlobalCacheForTesting();
+      await getAutoApproveThreshold(undefined, "background");
+    }
+    expect(_getFailureStateForTesting("global_thresholds")?.consecutiveFailures).toBe(
+      3,
+    );
+
+    working = true;
+    _clearGlobalCacheForTesting();
+    expect(await getAutoApproveThreshold(undefined, "background")).toBe("low");
+
+    const infos = logCalls.filter((c) => c.level === "info");
+    expect(infos.length).toBe(1);
+    expect(infos[0]?.fields).toMatchObject({
+      op: "global_thresholds",
+      swallowedFailures: 3,
+      event: "ipc_threshold_recovered",
+    });
+    expect(infos[0]?.fields.streakDurationMs).toBeDefined();
+
+    expect(_getFailureStateForTesting("global_thresholds")).toBeUndefined();
+  });
+
+  test("conversation and global ops have independent failure streaks", async () => {
+    _setFailureWarnIntervalForTesting(60 * 60 * 1000);
+    // conversation IPC fails (transport — returns undefined), global IPC works.
+    ipcHandler = (method) => {
+      if (method === "get_conversation_threshold") return undefined;
+      if (method === "get_global_thresholds") {
+        return { interactive: "medium", autonomous: "low" };
+      }
+      return undefined;
+    };
+
+    // First call: conversation transport fails, global succeeds.
+    expect(await getAutoApproveThreshold("conv-1", "conversation")).toBe(
+      "medium",
+    );
+
+    expect(
+      _getFailureStateForTesting("conversation_threshold")?.consecutiveFailures,
+    ).toBe(1);
+    expect(_getFailureStateForTesting("global_thresholds")).toBeUndefined();
+
+    const warns = logCalls.filter((c) => c.level === "warn");
+    expect(warns.length).toBe(1);
+    expect(warns[0]?.fields.op).toBe("conversation_threshold");
+  });
+
+  test("a successful conversation override clears the conversation streak even when the gateway returns null (no override)", async () => {
+    _setFailureWarnIntervalForTesting(60 * 60 * 1000);
+
+    // First two calls: conversation IPC returns undefined (transport failure).
+    let working = false;
+    ipcHandler = (method) => {
+      if (method === "get_conversation_threshold") {
+        return working ? null : undefined;
+      }
+      if (method === "get_global_thresholds") {
+        return { interactive: "low", autonomous: "none" };
+      }
+      return undefined;
+    };
+
+    // Force two transport failures.
+    await getAutoApproveThreshold("conv-2", "conversation");
+    await new Promise((r) => setTimeout(r, 6)); // bypass the 5s convo cache
+    _clearGlobalCacheForTesting();
+    // Convo cache is keyed on conversationId — change the id to bypass.
+    await getAutoApproveThreshold("conv-3", "conversation");
+    expect(
+      _getFailureStateForTesting("conversation_threshold")?.consecutiveFailures,
+    ).toBe(2);
+
+    // Now the IPC starts working — even a null "no override" response is a
+    // successful round-trip and must clear the streak.
+    working = true;
+    _clearGlobalCacheForTesting();
+    await getAutoApproveThreshold("conv-4", "conversation");
+
+    const infos = logCalls.filter((c) => c.level === "info");
+    expect(infos.length).toBe(1);
+    expect(infos[0]?.fields).toMatchObject({
+      op: "conversation_threshold",
+      swallowedFailures: 2,
+      event: "ipc_threshold_recovered",
+    });
+    expect(_getFailureStateForTesting("conversation_threshold")).toBeUndefined();
+  });
+});

package/bun.lock

@@ -18,6 +18,7 @@
         "@vellumai/credential-storage": "file:../packages/credential-storage",
         "@vellumai/egress-proxy": "file:../packages/egress-proxy",
         "@vellumai/gateway-client": "file:../packages/gateway-client",
+        "@vellumai/ipc-server-utils": "file:../packages/ipc-server-utils",
         "@vellumai/service-contracts": "file:../packages/service-contracts",
         "@vellumai/skill-host-contracts": "file:../packages/skill-host-contracts",
         "@vellumai/slack-text": "file:../packages/slack-text",
@@ -421,6 +422,8 @@
 
     "@vellumai/gateway-client": ["@vellumai/gateway-client@file:../packages/gateway-client", { "dependencies": { "@vellumai/service-contracts": "file:../service-contracts" }, "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
 
+    "@vellumai/ipc-server-utils": ["@vellumai/ipc-server-utils@file:../packages/ipc-server-utils", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],
+
     "@vellumai/service-contracts": ["@vellumai/service-contracts@file:../packages/service-contracts", { "dependencies": { "zod": "4.3.6" }, "devDependencies": { "@types/bun": "1.2.4", "typescript": "5.7.3" } }],
 
     "@vellumai/skill-host-contracts": ["@vellumai/skill-host-contracts@file:../packages/skill-host-contracts", { "devDependencies": { "@types/bun": "1.3.10", "typescript": "5.9.3" } }],

package/docs/architecture/memory.md

@@ -472,7 +472,7 @@ The Anthropic provider places `cache_control: { type: 'ephemeral' }` on the **la
 
 The session injects a unified `<turn_context>` block into every user message, giving the model awareness of the current timestamp (with timezone), interface, channel, and actor identity. This replaces the former separate `<temporal_context>`, `<inbound_actor_context>`, and per-channel turn context blocks. The unified block persists in conversation history so the assistant retains temporal and actor grounding across turns. Legacy blocks from pre-change history are stripped for backward compatibility.
 
-The `current_time:` field format is: `2026-04-02 (Wednesday) 14:30:00 -05:00 (America/Chicago)` — date, weekday name, local time, UTC offset, and IANA timezone name.
+The `current_time:` field format is: `2026-04-02 (Wednesday) 14:30:00 -05:00 (America/Chicago)` — date, weekday name, local time, UTC offset, and IANA timezone name. The timestamp is grounded in the user's effective timezone, not UTC, so a message sent at 10pm local time is represented as 10pm for date/time reasoning.
 
 ### Per-turn flow
 
@@ -492,7 +492,10 @@ graph TB
 
 - **Fresh each turn**: `buildUnifiedTurnContextBlock()` is called at the start of every agent loop invocation, ensuring the model always sees the current timestamp even in long-running conversations.
 - **Clock source invariant**: Absolute time (`now`) always comes from the assistant host clock (`Date.now()`), never from channel/client clocks.
-- **Timezone precedence**: If `ui.userTimezone` is configured, turn context uses it for local-date interpretation. Otherwise it falls back to memory-stored timezone, then assistant host timezone.
+- **Timezone precedence**: Turn context resolves the effective timezone in this order: explicit runtime override for tests/legacy callers, manual `ui.userTimezone`, current turn `clientTimezone`, persisted `ui.detectedTimezone`, then assistant host timezone. The host clock still supplies the absolute instant; this cascade only selects the local timezone used to render `current_time`.
+- **Manual override semantics**: `ui.userTimezone` is a historical config path, but it is runtime-affecting, not purely presentational. When set, it is authoritative for `current_time` across all clients until the user clears or changes it.
+- **Device timezone semantics**: `clientTimezone` is the timezone reported with the active message for this turn. `ui.detectedTimezone` is the last device-detected timezone persisted by a client and is only used when there is no manual override and the current message does not carry a client timezone.
+- **Timezone mismatch guidance**: When `ui.userTimezone` differs from the current device timezone (`clientTimezone`, or `ui.detectedTimezone` when no current client value exists), `<turn_context>` also includes `configured_user_timezone`, `client_device_timezone`, and `timezone_update_available`. The last line tells the assistant that, after explicit user confirmation, it can persist the device timezone with `assistant config set ui.userTimezone "<IANA zone>"`. This gives the assistant a natural-language path to fix stale manual overrides without adding a dedicated tool.
 - **Timezone-aware**: Uses `Intl.DateTimeFormat` APIs for DST-safe date arithmetic and timezone validation/canonicalization.
 - **Persists in history**: The `<turn_context>` block persists in conversation history. Legacy `<temporal_context>`, `<inbound_actor_context>`, and separate channel context blocks from pre-change history are stripped for backward compatibility.
 - **Retry paths**: Turn context is included in all `applyRuntimeInjections` call sites (main path, compact retry, media-trim retry).

package/knip.json

@@ -11,6 +11,7 @@
     "@vellumai/credential-storage",
     "@vellumai/egress-proxy",
     "@vellumai/gateway-client",
+    "@vellumai/ipc-server-utils",
     "@vellumai/service-contracts",
     "@vellumai/slack-text",
     "@vellumai/twilio-client",

package/node_modules/@vellumai/gateway-client/src/ipc-client.ts

@@ -62,13 +62,22 @@ const CONNECT_TIMEOUT_MS = 3_000;
  * Designed for CLI and daemon startup where we need a single RPC call
  * without leaving open handles. Returns `undefined` on any failure
  * (socket not found, timeout, parse error) so callers can fall back.
+ *
+ * @param timeoutMs - Optional override for both the connect and call
+ *   timeouts. When omitted, defaults to the module constants
+ *   (CONNECT_TIMEOUT_MS / DEFAULT_CALL_TIMEOUT_MS). Pass a small value
+ *   (e.g. 200) for opportunistic CLI checks where a slow/absent gateway
+ *   should fail fast rather than block startup.
  */
 export async function ipcCall(
   socketPath: string,
   method: string,
   params?: Record<string, unknown>,
   log: Logger = noopLogger,
+  timeoutMs?: number,
 ): Promise<unknown> {
+  const connectTimeoutMs = timeoutMs ?? CONNECT_TIMEOUT_MS;
+  const callTimeoutMs = timeoutMs ?? DEFAULT_CALL_TIMEOUT_MS;
   return new Promise<unknown>((resolve) => {
     let settled = false;
     let callTimer: ReturnType<typeof setTimeout> | undefined;
@@ -84,11 +93,11 @@ export async function ipcCall(
 
     const connectTimer = setTimeout(() => {
       log.warn(
-        { method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS },
+        { method, socketPath, timeoutMs: connectTimeoutMs },
         "IPC connect timed out",
       );
       finish(undefined);
-    }, CONNECT_TIMEOUT_MS);
+    }, connectTimeoutMs);
 
     const socket: Socket = connect(socketPath);
     socket.unref();
@@ -103,11 +112,11 @@ export async function ipcCall(
 
       callTimer = setTimeout(() => {
         log.warn(
-          { method, socketPath, timeoutMs: DEFAULT_CALL_TIMEOUT_MS },
+          { method, socketPath, timeoutMs: callTimeoutMs },
           "IPC call timed out waiting for response",
         );
         finish(undefined);
-      }, DEFAULT_CALL_TIMEOUT_MS);
+      }, callTimeoutMs);
 
       socket.on("data", (chunk) => {
         buffer += chunk.toString();

package/node_modules/@vellumai/ipc-server-utils/bun.lock

@@ -0,0 +1,24 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/ipc-server-utils",
+      "devDependencies": {
+        "@types/bun": "1.3.10",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/ipc-server-utils",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/ipc-server-utils/src/index.ts

@@ -0,0 +1,6 @@
+export {
+  SocketWatchdog,
+  ensureSocketDir,
+  type SocketWatchdogOptions,
+  type SocketWatchdogLogger,
+} from "./socket-watchdog.js";