@vellumai/assistant 0.9.0 → 0.9.1-staging.1

package/src/notifications/broadcaster.ts

@@ -14,7 +14,10 @@ import { v4 as uuid } from "uuid";
 import { getConversation } from "../memory/conversation-crud.js";
 import type { ApprovalUIMetadata } from "../runtime/channel-approval-types.js";
 import { getLogger } from "../util/logger.js";
-import { buildAccessRequestContractText } from "./access-request-copy.js";
+import {
+  buildAccessRequestContractText,
+  parseAccessRequestPayload,
+} from "./access-request-copy.js";
 import { isGuardianSensitiveEvent } from "./adapters/macos.js";
 import { pairDeliveryWithConversation } from "./conversation-pairing.js";
 import { composeFallbackCopy } from "./copy-composer.js";
@@ -181,6 +184,11 @@ export class NotificationBroadcaster {
     > | null = null;
 
     const approvalContext = resolveApprovalContext(signal);
+    const accessRequestContext =
+      signal.sourceEventName === "ingress.access_request" &&
+      signal.contextPayload
+        ? parseAccessRequestPayload(signal.contextPayload)
+        : undefined;
     const results: NotificationDeliveryResult[] = [];
 
     for (const channel of orderedChannels) {
@@ -411,6 +419,7 @@ export class NotificationBroadcaster {
         contextPayload: signal.contextPayload,
         urgency: signal.attentionHints.urgency,
         approvalContext,
+        accessRequestContext,
       };
 
       // Compute conversation decision audit fields for the delivery record

package/src/notifications/home-feed-side-effect.ts

@@ -217,9 +217,10 @@ function resolveHomeFeedMirror(
   sourceConversationId?: string;
   sourceScheduleJobId?: string;
 } {
-  let sourceRow:
-    | { conversationType?: string; scheduleJobId?: string | null }
-    | null = null;
+  let sourceRow: {
+    conversationType?: string;
+    scheduleJobId?: string | null;
+  } | null = null;
   if (signal.sourceContextId) {
     try {
       sourceRow = getConversation(signal.sourceContextId) ?? null;

package/src/notifications/notification-utils.ts

@@ -29,38 +29,36 @@ export function readPayloadString(
   return typeof value === "string" ? value : undefined;
 }
 
+/** Truncate `text` to `maxLength`, appending "…" when exceeded. */
+export function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength - 1) + "…";
+}
+
 // ── Sanitization ────────────────────────────────────────────────────────────
 
-const IDENTITY_FIELD_MAX_LENGTH = 120;
+/** Strip control characters and newlines, then truncate to `maxLength`. */
+function sanitize(value: string, maxLength: number): string {
+  return truncate(
+    value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, " ").trim(),
+    maxLength,
+  );
+}
 
 /**
  * Sanitize an untrusted identity field for inclusion in notification copy.
- *
- * - Strips control characters (U+0000–U+001F, U+007F–U+009F) and newlines.
- * - Clamps to 120 characters.
+ * Strips control characters and clamps to 120 characters.
  */
 export function sanitizeIdentityField(value: string): string {
-  const stripped = value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, " ").trim();
-  const clamped =
-    stripped.length > IDENTITY_FIELD_MAX_LENGTH
-      ? stripped.slice(0, IDENTITY_FIELD_MAX_LENGTH) + "…"
-      : stripped;
-  return clamped;
+  return sanitize(value, 120);
 }
 
 export const MESSAGE_PREVIEW_MAX_LENGTH = 200;
 
 /**
  * Sanitize an untrusted message preview for inclusion in notification copy.
- *
- * Same as {@link sanitizeIdentityField} but uses a higher length limit
- * (200 chars) suited for message previews.
+ * Strips control characters and clamps to 200 characters.
  */
 export function sanitizeMessagePreview(value: string): string {
-  const stripped = value.replace(/[\x00-\x1f\x7f-\x9f\r\n]+/g, " ").trim();
-  const clamped =
-    stripped.length > MESSAGE_PREVIEW_MAX_LENGTH
-      ? stripped.slice(0, MESSAGE_PREVIEW_MAX_LENGTH) + "…"
-      : stripped;
-  return clamped;
+  return sanitize(value, MESSAGE_PREVIEW_MAX_LENGTH);
 }

package/src/notifications/types.ts

@@ -8,6 +8,7 @@
 import type { ChannelPolicies } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
 import type { ApprovalUIMetadata } from "../runtime/channel-approval-types.js";
+import type { ParsedAccessRequestPayload } from "./access-request-copy.js";
 import type { AttentionHints } from "./signal.js";
 
 /**
@@ -103,6 +104,12 @@ export interface ChannelDeliveryPayload {
    * `contextPayload`.
    */
   approvalContext?: ApprovalUIMetadata;
+  /**
+   * Pre-parsed access request context for `ingress.access_request` signals.
+   * Built centrally by the broadcaster so adapters can render structured
+   * access-request cards without re-parsing `contextPayload`.
+   */
+  accessRequestContext?: ParsedAccessRequestPayload;
 }
 
 /**

package/src/oauth/AGENTS.md

@@ -29,34 +29,15 @@ Then add the key to `ServicesSchema`:
 
 The key here **must** match the `managedServiceConfigKey` in `seed-providers.ts`. The cross-repo invariant test in `__tests__/seed-providers-managed.test.ts` will fail if they drift.
 
-### 3. _(managed only)_ Enable by default during onboarding — `clients/macos/.../HatchingStepView.swift`
+### 3. _(managed only)_ Enable by default during onboarding
 
-In `buildOnboardingConfigValues()`, add a line so managed-sign-in users get the integration pre-enabled:
+Managed-sign-in users should get the integration pre-enabled by setting `services.acme-oauth.mode` to `"managed"` in the client's onboarding config defaults.
 
-```swift
-configValues["services.acme-oauth.mode"] = "managed"
-```
-
-### 4. Add a cached logo — `clients/shared/Resources/IntegrationLogos/`
-
-Drop a **vector PDF** named `{provider_key}.pdf` (e.g. `acme.pdf`) into the `IntegrationLogos/` directory. The file is automatically bundled via `.copy()` in `clients/Package.swift` and looked up at runtime by `IntegrationLogoBundle` using the provider key — no code changes needed.
-
-Most existing logos come from [Simple Icons](https://simpleicons.org) (CC0-licensed). To get a PDF from Simple Icons:
-
-1. Find the icon slug on https://simpleicons.org (e.g. `slack`, `linear`).
-2. Download the SVG: `curl -o acme.svg https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/acme.svg`
-3. Convert to PDF using `rsvg-convert` (same tool used by `clients/scripts/sync-lucide-icons.sh`):
-   ```bash
-   # Install if needed: brew install librsvg
-   rsvg-convert -f pdf -o clients/shared/Resources/IntegrationLogos/acme.pdf acme.svg
-   ```
-4. Add the provider key to `clients/shared/Resources/integration-logos-manifest.json`.
-
-If the service is not on Simple Icons, source or create an SVG and convert it the same way. The result must be a true vector PDF (not a rasterized image wrapped in PDF) so it scales cleanly.
+### 4. Set the logo URL — `seed-providers.ts`
 
-The `logoUrl` field in `seed-providers.ts` serves as the remote fallback (most providers use a Simple Icons CDN URL like `https://cdn.simpleicons.org/acme`). The client renders the local PDF first, then falls back to `logoUrl`, then to an initials avatar.
+The `logoUrl` field in `seed-providers.ts` is the source of truth for a provider's logo. Most providers use a [Simple Icons](https://simpleicons.org) (CC0-licensed) CDN URL like `https://cdn.simpleicons.org/acme`. The web client resolves logos from this field (see `clients/web/src/components/integrations/integration-icon.tsx`) and falls back to an initials avatar.
 
-For brands Simple Icons doesn't host (e.g. Salesforce, which Simple Icons removed for trademark reasons), use the same `glincker/thesvg` source via jsDelivr — `https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/<key>/default.svg`. The recognised `logoUrl` prefixes are enforced by `oauth-provider-seed-logos.test.ts`; if you need a third source, extend that allowlist alongside the manifest in `clients/shared/Resources/integration-logos-manifest.json`.
+For brands Simple Icons doesn't host (e.g. Salesforce, which Simple Icons removed for trademark reasons), use the `glincker/thesvg` source via jsDelivr — `https://cdn.jsdelivr.net/gh/glincker/thesvg@main/public/icons/<key>/default.svg`. The recognised `logoUrl` prefixes are enforced by `oauth-provider-seed-logos.test.ts`; if you need a third source, extend that allowlist.
 
 ### 5. Secret patterns (if applicable) — `../security/secret-patterns.ts`
 

package/src/plugin-api/constants.ts

@@ -20,7 +20,7 @@ export const HOOKS = {
   SHUTDOWN: "shutdown",
   /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
   USER_PROMPT_SUBMIT: "user-prompt-submit",
-  /** Fires immediately before each provider call. A hook may edit the outbound request (e.g. the system prompt) and opt the turn into deferred output streaming. */
+  /** Fires immediately before each provider call. A hook may edit the outbound request (e.g. the system prompt), route the call to a different inference profile, and opt the turn into deferred output streaming. */
   PRE_MODEL_CALL: "pre-model-call",
   /** Fires once per tool result, after the tool returns and before the result is sent to the provider. */
   POST_TOOL_USE: "post-tool-use",

