@vellumai/assistant 0.12.2-staging.3 → 0.12.2-staging.5

package/src/notifications/__tests__/decision-engine.test.ts

@@ -736,3 +736,178 @@ describe("schedule.result pass-through in notification decision engine", () => {
     expect(decision.shouldNotify).toBe(true);
   });
 });
+
+const SCHEDULER_OWNED_REPORT = [
+  "# Daily briefing",
+  "",
+  "## Overnight",
+  "- Calendar is clear until 10:00.",
+  "- Two pull requests are waiting on review.",
+  "",
+  "## Account security",
+  "- Urgent: a sign-in from a new device needs confirmation before the weekly sync.",
+  "",
+  "## This week",
+  "- Project kickoff on Wednesday.",
+  "- Weekly planning on Friday.",
+  "- Follow up on the draft status update.",
+].join("\n");
+
+function makeSchedulerShareSignal(
+  overrides?: Partial<NotificationSignal>,
+): NotificationSignal {
+  return {
+    signalId: "sig-scheduler-share-test-1",
+    createdAt: Date.now(),
+    sourceChannel: "scheduler",
+    sourceContextId: "conv-xyz",
+    sourceEventName: "assistant.share",
+    contextPayload: {
+      requestedMessage: SCHEDULER_OWNED_REPORT,
+      requestedBySource: "scheduler",
+      requestedTitle: "Your day",
+    },
+    attentionHints: {
+      requiresAction: true,
+      urgency: "high",
+      isAsyncBackground: true,
+      visibleInSourceNow: false,
+    },
+    ...overrides,
+  };
+}
+
+describe("scheduler requested-message pass-through in notification decision engine", () => {
+  beforeEach(() => {
+    persistedDecisions = [];
+  });
+
+  test("keeps a scheduler-owned report verbatim on every urgency-selected channel", async () => {
+    const available = [
+      "vellum",
+      "telegram",
+      "platform",
+    ] as NotificationChannel[];
+    const decision = await evaluateSignal(
+      makeSchedulerShareSignal(),
+      available,
+    );
+
+    expect(decision.shouldNotify).toBe(true);
+    expect(decision.selectedChannels).toEqual(available);
+    expect(decision.reasoningSummary).toBe(
+      "scheduler requested-message pass-through",
+    );
+    expect(decision.verbatimCopy).toBe(true);
+    expect(decision.fallbackUsed).toBe(false);
+    for (const ch of available) {
+      expect(decision.renderedCopy[ch]?.title).toBe("Your day");
+      expect(decision.renderedCopy[ch]?.body).toBe(SCHEDULER_OWNED_REPORT);
+      expect(decision.renderedCopy[ch]?.conversationSeedMessage).toBe(
+        SCHEDULER_OWNED_REPORT,
+      );
+    }
+  });
+
+  test("copies the complete report onto the urgency-narrowed channel set", async () => {
+    const available = [
+      "vellum",
+      "telegram",
+      "platform",
+    ] as NotificationChannel[];
+    const decision = await evaluateSignal(
+      makeSchedulerShareSignal({
+        attentionHints: {
+          requiresAction: false,
+          urgency: "medium",
+          isAsyncBackground: true,
+          visibleInSourceNow: false,
+        },
+      }),
+      available,
+    );
+
+    expect(decision.shouldNotify).toBe(true);
+    expect(decision.selectedChannels).toEqual(["vellum"]);
+    expect(decision.reasoningSummary).toBe(
+      "scheduler requested-message pass-through",
+    );
+    expect(decision.renderedCopy.vellum?.body).toBe(SCHEDULER_OWNED_REPORT);
+    expect(decision.renderedCopy.vellum?.conversationSeedMessage).toBe(
+      SCHEDULER_OWNED_REPORT,
+    );
+    expect(decision.renderedCopy.telegram?.body).toBe(SCHEDULER_OWNED_REPORT);
+    expect(decision.renderedCopy.platform?.body).toBe(SCHEDULER_OWNED_REPORT);
+  });
+
+  test("leaves an unowned scheduler requestedMessage on the model path", async () => {
+    const previousSendMessage = providerSendMessage;
+    let providerCalled = false;
+    providerSendMessage = async () => {
+      providerCalled = true;
+      return {};
+    };
+
+    try {
+      const decision = await evaluateSignal(
+        makeSchedulerShareSignal({
+          contextPayload: {
+            requestedMessage: SCHEDULER_OWNED_REPORT,
+            requestedTitle: "Your day",
+          },
+        }),
+        ["vellum", "telegram", "platform"] as NotificationChannel[],
+      );
+
+      expect(providerCalled).toBe(true);
+      expect(decision.verbatimCopy).toBeUndefined();
+      expect(decision.reasoningSummary).not.toBe(
+        "scheduler requested-message pass-through",
+      );
+    } finally {
+      providerSendMessage = previousSendMessage;
+    }
+  });
+
+  test("leaves scheduler notify-mode without the ownership marker on the model path", async () => {
+    const previousSendMessage = providerSendMessage;
+    let providerCalled = false;
+    providerSendMessage = async () => {
+      providerCalled = true;
+      return {};
+    };
+
+    try {
+      const decision = await evaluateSignal(
+        {
+          signalId: "sig-schedule-notify-test-1",
+          createdAt: Date.now(),
+          sourceChannel: "scheduler",
+          sourceContextId: "sched-notify-1",
+          sourceEventName: "schedule.notify",
+          contextPayload: {
+            scheduleId: "sched-notify-1",
+            label: "Take out the trash",
+            message: "Take out the trash",
+          },
+          attentionHints: {
+            requiresAction: true,
+            urgency: "high",
+            isAsyncBackground: false,
+            visibleInSourceNow: false,
+          },
+        },
+        ["vellum", "telegram", "platform"] as NotificationChannel[],
+      );
+
+      expect(providerCalled).toBe(true);
+      expect(decision.verbatimCopy).toBeUndefined();
+      expect(decision.reasoningSummary).not.toBe(
+        "scheduler requested-message pass-through",
+      );
+      expect(decision.reasoningSummary).not.toBe("schedule_result pass-through");
+    } finally {
+      providerSendMessage = previousSendMessage;
+    }
+  });
+});

