@nimbus-dev/connectors 0.4.0 → 0.6.0

package/connectors/launchdarkly/src/flag-state.ts

@@ -0,0 +1,178 @@
+/**
+ * Pure helpers for the LaunchDarkly flag tools: the one-environment read projection and the
+ * rollout-weight arithmetic. Kept apart from the tool registration so both are testable alone.
+ */
+
+/** LaunchDarkly rollout weights are thousandths of a percent: 0..100000, and a flag sums to 100000. */
+export const FULL_ROLLOUT = 100_000;
+
+export interface RolloutWeightInput {
+  readonly variationId: string;
+  readonly percent: number;
+}
+
+/**
+ * `weights` as the `rolloutWeights` map the semantic patch takes (variation id -> thousandths of a
+ * percent). Fails closed: duplicate ids, a percent with more than three decimals, or a total that is
+ * not EXACTLY 100% all throw before any request is made. (The API only says the sum "should" be 100%;
+ * what it does on a mismatch is not stated, so this connector does not find out on a production flag.)
+ */
+export function rolloutWeightsOf(weights: readonly RolloutWeightInput[]): Record<string, number> {
+  const out: Record<string, number> = {};
+  let total = 0;
+  for (const w of weights) {
+    if (Object.hasOwn(out, w.variationId)) {
+      throw new Error(`variationId ${w.variationId} appears more than once`);
+    }
+    const thousandths = Math.round(w.percent * 1000);
+    if (Math.abs(w.percent * 1000 - thousandths) > 1e-6) {
+      throw new Error(`percent ${String(w.percent)} has more than 3 decimal places`);
+    }
+    out[w.variationId] = thousandths;
+    total += thousandths;
+  }
+  if (total !== FULL_ROLLOUT) {
+    throw new Error(
+      `weights must sum to exactly 100 percent, got ${String(total / 1000)}; nothing was changed`,
+    );
+  }
+  return out;
+}
+
+/** The `on` a flag-change reply shows for `environmentKey`, when it is a boolean. */
+export function echoedOn(response: unknown, environmentKey: string): boolean | undefined {
+  const envs =
+    isRecord(response) && isRecord(response["environments"]) ? response["environments"] : {};
+  const env = envs[environmentKey];
+  return isRecord(env) && typeof env["on"] === "boolean" ? env["on"] : undefined;
+}
+
+/** `environmentKey`'s fallthrough rollout object in a flag-change reply, when there is one. */
+function fallthroughRolloutOf(
+  response: Record<string, unknown>,
+  environmentKey: string,
+): Record<string, unknown> | undefined {
+  const envs = isRecord(response["environments"]) ? response["environments"] : {};
+  const env = envs[environmentKey];
+  const fallthrough = isRecord(env) && isRecord(env["fallthrough"]) ? env["fallthrough"] : {};
+  const rollout = fallthrough["rollout"];
+  return isRecord(rollout) ? rollout : undefined;
+}
+
+/**
+ * The echoed rollout weights by variation id, or `undefined` when any entry cannot be resolved to a
+ * variation id and a numeric weight.
+ */
+function echoedWeights(
+  rollout: Record<string, unknown>,
+  variations: readonly unknown[],
+): Record<string, number> | undefined {
+  const echoed: Record<string, number> = {};
+  const entries = Array.isArray(rollout["variations"]) ? rollout["variations"] : [];
+  for (const entry of entries) {
+    const row = isRecord(entry) ? entry : {};
+    const index = row["variation"];
+    const weight = row["weight"];
+    const variation = typeof index === "number" ? variations[index] : undefined;
+    const id = isRecord(variation) ? variation["_id"] : undefined;
+    if (typeof id !== "string" || typeof weight !== "number") return undefined;
+    echoed[id] = weight;
+  }
+  return echoed;
+}
+
+/**
+ * True only when the reply carries `environmentKey`'s fallthrough rollout and its weights (by
+ * variation id, a missing id counting as 0) equal `requested`. A reply without them is not a
+ * confirmation.
+ */
+export function rolloutEchoed(
+  response: unknown,
+  environmentKey: string,
+  requested: Readonly<Record<string, number>>,
+): boolean {
+  if (!isRecord(response)) return false;
+  const rollout = fallthroughRolloutOf(response, environmentKey);
+  if (rollout === undefined || !Array.isArray(rollout["variations"])) return false;
+  const variations = Array.isArray(response["variations"]) ? response["variations"] : [];
+  const echoed = echoedWeights(rollout, variations);
+  if (echoed === undefined) return false;
+  const ids = new Set([...Object.keys(requested), ...Object.keys(echoed)]);
+  for (const id of ids) {
+    if ((requested[id] ?? 0) !== (echoed[id] ?? 0)) return false;
+  }
+  return true;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function numberOrUndefined(v: unknown): number | undefined {
+  return typeof v === "number" ? v : undefined;
+}
+
+/**
+ * The state of one flag in one environment, from `GET /flags/{p}/{f}?env={e}`.
+ *
+ * Variation references (`fallthrough.variation`, `offVariation`, `rollout.variations[].variation`)
+ * are read as INDICES into `variations[]`, which is how the schema describes `fallthrough.variation`.
+ * The same schema calls `offVariation` an "ID" in one place; the raw number is returned beside the
+ * resolved id so a caller can see which reading applied. Pinned by a fixture; live-check item.
+ */
+export function projectFlagState(
+  raw: unknown,
+  ids: { projectKey: string; flagKey: string; environmentKey: string },
+): Record<string, unknown> {
+  const flag = isRecord(raw) ? raw : {};
+  const envs = isRecord(flag["environments"]) ? flag["environments"] : {};
+  const env = envs[ids.environmentKey];
+  if (!isRecord(env)) {
+    throw new Error(`LaunchDarkly environment not found: ${ids.environmentKey}`);
+  }
+  const rawVariations = Array.isArray(flag["variations"]) ? flag["variations"] : [];
+  const variations = rawVariations.map((v, index) => {
+    const row = isRecord(v) ? v : {};
+    return { index, id: row["_id"], name: row["name"], value: row["value"] };
+  });
+  const idAt = (index: unknown): unknown =>
+    typeof index === "number" ? variations[index]?.id : undefined;
+
+  const fallthroughRaw = isRecord(env["fallthrough"]) ? env["fallthrough"] : {};
+  const fallthrough: Record<string, unknown> = {};
+  if (typeof fallthroughRaw["variation"] === "number") {
+    fallthrough["variation"] = fallthroughRaw["variation"];
+    fallthrough["variationId"] = idAt(fallthroughRaw["variation"]);
+  }
+  const rollout = fallthroughRaw["rollout"];
+  if (isRecord(rollout) && Array.isArray(rollout["variations"])) {
+    fallthrough["rollout"] = rollout["variations"].map((entry) => {
+      const row = isRecord(entry) ? entry : {};
+      const weight = numberOrUndefined(row["weight"]);
+      return {
+        variation: row["variation"],
+        variationId: idAt(row["variation"]),
+        weightPercent: weight === undefined ? undefined : weight / 1000,
+      };
+    });
+  }
+  if (isRecord(rollout)) {
+    if (typeof rollout["bucketBy"] === "string")
+      fallthrough["rolloutBucketBy"] = rollout["bucketBy"];
+    if (typeof rollout["contextKind"] === "string") {
+      fallthrough["rolloutContextKind"] = rollout["contextKind"];
+    }
+  }
+  return {
+    projectKey: ids.projectKey,
+    flagKey: ids.flagKey,
+    environmentKey: ids.environmentKey,
+    on: env["on"],
+    offVariation: env["offVariation"],
+    offVariationId: idAt(env["offVariation"]),
+    fallthrough,
+    variations,
+    version: numberOrUndefined(env["version"]) ?? numberOrUndefined(flag["_version"]),
+    archived: flag["archived"],
+  };
+}

package/connectors/launchdarkly/src/server.ts

@@ -1,6 +1,14 @@
-import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "../../../shared/consent-kit.ts";
 import { registerLaunchdarklyTools } from "./tools.ts";
 
-await runReadOnlyMcpConnector("nimbus-launchdarkly", (reg) => {
-  registerLaunchdarklyTools(reg);
-});
+const server = new McpServer(
+  { name: "nimbus-launchdarkly", version: "0.1.0" },
+  { capabilities: CONSENT_SERVER_CAPABILITIES },
+);
+
+registerLaunchdarklyTools(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/launchdarkly/src/tools.ts

@@ -1,32 +1,133 @@
 import { z } from "zod";
-import { createJsonGetter, envAuthHeaders, optionalEnv } from "../../../shared/env-json-api.ts";
+import { type ConsentServer, createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createJsonGetter,
+  createJsonSender,
+  envAuthHeaders,
+  type JsonApiConfig,
+  optionalEnv,
+} from "../../../shared/env-json-api.ts";
 import { matchesResult } from "../../../shared/mcp-search-tool.ts";
-import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
-import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+} from "../../../shared/mcp-tool-kit.ts";
+import { echoedOn, projectFlagState, rolloutEchoed, rolloutWeightsOf } from "./flag-state.ts";
 import { filterLaunchDarklyFlags } from "./search-filter.ts";
 
 const DEFAULT_BASE = "https://app.launchdarkly.com";
 
-const ldGet = createJsonGetter({
+const api: JsonApiConfig = {
   // `optionalEnv`, not `optionalBaseUrl`: a trailing slash on the override is left as given.
   base: () => `${optionalEnv("LAUNCHDARKLY_BASE_URL", DEFAULT_BASE)}/api/v2`,
   label: "LaunchDarkly",
   headers: envAuthHeaders({ env: "LAUNCHDARKLY_TOKEN", scheme: "" }),
-});
+};
+
+const ldGet = createJsonGetter(api);
+const ldSend = createJsonSender(api);
+
+/**
+ * A semantic patch needs `domain-model=launchdarkly.semanticpatch` appended to Content-Type, else
+ * LaunchDarkly treats the body as a JSON patch and answers 400
+ * (https://launchdarkly.com/docs/guides/api/rest-api, "append `domain-model=launchdarkly.semanticpatch`
+ * to your `Content-Type` header").
+ */
+const SEMANTIC_PATCH_HEADERS = {
+  "Content-Type": "application/json; domain-model=launchdarkly.semanticpatch",
+} as const;
+
+/** Written into the flag's change history, so the audit trail says who made the change. */
+const CHANGE_COMMENT = "Changed by Nimbus after owner approval";
 
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const LAUNCHDARKLY_TOOL_NAMES = [
   "launchdarkly_list",
   "launchdarkly_get",
   "launchdarkly_search",
+  "launchdarkly_flag_state_get",
+  "launchdarkly_flag_toggle",
+  "launchdarkly_flag_rollout_set",
 ] as const;
 
-export function registerLaunchdarklyTools(reg: ZodToolRegistrar): void {
+/**
+ * LaunchDarkly project, environment and flag keys: letters, digits, `.`, `_`, `-`, but never `.` or
+ * `..` alone: `encodeURIComponent("..")` is `..`, and a URL parser collapses it out of the path.
+ */
+const keyArg = z
+  .string()
+  .regex(
+    /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,128}$/,
+    "letters, digits, '.', '_' and '-' only; not '.' or '..'",
+  );
+
+/** The read tools keep accepting any key (it is percent-encoded), but never a dot segment. */
+const readKeyArg = z
+  .string()
+  .min(1)
+  .regex(/^(?!\.{1,2}$)/, "not '.' or '..'");
+
+const flagArgs = z.object({
+  projectKey: keyArg,
+  environmentKey: keyArg,
+  flagKey: keyArg,
+});
+
+type FlagArgs = z.infer<typeof flagArgs>;
+
+function flagPath(p: { projectKey: string; flagKey: string }): string {
+  return `/flags/${encodeURIComponent(p.projectKey)}/${encodeURIComponent(p.flagKey)}`;
+}
+
+/** One environment's slice of a flag, so the read stays small however many environments exist. */
+async function readFlagState(p: FlagArgs): Promise<Record<string, unknown>> {
+  const search = new URLSearchParams({ env: p.environmentKey });
+  const raw = await ldGet(`${flagPath(p)}?${search.toString()}`);
+  return projectFlagState(raw, p);
+}
+
+/**
+ * The result of a flag change: the facts, not LaunchDarkly's whole flag document. `confirmed` is
+ * true only when the reply SHOWS the requested state; false means the server accepted the write
+ * but its reply does not show the new state.
+ */
+function changed(
+  p: FlagArgs,
+  response: unknown,
+  confirmed: (response: unknown) => boolean,
+): Record<string, unknown> {
+  const flag = (response ?? {}) as { environments?: Record<string, { on?: unknown }> };
+  return {
+    ok: true,
+    confirmed: confirmed(response),
+    projectKey: p.projectKey,
+    environmentKey: p.environmentKey,
+    flagKey: p.flagKey,
+    on: flag.environments?.[p.environmentKey]?.on,
+  };
+}
+
+/** Scope: `flag:<projectKey>/<environmentKey>/<flagKey>`. */
+function flagScope(p: FlagArgs): { kind: string; value: string } {
+  return { kind: "flag", value: `${p.projectKey}/${p.environmentKey}/${p.flagKey}` };
+}
+
+export function registerLaunchdarklyTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+  const registerWriteTool = createWriteToolRegistrar(server, {
+    connector: "launchdarkly",
+    scopeEnv: "NIMBUS_MCP_LAUNCHDARKLY_WRITE_SCOPE",
+    scopeKinds: ["flag"],
+  });
+
   reg(
     "launchdarkly_list",
     "List LaunchDarkly projects, or feature flags for a project. Without `projectKey`, returns the account's projects (`/projects`). With `projectKey`, returns that project's flags (`/flags/{projectKey}`), capped at `limit` (default 100).",
     z.object({
-      projectKey: z.string().min(1).optional(),
+      projectKey: readKeyArg.optional(),
       limit: z.number().int().min(1).max(500).optional(),
     }),
     async (p) => {
@@ -44,8 +145,8 @@ export function registerLaunchdarklyTools(reg: ZodToolRegistrar): void {
     "launchdarkly_get",
     "Fetch one LaunchDarkly feature flag by project key + flag key. Throws when no match is found.",
     z.object({
-      projectKey: z.string().min(1),
-      flagKey: z.string().min(1),
+      projectKey: readKeyArg,
+      flagKey: readKeyArg,
     }),
     async (p) => {
       return jsonResult(
@@ -58,7 +159,7 @@ export function registerLaunchdarklyTools(reg: ZodToolRegistrar): void {
     "launchdarkly_search",
     "Substring search across a project's feature flags. Matches the query against flag key, name, description, and tags (case-insensitive). Returns a `{ matches: [...] }` envelope.",
     z.object({
-      projectKey: z.string().min(1),
+      projectKey: readKeyArg,
       query: z.string().min(1),
       limit: z.number().int().min(1).max(200).optional(),
     }),
@@ -69,4 +170,77 @@ export function registerLaunchdarklyTools(reg: ZodToolRegistrar): void {
       return matchesResult(flags, filterLaunchDarklyFlags, p);
     },
   );
+
+  reg(
+    "launchdarkly_flag_state_get",
+    "Read one feature flag's state in ONE environment (`GET /flags/{projectKey}/{flagKey}?env={environmentKey}`): on/off, off variation, fallthrough (a single variation or a percentage rollout, with variation ids and weights in percent), the variation list and the environment's version. Smaller than `launchdarkly_get`, which returns every environment. Variation references are read as indices into `variations` (LaunchDarkly's schema is ambiguous for `offVariation`); the raw number is returned beside the resolved id.",
+    flagArgs,
+    async (p) => jsonResult(await readFlagState(p)),
+  );
+
+  registerWriteTool(
+    "launchdarkly_flag_toggle",
+    {
+      mutates: "launchdarkly.flag.toggle",
+      recoverable: true,
+      scopeTargetOf: flagScope,
+    },
+    "Turn a feature flag on or off in ONE environment (`PATCH /flags/{projectKey}/{flagKey}`, semantic patch turnFlagOn / turnFlagOff). Reversible by toggling back. An environment that requires approvals answers 405 and nothing changes.",
+    flagArgs.extend({ on: z.boolean() }),
+    async (p) => {
+      const response = await ldSend(
+        "PATCH",
+        flagPath(p),
+        {
+          environmentKey: p.environmentKey,
+          comment: CHANGE_COMMENT,
+          instructions: [{ kind: p.on ? "turnFlagOn" : "turnFlagOff" }],
+        },
+        SEMANTIC_PATCH_HEADERS,
+      );
+      return jsonResult(changed(p, response, (r) => echoedOn(r, p.environmentKey) === p.on));
+    },
+  );
+
+  registerWriteTool(
+    "launchdarkly_flag_rollout_set",
+    {
+      mutates: "launchdarkly.flag.rollout.set",
+      // The previous fallthrough (variation or weights, bucketBy, context kind) is recorded in the
+      // audit pre-state. This tool does not restore it, so the write is not marked recoverable.
+      recoverable: false,
+      capturePreState: readFlagState,
+      scopeTargetOf: flagScope,
+    },
+    "Set a feature flag's fallthrough to a percentage rollout in ONE environment (`PATCH /flags/{projectKey}/{flagKey}`, semantic patch updateFallthroughVariationOrRollout). `weights` maps variation ids (from `launchdarkly_flag_state_get`) to percent; they must sum to exactly 100 with at most 3 decimals, else nothing is sent. The previous fallthrough is recorded in the audit pre-state; this tool does not restore it, and a rollout's bucketBy / context kind are not set by it.",
+    flagArgs.extend({
+      weights: z
+        .array(
+          z.object({
+            variationId: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/),
+            percent: z.number().min(0).max(100),
+          }),
+        )
+        .min(1)
+        .max(20),
+    }),
+    async (p) => {
+      // Validated here, not with `.refine` on the schema: a refined schema loses `.shape`, which
+      // the registrar passes to the MCP SDK as the tool's input schema.
+      const rolloutWeights = rolloutWeightsOf(p.weights);
+      const response = await ldSend(
+        "PATCH",
+        flagPath(p),
+        {
+          environmentKey: p.environmentKey,
+          comment: CHANGE_COMMENT,
+          instructions: [{ kind: "updateFallthroughVariationOrRollout", rolloutWeights }],
+        },
+        SEMANTIC_PATCH_HEADERS,
+      );
+      return jsonResult(
+        changed(p, response, (r) => rolloutEchoed(r, p.environmentKey, rolloutWeights)),
+      );
+    },
+  );
 }

package/connectors/obsidian/nimbus.extension.json

@@ -2,7 +2,7 @@
   "id": "com.nimbus.obsidian",
   "displayName": "Obsidian",
   "version": "0.1.0",
-  "description": "Local Obsidian vault connector (notes, backlinks). No network. Vault paths come from [[filesystem.roots]] and are merged into permissions.filesystem at spawn time by the Gateway. obsidian_append_to_daily_note requires HITL.",
+  "description": "Local Obsidian vault connector (notes, backlinks, daily notes). No network. Vault paths come from [[filesystem.roots]] and are merged into permissions.filesystem.read at spawn time by the Gateway, which may also add the vaults to permissions.filesystem.write at spawn (only while the owner has approved obsidian_append_to_daily_note for the model). obsidian_append_to_daily_note requires HITL; obsidian_daily_note_get is a read.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
   "runtime": "bun",

package/connectors/obsidian/src/tools.ts

@@ -2,11 +2,13 @@ import { createHash } from "node:crypto";
 import {
   closeSync,
   fstatSync,
+  lstatSync,
   mkdirSync,
   openSync,
   readdirSync,
   readFileSync,
   readSync,
+  realpathSync,
   statSync,
   writeSync,
 } from "node:fs";
@@ -54,6 +56,93 @@ function assertWithinVault(vaultRoot: string, relPath: string): string {
   return candidate;
 }
 
+/** Whether anything, a dangling link included, sits at `p`. */
+function pathEntryExists(p: string): boolean {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Refuse `abs` (a path `assertWithinVault` already accepted) when the place it really names is
+ * outside the vault: a folder or note that is, or passes through, a symlink or junction out of the
+ * vault. `assertWithinVault` compares strings, so it cannot see a link.
+ *
+ * The note, and the folders above it, may not exist yet (the append creates them), so the check
+ * resolves the deepest part of the path that does exist; whatever is created below it is created
+ * inside it. A dangling link cannot be resolved and is refused. The check and the later open are
+ * two system calls, so a link swapped in between them is not seen here: the gateway's sandbox,
+ * which grants only the vaults, is the boundary (stated bound).
+ */
+export function assertRealpathWithinVault(vaultRoot: string, abs: string, relPath: string): void {
+  const realRoot = realpathSync(resolve(vaultRoot));
+  const prefix = realRoot.endsWith(sep) ? realRoot : realRoot + sep;
+  let probe = abs;
+  while (!pathEntryExists(probe)) {
+    const parent = dirname(probe);
+    if (parent === probe) break;
+    probe = parent;
+  }
+  let real: string;
+  try {
+    real = realpathSync(probe);
+  } catch {
+    throw new Error(`Path escapes vault: ${relPath}`);
+  }
+  if (real !== realRoot && !real.startsWith(prefix)) {
+    throw new Error(`Path escapes vault: ${relPath}`);
+  }
+}
+
+/** How much of the end of a daily note `obsidian_daily_note_get` returns. */
+export const DAILY_NOTE_TAIL_BYTES = 16 * 1024;
+
+/** The positioned-read signature of `readSync`, injectable so a test can count what is read. */
+export type PositionedRead = (
+  fd: number,
+  buffer: Buffer,
+  offset: number,
+  length: number,
+  position: number,
+) => number;
+
+/**
+ * The size of the file at `abs` and its last `maxBytes` bytes, decoded as UTF-8.
+ *
+ * Positioned reads of at most `maxBytes` in all, never the whole file. When the window starts
+ * inside the file, the UTF-8 continuation bytes it begins with (the rest of a character the window
+ * cut) are dropped, so the tail starts on a character boundary.
+ */
+export function readUtf8Tail(
+  abs: string,
+  maxBytes: number,
+  read: PositionedRead = readSync,
+): { size: number; tail: string } {
+  const fd = openSync(abs, "r");
+  try {
+    const size = fstatSync(fd).size;
+    const start = Math.max(0, size - maxBytes);
+    const length = size - start;
+    const buf = Buffer.alloc(length);
+    let got = 0;
+    while (got < length) {
+      const n = read(fd, buf, got, length - got, start + got);
+      if (n <= 0) break;
+      got += n;
+    }
+    let skip = 0;
+    if (start > 0) {
+      while (skip < 3 && skip < got && ((buf[skip] ?? 0) & 0xc0) === 0x80) skip++;
+    }
+    return { size, tail: buf.subarray(skip, got).toString("utf8") };
+  } finally {
+    closeSync(fd);
+  }
+}
+
 function loadVaultPaths(): readonly string[] {
   const raw = requireProcessEnv("OBSIDIAN_VAULT_PATHS_JSON");
   let parsed: unknown;
@@ -98,7 +187,10 @@ function walkForVaults(dir: string, out: VaultEntry[]): void {
     const sub = join(dir, e);
     let isDir = false;
     try {
-      const st = statSync(sub);
+      // lstat, not stat: stat follows a link, so its isSymbolicLink() was always false and
+      // discovery used to find a vault through a symlink or junction outside the configured root.
+      // Every link below a root is skipped, so a discovered vault is physically under its root.
+      const st = lstatSync(sub);
       isDir = st.isDirectory() && !st.isSymbolicLink();
     } catch {
       continue;
@@ -128,7 +220,9 @@ function walkNotes(currentDir: string, vaultRoot: string, out: string[]): void {
     let isFile = false;
     let isDir = false;
     try {
-      const st = statSync(full);
+      // lstat, not stat: stat follows a link, so its isSymbolicLink() is always false and the
+      // walk used to list notes through a symlink or junction, out of the vault included.
+      const st = lstatSync(full);
       if (st.isSymbolicLink()) continue;
       isFile = st.isFile();
       isDir = st.isDirectory();
@@ -151,6 +245,7 @@ function readNote(
   relPath: string,
 ): { title: string; body: string; raw: string } {
   const abs = assertWithinVault(vaultRoot, relPath);
+  assertRealpathWithinVault(vaultRoot, abs, relPath);
   const raw = readFileSync(abs, "utf8");
   const m = FRONTMATTER_RE.exec(raw);
   const body = m === null ? raw : raw.slice(m[0].length);
@@ -193,6 +288,7 @@ export const OBSIDIAN_TOOL_NAMES = [
   "obsidian_get",
   "obsidian_search",
   "obsidian_append_to_daily_note",
+  "obsidian_daily_note_get",
 ] as const;
 
 /** The date tokens an Obsidian daily-note filename format may contain. */
@@ -400,6 +496,28 @@ export function registerObsidianTools(
     }),
   );
 
+  /**
+   * The vault and the daily note a daily-note tool names: ONE resolution, shared by the append and
+   * the read, so the read shows exactly the note the append would write. String containment
+   * (`assertWithinVault`) and then realpath containment (`assertRealpathWithinVault`).
+   */
+  function resolveDailyNote(parsed: { vault_id: string; date_iso?: string | undefined }): {
+    v: VaultEntry;
+    rel: string;
+    abs: string;
+  } {
+    const v = findVaultByIdOrPathPrefix(VAULTS, parsed.vault_id);
+    if (v === undefined) {
+      throw new Error("Unknown vault_id");
+    }
+    const date =
+      parsed.date_iso === undefined ? new Date() : new Date(`${parsed.date_iso}T00:00:00Z`);
+    const rel = resolveDailyNoteRelativePath(v.root, date);
+    const abs = assertWithinVault(v.root, rel);
+    assertRealpathWithinVault(v.root, abs, rel);
+    return { v, rel, abs };
+  }
+
   const appendDailyNoteSchema = z.object({
     vault_id: z.string().min(1),
     content: z.string().min(1),
@@ -420,15 +538,10 @@ export function registerObsidianTools(
     "Append text to today's Obsidian daily note. Creates the file if it does not exist. Always appends — never overwrites. Adds a leading newline when the existing file does not end in one. Requires HITL `obsidian.note.append`.",
     appendDailyNoteSchema,
     syncToolHandler((parsed) => {
-      const v = findVaultByIdOrPathPrefix(VAULTS, parsed.vault_id);
-      if (v === undefined) {
-        throw new Error("Unknown vault_id");
-      }
-      const date =
-        parsed.date_iso === undefined ? new Date() : new Date(`${parsed.date_iso}T00:00:00Z`);
-      const rel = resolveDailyNoteRelativePath(v.root, date);
-      const abs = assertWithinVault(v.root, rel);
+      const { v, rel, abs } = resolveDailyNote(parsed);
       mkdirSync(dirname(abs), { recursive: true });
+      // Again, now the folders exist: what was created must still be inside the vault.
+      assertRealpathWithinVault(v.root, abs, rel);
 
       const fd = openSync(abs, "a+");
       let bytes = 0;
@@ -463,4 +576,39 @@ export function registerObsidianTools(
       });
     }),
   );
+
+  const dailyNoteGetSchema = z.object({
+    vault_id: z.string().min(1),
+    date_iso: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/)
+      .optional(),
+  });
+
+  reg(
+    "obsidian_daily_note_get",
+    `Read the end of the Obsidian daily note that obsidian_append_to_daily_note would write for the same vault_id and date_iso (today in UTC when omitted). Returns { vault_id, vault_name, path, exists, size_bytes, tail }: tail is at most the last ${String(DAILY_NOTE_TAIL_BYTES)} bytes, starting on a character boundary; a missing note is exists: false, size_bytes: 0, tail "". Read-only.`,
+    dailyNoteGetSchema,
+    syncToolHandler((parsed) => {
+      const { v, rel, abs } = resolveDailyNote(parsed);
+      let exists = false;
+      let size = 0;
+      let tail = "";
+      if (pathEntryExists(abs)) {
+        if (!statSync(abs).isFile()) {
+          throw new Error(`Daily note is not a file: ${rel}`);
+        }
+        exists = true;
+        ({ size, tail } = readUtf8Tail(abs, DAILY_NOTE_TAIL_BYTES));
+      }
+      return jsonResult({
+        vault_id: v.id,
+        vault_name: v.name,
+        path: rel,
+        exists,
+        size_bytes: size,
+        tail,
+      });
+    }),
+  );
 }