package/src/plugin-api/index.ts

@@ -32,6 +32,8 @@
  *
  * - {@link assistantEventHub} — the assistant's pub/sub hub for runtime events
  * - {@link getSecureKeyAsync} — read a secret from secure storage
+ * - {@link getModelProfiles} — list the workspace inference profiles a plugin
+ *   can route to (e.g. a model router building its category → profile map)
  *
  * - {@link PluginInitContext} — passed to `init` hook at bootstrap
  * - {@link PluginShutdownContext} — passed to `shutdown` hook at teardown
@@ -40,7 +42,8 @@
  * - {@link PostCompactContext} — passed to `post-compact` hook, fired after
  *   the agent loop compacts a conversation mid-turn to re-apply injections
  * - {@link PreModelCallContext} — passed to `pre-model-call` hook, fired
- *   before each provider call to edit the request / defer output streaming
+ *   before each provider call to edit the request, route it to a different
+ *   inference profile, or defer output streaming
  * - {@link PostToolUseContext} — passed to `post-tool-use` hook, fired once
  *   per tool result before it joins the provider-bound history
  * - {@link StopContext} — passed to `stop` hook, the definitive terminal hook
@@ -79,6 +82,7 @@ export type {
 } from "../providers/types.js";
 export type {
   AgentLoopExitReason,
+  ModelProfileInfo,
   PluginHookFn,
   PluginInitContext,
   PluginLogger,
@@ -110,3 +114,4 @@ export type {
 } from "../runtime/assistant-event-hub.js";
 export { assistantEventHub } from "../runtime/assistant-event-hub.js";
 export { getSecureKeyAsync } from "../security/secure-keys.js";
+export { getModelProfiles } from "./model-profiles.js";

package/src/plugin-api/model-profiles.ts

@@ -0,0 +1,33 @@
+import { getConfig } from "../config/loader.js";
+import { orderProfileKeys } from "../config/profile-order.js";
+import type { ModelProfileInfo } from "./types.js";
+
+/**
+ * List the workspace inference profiles a plugin can route to, in the order the
+ * `/model` picker presents them (`llm.profileOrder` first, then the rest
+ * alphabetically). Disabled profiles are included and flagged via
+ * {@link ModelProfileInfo.isDisabled}; weighted "mix" profiles are included and
+ * flagged via {@link ModelProfileInfo.isMix}, since a mix is itself a valid
+ * routing target (it resolves to one constituent per conversation).
+ *
+ * Reads the live in-memory config, so the result reflects the current profile
+ * set each time it is called.
+ */
+export function getModelProfiles(): ModelProfileInfo[] {
+  const { llm } = getConfig();
+  const { profiles, activeProfile } = llm;
+  const result: ModelProfileInfo[] = [];
+  for (const key of orderProfileKeys(profiles, llm.profileOrder)) {
+    const entry = profiles[key];
+    if (entry == null) continue;
+    result.push({
+      key,
+      label: entry.label ?? key,
+      description: entry.description ?? null,
+      isActive: key === activeProfile,
+      isDisabled: entry.status === "disabled",
+      isMix: entry.mix != null,
+    });
+  }
+  return result;
+}

package/src/plugin-api/types.ts

@@ -94,6 +94,35 @@ export interface PluginInitContext {
   assistantVersion: string;
 }
 
+// ─── Model profiles ──────────────────────────────────────────────────────────
+
+/**
+ * A workspace inference profile a plugin can route to. Returned by
+ * {@link getModelProfiles}; {@link key} is the value a `pre-model-call` hook
+ * assigns to `PreModelCallContext.modelProfile` to route a call. A model router
+ * reads this list (typically at `init`) to learn which profiles exist before
+ * mapping a classified message onto one.
+ */
+export interface ModelProfileInfo {
+  /** Profile key in `llm.profiles`; assignable to `PreModelCallContext.modelProfile`. */
+  readonly key: string;
+  /** Human-readable label, falling back to {@link key} when none is set. */
+  readonly label: string;
+  /** Author-supplied description, or `null` when none is set. */
+  readonly description: string | null;
+  /** Whether this is the workspace's active profile. */
+  readonly isActive: boolean;
+  /** Whether the profile is disabled; routing to it is rejected by the resolver. */
+  readonly isDisabled: boolean;
+  /**
+   * Whether this is a weighted "mix" profile — an A/B blend that resolves to one
+   * of its constituent profiles per conversation via a seeded weighted pick.
+   * Routing to its {@link key} is valid; it directs the call into the blend
+   * rather than at a single fixed model.
+   */
+  readonly isMix: boolean;
+}
+
 // ─── Shutdown context ────────────────────────────────────────────────────────
 
 /**
@@ -438,8 +467,9 @@ export interface StopContext {
  * and compaction work can share a conversation), hooks MUST self-gate on
  * {@link callSite} / {@link conversationId} before acting.
  *
- * A hook may edit the outbound request by replacing {@link systemPrompt}, and may
- * opt this turn into deferred output streaming via {@link deferAssistantOutput}.
+ * A hook may edit the outbound request by replacing {@link systemPrompt}, route
+ * the call to a different inference profile via {@link modelProfile}, and opt
+ * this turn into deferred output streaming via {@link deferAssistantOutput}.
  * Mutate the context in place or return a new one; throwing is contained by the
  * loop (the call proceeds with the original request).
  */
@@ -456,6 +486,24 @@ export interface PreModelCallContext {
    * append a section); the loop sends the resulting value.
    */
   systemPrompt: string | null;
+  /**
+   * Inference profile to route THIS provider call to, named by its key in the
+   * workspace `llm.profiles`. Seeded with the call's already-resolved override
+   * profile, or `null` when none applies. A hook may replace it to select a
+   * different profile per call — the lever a model router uses to map a
+   * classified message onto a profile (model + provider connection + sampling
+   * settings). For the user-facing `mainAgent` call the resolver layers the
+   * named profile at the top of precedence (above the workspace active
+   * profile), so the hook's choice wins; a key with no matching profile falls
+   * through unchanged (no throw). Honored only when {@link callSite} is set.
+   * Set to `null` to apply no override.
+   *
+   * Context-window sizing and overflow recovery for this call are computed from
+   * the profile resolved before the hook runs. Routing a near-budget
+   * conversation to a profile with a smaller context window relies on the loop's
+   * overflow recovery (compact and retry) rather than proactive compaction.
+   */
+  modelProfile: string | null;
   /**
    * Seeded `false`. When a hook sets it `true`, the loop suppresses this turn's
    * live assistant `text_delta` stream; a `post-model-call` hook is then

package/src/plugins/defaults/index.ts

@@ -54,6 +54,10 @@ import memoryRetrievalPkg from "./memory-retrieval/package.json" with { type: "j
 import memoryV3PostCompact from "./memory-v3-shadow/hooks/post-compact.js";
 import memoryV3UserPromptSubmit from "./memory-v3-shadow/hooks/user-prompt-submit.js";
 import memoryV3Pkg from "./memory-v3-shadow/package.json" with { type: "json" };
+import surfaceCompletionNudgePostModelCall from "./surface-completion-nudge/hooks/post-model-call.js";
+import surfaceCompletionNudgeStop from "./surface-completion-nudge/hooks/stop.js";
+import { resetSurfaceCompletionNudgeStoreForTests } from "./surface-completion-nudge/nudge-state-store.js";
+import surfaceCompletionNudgePkg from "./surface-completion-nudge/package.json" with { type: "json" };
 import taskProgressNudgePostToolUse, {
   resetTaskProgressNudgeStateForTests,
 } from "./task-progress-nudge/hooks/post-tool-use.js";
@@ -259,6 +263,25 @@ export const defaultTaskProgressNudgePlugin: Plugin = {
   },
 };
 
+/**
+ * `surface-completion-nudge` — a `post-model-call` hook that, when a user-facing
+ * turn is about to end with a progress surface (a `task_progress` card or
+ * `work_result`) the model showed but never advanced to a terminal status or
+ * dismissed, nudges the model once to close it and re-queries so it can act; the
+ * `stop` hook clears the one-shot bound on a terminal stop so the next run
+ * nudges afresh.
+ */
+export const defaultSurfaceCompletionNudgePlugin: Plugin = {
+  manifest: {
+    name: surfaceCompletionNudgePkg.name,
+    version: surfaceCompletionNudgePkg.version,
+  },
+  hooks: {
+    "post-model-call": surfaceCompletionNudgePostModelCall,
+    stop: surfaceCompletionNudgeStop,
+  },
+};
+
 /**
  * `tool-result-truncate` — a `post-tool-use` hook that tail-drops an oversized
  * tool result down to a character budget derived from the model's context
@@ -289,6 +312,7 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     defaultToolErrorPlugin,
     defaultExplorationDriftPlugin,
     defaultTaskProgressNudgePlugin,
+    defaultSurfaceCompletionNudgePlugin,
     defaultHistoryRepairPlugin,
     defaultImageRecoveryPlugin,
     defaultCompactionPlugin,
@@ -339,5 +363,6 @@ export function resetPluginRegistryAndRegisterDefaults(): void {
   resetImageRecoveryStoreForTests();
   resetExplorationDriftStateForTests();
   resetTaskProgressNudgeStateForTests();
+  resetSurfaceCompletionNudgeStoreForTests();
   registerDefaultPlugins();
 }

package/src/plugins/defaults/memory-v3-shadow/__tests__/maintain-job.test.ts

@@ -71,6 +71,7 @@ describe("maintainJob", () => {
         return makeIndex(slugs);
       },
       readPageBody: async (slug) => `body for ${slug}`,
+      readCapabilityBody: async (slug) => `capability body for ${slug}`,
       deleteSectionsForArticle: async (_config, article) => {
         calls.deleted.push(article);
       },
@@ -283,6 +284,9 @@ describe("maintainJob", () => {
     const { deps: d, calls } = deps({
       loadCoreSet: () => ["page-live", "page-gone", "skills/example"],
       listIndexedSlugs: async () => ["page-live", "skills/example"],
+      // The capability row is already in the store, so the reconcile stage
+      // no-ops here and this test exercises core-validation in isolation.
+      listSectionArticles: async () => ["skills/example"],
     });
     const outcome = await maintainJob(JOB, CONFIG, d);
 
@@ -317,8 +321,9 @@ describe("maintainJob", () => {
     });
     const outcome = await maintainJob(JOB, CONFIG, d);
     expect(outcome.danglingCoreSlugs).toEqual([]);
-    // The prune stage reads the index once; the core stage adds no second read.
-    expect(indexReads).toBe(1);
+    // The reconcile and prune stages each read the index once; the empty core
+    // stage adds no further read.
+    expect(indexReads).toBe(2);
   });
 
   test("a thrown core-validation stage is contained and does not abort lane invalidation", async () => {
@@ -351,6 +356,53 @@ describe("maintainJob", () => {
     expect(calls.invalidate).toBe(1);
     expect(outcome.invalidated).toBe(true);
   });
+
+  test("reconciles capability rows missing from the section store", async () => {
+    setOverridesForTesting({ [FLAG_SHADOW]: true });
+    // The index lists a real page and three capability rows; the store already
+    // holds one of the caps. The change-delta excludes capability rows, so
+    // without this stage a skill enabled after the one-time backfill never
+    // reaches the dense lane. selectChangedPages stays empty so `calls.built`
+    // reflects reconcile embeds only.
+    const { deps: d, calls } = deps({
+      selectChangedPages: async () => [],
+      listIndexedSlugs: async () => [
+        "page-a",
+        "skills/already",
+        "skills/workflows",
+        "skills/another",
+      ],
+      listSectionArticles: async () => ["page-a", "skills/already"],
+    });
+    const outcome = await maintainJob(JOB, CONFIG, d);
+
+    // Only the caps missing from the store are embedded; the real page (handled
+    // by the change-delta stage) and the already-stored cap are left alone.
+    expect(outcome.capabilitiesReconciled).toBe(2);
+    expect(outcome.reconcileFailures).toBe(0);
+    expect(calls.built).toEqual([["skills/workflows"], ["skills/another"]]);
+    expect(calls.deleted).toEqual(["skills/workflows", "skills/another"]);
+    expect(calls.upserted.flat().map((s) => s.article)).toEqual([
+      "skills/workflows",
+      "skills/another",
+    ]);
+  });
+
+  test("skips a cold capability row (empty body) without deleting its points", async () => {
+    setOverridesForTesting({ [FLAG_SHADOW]: true });
+    const { deps: d, calls } = deps({
+      listIndexedSlugs: async () => ["skills/cold"],
+      listSectionArticles: async () => [],
+      readCapabilityBody: async () => "", // capability store not seeded yet
+    });
+    const outcome = await maintainJob(JOB, CONFIG, d);
+
+    expect(outcome.capabilitiesReconciled).toBe(0);
+    expect(outcome.reconcileFailures).toBe(0);
+    // Never replace good points with a blank: no delete, no upsert.
+    expect(calls.deleted).toEqual([]);
+    expect(calls.upserted).toEqual([]);
+  });
 });
 
 describe("computeChangedPages", () => {

package/src/plugins/defaults/memory-v3-shadow/maintain-job.ts

@@ -2,7 +2,7 @@
  * Memory v3 — `memory_v3_maintain` job handler.
  *
  * A flag-gated, best-effort self-maintenance pass over the v3 section dense
- * store and the in-memory lanes. It runs four independent stages, in order:
+ * store and the in-memory lanes. It runs five independent stages, in order:
  *
  *   1. **Section re-embed** — diff the page index by `modifiedAt` against the
  *      last successful pass (the high-water mark below), and for every page that
@@ -15,19 +15,26 @@
  *      captured before any potential mtime bumps) so a page is not re-embedded
  *      forever, yet a page whose embed failed (and whose sections were therefore
  *      left deleted) stays above the mark and is retried next pass.
- *   2. **Deleted-page prune** — diff the dense store's stored articles
+ *   2. **Capability reconcile** — embed capability rows (synthetic skill/CLI
+ *      slugs) present in the page index but missing from the section store. The
+ *      re-embed delta above EXCLUDES capability rows (they have `modifiedAt` 0,
+ *      no mtime to diff), so the only other embedder is the one-time
+ *      `backfillAllSections`. Without this stage a skill enabled AFTER that
+ *      backfill (e.g. a flag-gated skill flipped on at runtime) lands in the
+ *      index but never reaches the dense lane. See {@link reconcileCapabilityRows}.
+ *   3. **Deleted-page prune** — diff the dense store's stored articles
  *      (`listSectionArticles`) against the live page-index slugs and
  *      `deleteSectionsForArticle` for any article that is no longer in the
  *      index. A deleted page's slug never reaches the re-embed delta selector
  *      (it only names live pages), so without this its section points would
  *      linger in Qdrant and the dense lane could still surface the deleted page.
  *      Synthetic capability rows are in the page index, so they are never pruned.
- *   3. **Core-set validation** — load the maintainer-curated core set
+ *   4. **Core-set validation** — load the maintainer-curated core set
  *      (`memory/core-pages.md`) and report entries whose page no longer exists
  *      in the page index (dangling slugs) via the log + outcome. The file is
  *      maintainer-owned, so this stage NEVER edits it — the maintainer fixes
  *      dangling entries at the next consolidation pass.
- *   4. **Lane invalidation** — `invalidateLanes()` so the next turn rebuilds the
+ *   5. **Lane invalidation** — `invalidateLanes()` so the next turn rebuilds the
  *      in-memory section index, needle, and edge graph from the freshly-updated
  *      pages.
  *
@@ -110,6 +117,13 @@ export interface MaintainJobDeps {
   buildSectionIndex: typeof realBuildSectionIndex;
   /** Read a page's frontmatter-stripped body for `buildSectionIndex`. */
   readPageBody: (slug: Slug) => Promise<string>;
+  /**
+   * Capability-aware body reader for the reconcile stage: synthetic skill/CLI
+   * slugs resolve their rendered capability content; real pages read from disk.
+   * The re-embed stage uses `readPageBody` (disk-only) since it only processes
+   * real pages — the reconcile stage needs capability bodies.
+   */
+  readCapabilityBody: (slug: Slug) => Promise<string>;
   /** Clear an article's stale section points before re-upserting. */
   deleteSectionsForArticle: typeof realDeleteSectionsForArticle;
   /** Embed + upsert an article's current sections into the dense store. */
@@ -198,6 +212,15 @@ export interface MaintainOutcome {
   reembedded: number;
   /** Pages whose re-embed threw (and was contained). */
   reembedFailures: number;
+  /**
+   * Capability rows (skills/CLI) present in the index but missing from the
+   * section store that were embedded this pass — how a skill enabled after the
+   * one-time backfill reaches the dense lane (the re-embed delta excludes
+   * capability rows).
+   */
+  capabilitiesReconciled: number;
+  /** Capability reconcile embeds that threw (and were contained). */
+  reconcileFailures: number;
   /**
    * Deleted-page articles whose lingering section points were pruned this pass
    * (present in the dense store but absent from the page index).
@@ -302,6 +325,8 @@ function defaultDeps(config: AssistantConfig): MaintainJobDeps {
     selectChangedPages: () => selectChangedPagesFromWorkspace(workspaceDir),
     buildSectionIndex: realBuildSectionIndex,
     readPageBody: (slug) => readPageBodyFromWorkspace(workspaceDir, slug),
+    readCapabilityBody: (slug) =>
+      backfillPageBodyFromWorkspace(workspaceDir, slug),
     deleteSectionsForArticle: realDeleteSectionsForArticle,
     upsertSections: realUpsertSections,
     commitEmbedHighWater,
@@ -357,6 +382,58 @@ async function reembedChangedPages(
   return { reembedded, reembedFailures };
 }
 
+/**
+ * Embed capability rows (synthetic skill/CLI slugs) present in the page index
+ * but missing from the section dense store. The incremental re-embed selector
+ * ({@link computeChangedPages}) excludes capability rows — they have no on-disk
+ * mtime to delta against — so the ONLY other embedder is the one-time
+ * {@link backfillAllSections}. Without this, a skill enabled AFTER that backfill
+ * (e.g. a flag-gated skill flipped on at runtime) lands in the page index but
+ * never reaches the dense lane. This stage makes the periodic maintain pass
+ * self-heal: diff the live capability slugs against the stored section articles
+ * and embed the missing ones.
+ *
+ * Each row is independent: a single build/upsert throw is logged and counted in
+ * `reconcileFailures` without aborting the rest. A capability row whose body
+ * resolves empty (its store has not seeded yet) is skipped WITHOUT deleting any
+ * points — never replace good points with a blank — and is retried next pass.
+ */
+async function reconcileCapabilityRows(
+  deps: MaintainJobDeps,
+): Promise<{ capabilitiesReconciled: number; reconcileFailures: number }> {
+  const [indexedSlugs, storedArticles] = await Promise.all([
+    deps.listIndexedSlugs(),
+    deps.listSectionArticles(),
+  ]);
+  const stored = new Set(storedArticles);
+  const missing = indexedSlugs.filter(
+    (slug) => isCapabilitySlug(slug) && !stored.has(slug),
+  );
+
+  let capabilitiesReconciled = 0;
+  let reconcileFailures = 0;
+  for (const slug of missing) {
+    try {
+      const body = await deps.readCapabilityBody(slug);
+      if (body.trim().length === 0) continue; // store cold — retry next pass
+      const index = await deps.buildSectionIndex(
+        [slug],
+        deps.readCapabilityBody,
+      );
+      await deps.deleteSectionsForArticle(deps.config, slug);
+      await deps.upsertSections(deps.config, index.sections);
+      capabilitiesReconciled += 1;
+    } catch (err) {
+      reconcileFailures += 1;
+      log.warn(
+        { slug, err: err instanceof Error ? err.message : String(err) },
+        "memory-v3 maintain: capability reconcile embed failed (non-fatal)",
+      );
+    }
+  }
+  return { capabilitiesReconciled, reconcileFailures };
+}
+
 /**
  * Prune section points for articles that no longer exist in the page index. A
  * deleted concept page leaves `getPageIndex` (so the needle and edge lanes both
@@ -537,6 +614,8 @@ export async function maintainJob(
     disabled: false,
     reembedded: 0,
     reembedFailures: 0,
+    capabilitiesReconciled: 0,
+    reconcileFailures: 0,
     pruned: 0,
     pruneFailures: 0,
     danglingCoreSlugs: [],
@@ -587,7 +666,26 @@ export async function maintainJob(
     );
   }
 
-  // Stage 2: prune section points for pages deleted from the index. A deleted
+  // Stage 2: embed capability rows (skills/CLI) present in the index but missing
+  // from the section store. They have modifiedAt 0, so computeChangedPages never
+  // selects them; the one-time backfill is otherwise their only embedder, so a
+  // skill enabled after that backfill stays invisible to the dense lane until
+  // this self-heals it. Contained: a failure is logged + recorded without
+  // aborting later stages.
+  try {
+    const { capabilitiesReconciled, reconcileFailures } =
+      await reconcileCapabilityRows(deps);
+    outcome.capabilitiesReconciled = capabilitiesReconciled;
+    outcome.reconcileFailures = reconcileFailures;
+  } catch (err) {
+    outcome.failures.push("capability-reconcile");
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err) },
+      "memory-v3 maintain: capability reconcile failed (non-fatal)",
+    );
+  }
+
+  // Stage 3: prune section points for pages deleted from the index. A deleted
   // page's slug never appears in `selectChangedPages` (the delta selector only
   // names live pages), so its lingering points are cleared by diffing the dense
   // store's stored articles against the live page-index slugs. Contained: a
@@ -604,7 +702,7 @@ export async function maintainJob(
     );
   }
 
-  // Stage 3: validate the maintainer-curated core set. Diff `core-pages.md`
+  // Stage 4: validate the maintainer-curated core set. Diff `core-pages.md`
   // entries against the live page-index slugs and REPORT dangling entries
   // (pages that were renamed or deleted) through the log + outcome — the file
   // is maintainer-owned, so it is never auto-edited; the maintainer fixes it at
@@ -632,7 +730,7 @@ export async function maintainJob(
     );
   }
 
-  // Stage 4: rebuild section index + needle + edge graph on the next turn.
+  // Stage 5: rebuild section index + needle + edge graph on the next turn.
   try {
     deps.invalidateLanes();
     outcome.invalidated = true;
@@ -648,6 +746,8 @@ export async function maintainJob(
     {
       reembedded: outcome.reembedded,
       reembedFailures: outcome.reembedFailures,
+      capabilitiesReconciled: outcome.capabilitiesReconciled,
+      reconcileFailures: outcome.reconcileFailures,
       pruned: outcome.pruned,
       pruneFailures: outcome.pruneFailures,
       danglingCoreSlugs: outcome.danglingCoreSlugs,