package/src/notifications/decision-engine.ts

@@ -833,6 +833,19 @@ function buildPassThroughDecision(params: {
   return decision;
 }
 
+function selectDefaultChannelsByUrgency(
+  urgency: NotificationSignal["attentionHints"]["urgency"],
+  availableChannels: NotificationChannel[],
+): NotificationChannel[] {
+  const isUrgent = urgency === "critical" || urgency === "high";
+  if (isUrgent) {
+    return [...availableChannels];
+  }
+  return availableChannels.includes("vellum")
+    ? ["vellum" as NotificationChannel]
+    : [];
+}
+
 /**
  * The deterministic guards every decision passes through once the model,
  * the assistant-tool pass-through, or the fallback has rendered copy.
@@ -870,14 +883,10 @@ export async function evaluateSignal(
   );
   if (signal.sourceChannel === "assistant_tool" && requestedBody) {
     const payload = signal.contextPayload as Record<string, unknown>;
-    const isUrgent =
-      signal.attentionHints.urgency === "critical" ||
-      signal.attentionHints.urgency === "high";
-    const defaultChannels: NotificationChannel[] = isUrgent
-      ? [...availableChannels]
-      : availableChannels.includes("vellum")
-        ? ["vellum" as NotificationChannel]
-        : [];
+    const defaultChannels = selectDefaultChannelsByUrgency(
+      signal.attentionHints.urgency,
+      availableChannels,
+    );
     // Honor `--preferred-channels` as ADDITIVE push targets on top of
     // the default channel set. The notification center (vellum) is the
     // always-on canonical inbox; preferred channels add push surfaces
@@ -926,6 +935,32 @@ export async function evaluateSignal(
     });
   }
 
+  // Scheduler-owned requested copy: the scheduler already authored the
+  // complete message. Ownership requires both the signal source and the
+  // payload marker so schedule.result (requestedMessage, no
+  // requestedBySource) and notify-mode (message, no requestedBySource)
+  // stay on their existing paths. Urgency still chooses channels; every
+  // selected channel keeps the producer body.
+  const requestedBySource = nonEmpty(
+    readPayloadString(signal.contextPayload, "requestedBySource"),
+  );
+  if (
+    signal.sourceChannel === "scheduler" &&
+    requestedBySource === "scheduler" &&
+    requestedBody
+  ) {
+    return buildPassThroughDecision({
+      signal,
+      availableChannels,
+      selectedChannels: selectDefaultChannelsByUrgency(
+        signal.attentionHints.urgency,
+        availableChannels,
+      ),
+      body: requestedBody,
+      reasoningSummary: "scheduler requested-message pass-through",
+    });
+  }
+
   // Schedule-result pass-through: the body is the run's own reply, which is
   // the whole point of the notification — a briefing, a digest, a report. The
   // classifier rewrites bodies into short alerts, which would throw away the

package/src/plugins/defaults/memory/__tests__/memory-retrospective-prompt.test.ts

@@ -115,6 +115,16 @@ For everything else in your review window, use the \`remember\` tool on facts, p
     expect(out).toContain(
       "\n---\n\nIf your review window contains a PROCEDURE you actually carried out",
     );
+    // A refinement overwrites the whole file and the pass has no other read
+    // path to the skill, so the instruction has to point at `current`.
+    expect(out).toContain(
+      "rewriting `body_markdown` from `current.body_markdown` plus what you actually observed in the trace",
+    );
+    // Hints are the retrieval signal; a refinement carries them forward
+    // rather than regenerating them from one trace.
+    expect(out).toContain(
+      "restate `current.activation_hints` (revised only if the procedure's triggers changed",
+    );
     // An UPDATE is announced by a notice whose only account of the change is
     // what the pass passes here, so the instruction has to ask for it.
     expect(out).toContain(

package/src/plugins/defaults/memory/memory-retrospective-prompt.ts

@@ -223,7 +223,7 @@ If your review window contains a PROCEDURE you actually carried out — a sequen
 
 When you do capture a procedure:
 
-1. Deduplicate against existing skills first. Call \`find_similar_skills\` with the procedure's goal as its \`goal\` argument. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored: a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate. Skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it: call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting \`body_markdown\` from what you actually observed in the trace, and pass \`change_summary\` (the update is rejected without it): 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."). The notice shows nothing else about the change, so name the concrete step, value, or gotcha rather than saying the skill was refined. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
+1. Deduplicate against existing skills first. Call \`find_similar_skills\` with the procedure's goal as its \`goal\` argument. Each hit carries a \`source\` (bundled, managed, plugin, workspace, or extra), and a managed hit also carries \`author\` (\`"assistant"\` if you authored it, \`"user"\` if a person did, omitted if untagged). You may only overwrite or refine a skill YOU authored: a hit with \`source: "managed"\` AND \`author: "assistant"\`. ANY other hit means the procedure is ALREADY COVERED: a non-managed source (bundled, plugin, workspace, or extra), OR a managed skill that is NOT \`author: "assistant"\` (a person wrote it, or it is untagged). For an ALREADY COVERED hit do not \`overwrite\` it, do not shadow it by creating a skill with its \`skill_id\`, and do not create a near-duplicate. Skip it. Only when a returned skill is one of your own (\`source: "managed"\`, \`author: "assistant"\`) and is the SAME procedure, UPDATE it. Such a hit carries \`current\`: the skill as it is now, in \`scaffold_managed_skill\`'s own argument names. Call \`scaffold_managed_skill\` with that \`skill_id\` and \`overwrite: true\`, rewriting \`body_markdown\` from \`current.body_markdown\` plus what you actually observed in the trace (keep the steps the trace did not contradict; correct or add the ones it did), restate \`current.activation_hints\` (revised only if the procedure's triggers changed; they are the skill's retrieval signal, not something to regenerate) and every other \`current\` field you are not changing (\`emoji\`, \`category\`, \`includes\`, \`avoid_when\`) since an overwrite replaces the whole file, and pass \`change_summary\` (the update is rejected without it): 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."). The notice shows nothing else about the change, so name the concrete step, value, or gotcha rather than saying the skill was refined. Only CREATE a new skill (fresh \`skill_id\`) when no existing skill of any source covers the procedure. Bias strongly toward reusing or refining your own skills over spawning near-duplicates.
 
 2. Capture procedure-scoped knowledge alongside the body. Failure modes, gotchas, and cached values you observed in the trace (error signatures and how you recovered, preconditions, IDs/paths/endpoints that held steady) belong in companion files passed via \`scaffold_managed_skill\`'s \`files\` input (for example \`references/failure-modes.md\`), and the SKILL.md body should reference them so a future load surfaces them.
 

package/src/runtime/routes/__tests__/acp-routes.test.ts

@@ -302,6 +302,25 @@ describe("GET /v1/acp/sessions — merged in-memory + history", () => {
     ]);
   });
 
+  test("does not expose snapshot-only history metadata", async () => {
+    insertHistoryRow({
+      id: "hist-private",
+      status: "completed",
+      cwd: "/tmp/private-project",
+      authErrorCredential: "credential-digest",
+    });
+
+    const handler = getSessionsHandler();
+    const body = (await handler({})) as ResponseShape;
+    const session = body.sessions.find((entry) => entry.id === "hist-private");
+
+    expect(session).toBeDefined();
+    expect(session).not.toHaveProperty("source");
+    expect(session).not.toHaveProperty("resumable");
+    expect(session).not.toHaveProperty("cwd");
+    expect(session).not.toHaveProperty("authErrorCredential");
+  });
+
   test("returns input/output tokens for live and history sessions", async () => {
     fakeInMemorySessions = [
       {

package/src/runtime/routes/acp-routes.ts

@@ -24,7 +24,13 @@ import {
   AcpResumeError,
   AcpSessionNotFoundError,
 } from "../../acp/session-manager.js";
-import { type AcpSessionState, isLiveAcpStatus } from "../../acp/types.js";
+import {
+  type AcpSessionSnapshot,
+  listAcpSessionSnapshots,
+  snapshotHistoryRow,
+  withCurrentAuthMarkers,
+} from "../../acp/session-snapshot.js";
+import { isLiveAcpStatus } from "../../acp/types.js";
 import {
   AcpSessionModelUpdateEventSchema,
   type AssistantEvent,
@@ -103,11 +109,14 @@ type SessionEntry = z.infer<typeof sessionEntrySchema>;
  * client has no use for it and no way to resolve the other side of the
  * comparison, so serving it would only widen what leaves the daemon.
  */
-type MergedSession = SessionEntry & { authErrorCredential?: string };
+type MergedSession = AcpSessionSnapshot;
 
-/** Drop the comparison's own input before the session goes out on the wire. */
+/** Drop internal snapshot metadata before the session goes out on the wire. */
 function stripMarkerCredential({
-  authErrorCredential: _dropped,
+  authErrorCredential: _credential,
+  source: _source,
+  resumable: _resumable,
+  cwd: _cwd,
   ...session
 }: MergedSession): SessionEntry {
   return session;
@@ -511,7 +520,7 @@ async function listSessions({ queryParams }: RouteHandlerArgs) {
     return resolvedByAgent.get(agentId);
   };
 
-  const { sessions: merged, sawEveryHistoryRow } = listMergedSessions({
+  const { sessions: merged, sawEveryHistoryRow } = listAcpSessionSnapshots({
     limit,
     conversationId,
   });
@@ -552,43 +561,12 @@ async function listSessions({ queryParams }: RouteHandlerArgs) {
   return { sessions: [...page, stripMarkerCredential(marker)] };
 }
 
-/**
- * Blank the failure code on any session whose marker no longer describes the
- * credential its agent would resolve.
- *
- * This comparison is what retires a Connect card: not a sweep that has to run
- * at the right moment, but the marker no longer describing the credential in
- * use. Applied after merging rather than inside the query, so live sessions
- * and history rows are judged by exactly the same rule.
- *
- * Resolved per agent, because precedence is per agent: one alias can carry a
- * configured token while another falls through to the vault. Memoised across
- * the request, since a conversation's marked runs are nearly always one agent
- * and each resolution costs a vault read.
- */
 async function withCurrentMarkersOnly(
   sessions: MergedSession[],
   resolvedFor: (agentId: string) => Promise<string | undefined>,
 ): Promise<SessionEntry[]> {
-  const strip = stripMarkerCredential;
-  if (!sessions.some((s) => s.authErrorCode !== undefined)) {
-    return sessions.map(strip);
-  }
-  const judged: SessionEntry[] = [];
-  for (const session of sessions) {
-    if (session.authErrorCode === undefined) {
-      judged.push(strip(session));
-      continue;
-    }
-    const current = acpAuthMarkerStillCurrent(
-      session.authErrorCredential,
-      await resolvedFor(session.agentId),
-    );
-    judged.push(
-      strip(current ? session : { ...session, authErrorCode: undefined }),
-    );
-  }
-  return judged;
+  const judged = await withCurrentAuthMarkers(sessions, resolvedFor);
+  return judged.map(stripMarkerCredential);
 }
 
 function bulkDeleteSessions({ queryParams }: RouteHandlerArgs) {
@@ -879,128 +857,6 @@ function parseLimit(raw: string | null | undefined): number {
   return Math.min(Math.floor(n), MAX_SESSION_LIMIT);
 }
 
-function listMergedSessions(opts: { limit: number; conversationId?: string }): {
-  sessions: MergedSession[];
-  /**
-   * Whether the history query reached the end of this conversation's rows.
-   *
-   * A short read means there is nothing beyond what was returned, which is the
-   * proof that no marker is hiding outside the page.
-   */
-  sawEveryHistoryRow: boolean;
-} {
-  const manager = getAcpSessionManager();
-  const inMemory = manager.getStatus() as AcpSessionState[];
-
-  const merged = new Map<string, MergedSession>();
-  for (const s of inMemory) {
-    if (opts.conversationId && s.parentConversationId !== opts.conversationId) {
-      continue;
-    }
-    merged.set(s.id, {
-      id: s.id,
-      agentId: s.agentId,
-      acpSessionId: s.acpSessionId,
-      parentConversationId: s.parentConversationId,
-      status: s.status,
-      startedAt: s.startedAt,
-      completedAt: s.completedAt ?? null,
-      error: s.error ?? null,
-      stopReason: s.stopReason ?? null,
-      task: s.task,
-      parentToolUseId: s.parentToolUseId,
-      authErrorCode: s.authErrorCode,
-      authErrorCredential: s.authErrorCredential,
-      model: s.model,
-      availableModels: s.availableModels,
-      modelRevisionEpoch: s.modelRevisionEpoch,
-      modelRevision: s.modelRevision,
-      usedTokens: s.latestUsage?.usedTokens,
-      contextSize: s.latestUsage?.contextSize,
-      costAmount: s.latestUsage?.costAmount,
-      costCurrency: s.latestUsage?.costCurrency,
-      inputTokens: s.latestUsage?.inputTokens,
-      outputTokens: s.latestUsage?.outputTokens,
-      eventLog: manager.getBufferedUpdates(s.id),
-    });
-  }
-
-  const db = getDb();
-  const baseQuery = db.select().from(acpSessionHistory);
-  const filtered = opts.conversationId
-    ? baseQuery.where(
-        eq(acpSessionHistory.parentConversationId, opts.conversationId),
-      )
-    : baseQuery;
-  // Fetch only enough rows to fill the requested page after merging with
-  // in-memory sessions. In-memory entries take precedence on id collision,
-  // so we pad by the count that survived the conversation filter to
-  // guarantee we still surface `limit` distinct rows even when every
-  // in-memory session shadows a DB row — without over-fetching when many
-  // unrelated sessions are in memory.
-  const historyLimit = opts.limit + merged.size;
-  const historyRows = filtered
-    .orderBy(desc(acpSessionHistory.startedAt))
-    .limit(historyLimit)
-    .all();
-
-  for (const row of historyRows) {
-    if (merged.has(row.id)) {
-      continue;
-    }
-    merged.set(row.id, toMergedSession(row));
-  }
-
-  return {
-    sessions: Array.from(merged.values()).sort(
-      (a, b) => b.startedAt - a.startedAt,
-    ),
-    sawEveryHistoryRow: historyRows.length < historyLimit,
-  };
-}
-
-/** Shape a history row for the response, parsing its stored event log. */
-function toMergedSession(
-  row: typeof acpSessionHistory.$inferSelect,
-): MergedSession {
-  let eventLog: unknown[] = [];
-  try {
-    const parsed = JSON.parse(row.eventLogJson) as unknown;
-    if (Array.isArray(parsed)) {
-      eventLog = parsed;
-    }
-  } catch (err) {
-    log.warn(
-      { id: row.id, err },
-      "Failed to parse event_log_json for ACP session history row",
-    );
-  }
-  // Rows predating the usage migration carry NULLs for these columns and
-  // degrade to undefined.
-  return {
-    id: row.id,
-    agentId: row.agentId,
-    acpSessionId: row.acpSessionId,
-    parentConversationId: row.parentConversationId,
-    status: row.status,
-    startedAt: row.startedAt,
-    completedAt: row.completedAt,
-    error: row.error,
-    stopReason: row.stopReason,
-    task: row.task ?? undefined,
-    parentToolUseId: row.parentToolUseId ?? undefined,
-    authErrorCode: row.authErrorCode ?? undefined,
-    authErrorCredential: row.authErrorCredential ?? undefined,
-    usedTokens: row.usedTokens ?? undefined,
-    contextSize: row.contextSize ?? undefined,
-    costAmount: row.costAmount ?? undefined,
-    costCurrency: row.costCurrency ?? undefined,
-    inputTokens: row.inputTokens ?? undefined,
-    outputTokens: row.outputTokens ?? undefined,
-    eventLog,
-  };
-}
-
 /**
  * Reach past the page for the one marked run a client would restore the card
  * from, when the page itself holds none.
@@ -1061,7 +917,7 @@ async function findRecoveryMarker(
         .from(acpSessionHistory)
         .where(eq(acpSessionHistory.id, marker.id))
         .get();
-      return row ? toMergedSession(row) : undefined;
+      return row ? snapshotHistoryRow(row) : undefined;
     }
   }
   return undefined;

package/src/skills/managed-store.ts

@@ -14,10 +14,12 @@ import { dirname, isAbsolute, join, normalize, relative, sep } from "node:path";
 
 import { stringify as stringifyYaml } from "yaml";
 
+import { parseFrontmatter } from "../config/skills.js";
 import { deleteSkillCapabilityNode } from "../plugins/defaults/memory/graph/capability-seed.js";
 import { isDeniedBasename } from "../tools/shared/filesystem/path-policy.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir, getWorkspaceSkillsDir } from "../util/platform.js";
+import { parseFrontmatterFields } from "./frontmatter.js";
 import { writeInstallMeta } from "./install-meta.js";
 
 const log = getLogger("managed-store");
@@ -450,6 +452,60 @@ export function createManagedSkill(
   return { created: true, path: skillFilePath };
 }
 
+/**
+ * A managed skill as it is on disk. Frontmatter fields come through the
+ * catalog's parser so they are exactly what routing and the Skills UI see;
+ * `body` is the stored text after the frontmatter, verbatim except for the
+ * separator newline the store writes before it and the trailing newline it
+ * guarantees. Verbatim matters: the skill loader substitutes `{baseDir}` and
+ * `{workspaceDir}` and strips feature-gated sections, and a caller that wrote
+ * that output back would bake absolute paths into the skill; and a first line
+ * that opens an indented code block must keep its indentation or a copy turns
+ * it into prose.
+ */
+export interface StoredManagedSkill {
+  name: string;
+  description: string;
+  emoji?: string;
+  includes?: string[];
+  activationHints?: string[];
+  avoidWhen?: string[];
+  category?: string;
+  body: string;
+}
+
+/**
+ * Read a managed skill from disk. Best-effort: a missing file or frontmatter
+ * that does not parse resolves to null, so a caller enriching or patching one
+ * skill never fails on a bad one.
+ */
+export function readStoredManagedSkill(
+  skillId: string,
+): StoredManagedSkill | null {
+  const skillFilePath = join(getManagedSkillDir(skillId), "SKILL.md");
+  try {
+    const content = readFileSync(skillFilePath, "utf-8");
+    const parsed = parseFrontmatter(content, skillFilePath);
+    const raw = parseFrontmatterFields(content);
+    if (!parsed || !raw) {
+      return null;
+    }
+    return {
+      name: parsed.name,
+      description: parsed.description,
+      emoji: parsed.emoji,
+      includes: parsed.includes,
+      activationHints: parsed.activationHints,
+      avoidWhen: parsed.avoidWhen,
+      category: parsed.category,
+      body: raw.body.replace(/^(?:\r?\n)+/, "").replace(/(?:\r?\n)+$/, ""),
+    };
+  } catch (err) {
+    log.warn({ err, skillFilePath }, "Could not read managed skill");
+    return null;
+  }
+}
+
 interface DeleteManagedSkillResult {
   deleted: boolean;
   error?: string;