@agent-native/core 0.70.2 → 0.71.0

package/corpus/core/src/agent/run-manager.ts

@@ -64,9 +64,42 @@ export const DEFAULT_HOSTED_RUN_SOFT_TIMEOUT_MS = 40_000;
  * env value just guarantees the cutoff is a hard error instead of a graceful
  * hand-off. Any resolved value above this is clamped down when hosted. Local
  * dev (non-hosted) is left alone so long-running local turns aren't chunked.
+ *
+ * IMPORTANT: this clamp is for the INTERACTIVE / foreground path and must NOT
+ * be raised. The foreground POST still rides a synchronous serverless function
+ * (~60-65s wall), so 40s remains correct there. The only sanctioned exception
+ * is the opt-in `backgroundFunction` mode (see
+ * `BACKGROUND_SOFT_TIMEOUT_CEILING_MS`), which runs inside a Netlify background
+ * function (no ~60s wall, 15-min budget) and therefore can safely outlast 40s.
  */
 export const HOSTED_SOFT_TIMEOUT_CEILING_MS = 40_000;
 
+/**
+ * Hard ceiling for the soft timeout when a run executes inside a Netlify
+ * background function (any deployed function whose name ends in `-background`).
+ * Background functions return 202 immediately and run detached for up to 15
+ * minutes, so the ~60s synchronous function wall that 40s defends against does
+ * NOT apply. 13 minutes leaves ~2 min of headroom under Netlify's 15-min hard
+ * kill to abort, persist the partial turn, write the terminal event, and (for
+ * the rare >13-min turn) self-fire another background continuation.
+ *
+ * This ceiling is used ONLY when a caller explicitly opts in with
+ * `backgroundFunction: true`. It does not change the foreground/interactive
+ * ceiling and does not fire unless the durable-background path dispatched the
+ * run into a background function. Per the design doc Guardrail, the 40s
+ * interactive clamp stays correct for every non-background run.
+ */
+export const BACKGROUND_SOFT_TIMEOUT_CEILING_MS = 13 * 60_000; // 780_000
+
+/**
+ * Default soft-timeout budget for a background-function run when the caller
+ * does not pass an explicit `softTimeoutMs`. Same value as the ceiling — we
+ * want a background turn to use nearly its whole 15-min budget before handing
+ * off to a chained background continuation.
+ */
+export const DEFAULT_BACKGROUND_RUN_SOFT_TIMEOUT_MS =
+  BACKGROUND_SOFT_TIMEOUT_CEILING_MS;
+
 /** Default SQL retention for completed run event logs (24 hours). */
 export const DEFAULT_COMPLETED_RUN_RETENTION_MS = 24 * 60 * 60 * 1000;
 
@@ -137,10 +170,28 @@ export interface StartRunOptions {
    * share one `turnId` so the durable assistant message can be folded across
    * them instead of dropped per-run. Defaults to the runId (turn == run). */
   turnId?: string;
+  /**
+   * Opt into the durable-background-function soft-timeout regime for THIS run
+   * only. When true, `resolveRunSoftTimeoutMs` lifts the hosted ceiling from
+   * 40s to ~13min (`BACKGROUND_SOFT_TIMEOUT_CEILING_MS`) because the run is
+   * executing inside a Netlify background function (no ~60s wall). Off by
+   * default — the foreground/interactive path never sets this, so its 40s
+   * clamp is unchanged. See the design doc + the durable-background dispatch
+   * decision in production-agent.ts.
+   */
+  backgroundFunction?: boolean;
 }
 
 export interface ResolveRunSoftTimeoutOptions {
   useHostedDefault?: boolean;
+  /**
+   * Resolve the soft timeout for a run executing inside a Netlify background
+   * function. Lifts the hosted clamp to `BACKGROUND_SOFT_TIMEOUT_CEILING_MS`
+   * (~13min) for this invocation only and, when no override/env is supplied,
+   * defaults to `DEFAULT_BACKGROUND_RUN_SOFT_TIMEOUT_MS`. Does NOT change the
+   * foreground ceiling. Off by default.
+   */
+  backgroundFunction?: boolean;
 }
 
 function isHostedRuntime(): boolean {
@@ -172,15 +223,21 @@ export function resolveRunSoftTimeoutMs(
   options?: ResolveRunSoftTimeoutOptions,
 ): number {
   const hosted = isHostedRuntime();
+  const background = options?.backgroundFunction === true;
+  // The interactive/foreground ceiling is 40s — the synchronous serverless
+  // function wall. A background-function run (opt-in only) has no ~60s wall, so
+  // it is allowed to outlast that and is clamped to the larger 13-min ceiling
+  // instead. The 40s clamp for non-background hosted runs is unchanged.
+  const ceiling = background
+    ? BACKGROUND_SOFT_TIMEOUT_CEILING_MS
+    : HOSTED_SOFT_TIMEOUT_CEILING_MS;
   // A configured/env soft timeout that exceeds the upstream walls can never
   // actually fire (the gateway/function kills the run first), so clamp it down
   // on hosted runtimes. This is what makes auto_continue reach the client
   // instead of the run dying as builder_gateway_timeout / stale_run. `0` means
   // "disabled" and is never clamped up.
   const clampHosted = (ms: number): number =>
-    hosted && ms > HOSTED_SOFT_TIMEOUT_CEILING_MS
-      ? HOSTED_SOFT_TIMEOUT_CEILING_MS
-      : ms;
+    hosted && ms > ceiling ? ceiling : ms;
 
   if (typeof overrideMs === "number" && Number.isFinite(overrideMs)) {
     return clampHosted(Math.max(0, overrideMs));
@@ -190,6 +247,11 @@ export function resolveRunSoftTimeoutMs(
     const raw = Number(envValue);
     if (Number.isFinite(raw) && raw >= 0) return clampHosted(raw);
   }
+  // A background-function run uses the full background budget by default; the
+  // foreground default (40s) is unchanged.
+  if (background) {
+    return hosted ? DEFAULT_BACKGROUND_RUN_SOFT_TIMEOUT_MS : 0;
+  }
   return options?.useHostedDefault && hosted
     ? DEFAULT_HOSTED_RUN_SOFT_TIMEOUT_MS
     : 0;
@@ -343,6 +405,7 @@ export function startRun(
   }, 1500);
   const softTimeoutMs = resolveRunSoftTimeoutMs(options?.softTimeoutMs, {
     useHostedDefault: options?.useHostedSoftTimeoutDefault === true,
+    backgroundFunction: options?.backgroundFunction === true,
   });
   const softTimeoutTimer =
     softTimeoutMs > 0

package/corpus/core/src/agent/run-store.ts

@@ -18,6 +18,21 @@ let _initPromise: Promise<void> | undefined;
  */
 export const RUN_STALE_MS = 15_000;
 
+/**
+ * Stale window for runs dispatched into a Netlify background function
+ * (`dispatch_mode = 'background'`). The design doc flags the 15s reaper vs a
+ * background cold-start as the #1 false-failure risk: the foreground POST
+ * inserts the `running` row, then `fireInternalDispatch` returns 202 and the
+ * background function may take >15s to cold-start and emit its first heartbeat.
+ * With the normal 15s window the reaper would falsely kill that freshly-
+ * inserted-but-not-yet-heartbeaten row. 90s tolerates a slow background
+ * cold-start while still reaping a genuinely dead background worker promptly.
+ *
+ * Only applied to rows explicitly marked background-dispatched; ordinary
+ * foreground runs keep the tight 15s window unchanged.
+ */
+export const BACKGROUND_RUN_STALE_MS = 90_000;
+
 export const STALE_RUN_ERROR_EVENT = {
   type: "error",
   error:
@@ -44,7 +59,8 @@ async function ensureRunTables(): Promise<void> {
           last_progress_at ${intType()},
           turn_id TEXT,
           error_code TEXT,
-          error_detail TEXT
+          error_detail TEXT,
+          dispatch_mode TEXT
         )
       `);
       // Backfill heartbeat_at on older deployments.
@@ -97,7 +113,16 @@ async function ensureRunTables(): Promise<void> {
       //   error_code / error_detail = terminal failure classification captured
       //                at completion so errored/cut-off runs are queryable for
       //                pattern analysis (see listErroredRuns).
-      for (const col of ["turn_id", "error_code", "error_detail"] as const) {
+      // dispatch_mode marks how a run was started: NULL/"foreground" for the
+      // normal synchronous path, "background" for a run dispatched into a
+      // Netlify background function. The reaper/claim widen the stale window
+      // for background rows so a slow cold-start isn't falsely reaped.
+      for (const col of [
+        "turn_id",
+        "error_code",
+        "error_detail",
+        "dispatch_mode",
+      ] as const) {
         try {
           if (isPostgres()) {
             await client.execute(
@@ -234,16 +259,68 @@ export async function insertRun(
   id: string,
   threadId: string,
   turnId?: string,
+  options?: { dispatchMode?: "foreground" | "background" },
 ): Promise<void> {
   await ensureRunTables();
   const client = getDbExec();
   const now = Date.now();
   await client.execute({
-    sql: `INSERT INTO agent_runs (id, thread_id, status, started_at, heartbeat_at, last_progress_at, turn_id) VALUES (?, ?, 'running', ?, ?, ?, ?)`,
-    args: [id, threadId, now, now, now, turnId ?? id],
+    sql: `INSERT INTO agent_runs (id, thread_id, status, started_at, heartbeat_at, last_progress_at, turn_id, dispatch_mode) VALUES (?, ?, 'running', ?, ?, ?, ?, ?)`,
+    args: [
+      id,
+      threadId,
+      now,
+      now,
+      now,
+      turnId ?? id,
+      options?.dispatchMode ?? null,
+    ],
   });
 }
 
+/**
+ * SQL fragment that resolves the per-row stale cutoff. Background-dispatched
+ * runs (`dispatch_mode` starting with `background`) tolerate a much longer gap
+ * without a heartbeat (slow Netlify background-function cold-start) before being
+ * reaped; every other run keeps the tight 15s window. The bound `now` is
+ * subtracted by the resolved window so the comparison is
+ * `COALESCE(heartbeat_at, started_at) < (now - window)`.
+ *
+ * `dispatch_mode` is one of NULL/"foreground" (normal sync path), "background"
+ * (foreground inserted the row for a background dispatch), or
+ * "background-processing" (the background worker claimed it). Both background
+ * states get the wider window via a LIKE-prefix match.
+ */
+function backgroundAwareStaleCutoffSql(): string {
+  return `(? - CASE WHEN dispatch_mode LIKE 'background%' THEN ${BACKGROUND_RUN_STALE_MS} ELSE ${RUN_STALE_MS} END)`;
+}
+
+/**
+ * Atomically claim a background-dispatched run for processing. The foreground
+ * POST inserts the run row with `dispatch_mode = 'background'`; the FIRST
+ * delivery of the background dispatch flips it to `background-processing` and
+ * wins the claim. A duplicate Netlify delivery (background functions can be
+ * retried) sees `background-processing` and loses, so it no-ops — mirroring
+ * `claimAgentTeamRun` returning null. Returns true when this caller won.
+ *
+ * Idempotent and conditional: the WHERE clause only matches the unclaimed
+ * `background` state AND a still-running row, so a reaped/terminal row can't be
+ * re-claimed.
+ */
+export async function claimBackgroundRun(runId: string): Promise<boolean> {
+  await ensureRunTables();
+  const client = getDbExec();
+  const { rowsAffected } = await client.execute({
+    sql: `UPDATE agent_runs
+          SET dispatch_mode = 'background-processing'
+          WHERE id = ?
+            AND status = 'running'
+            AND dispatch_mode = 'background'`,
+    args: [runId],
+  });
+  return (rowsAffected ?? 0) > 0;
+}
+
 /**
  * Atomically acquire a run lease for a thread. Succeeds (returns true) only
  * when no other run for the same thread is currently status='running' with a
@@ -256,18 +333,37 @@ export async function insertRun(
  */
 export async function tryClaimRunSlot(
   threadId: string,
-  maxStaleMs: number = RUN_STALE_MS,
+  maxStaleMs?: number,
 ): Promise<{ claimed: boolean; activeRunId: string | null }> {
   await ensureRunTables();
   const client = getDbExec();
-  const heartbeatCutoff = Date.now() - maxStaleMs;
+  const now = Date.now();
+  // Default: per-row background-aware window so a live background run (which can
+  // legitimately go >15s between heartbeats during a cold-start) isn't seen as
+  // "free" and double-claimed by a racing foreground POST. An explicit
+  // `maxStaleMs` override keeps a flat window for callers that want one.
+  if (typeof maxStaleMs === "number") {
+    const heartbeatCutoff = now - maxStaleMs;
+    const { rows } = await client.execute({
+      sql: `SELECT id FROM agent_runs
+            WHERE thread_id = ?
+              AND status = 'running'
+              AND COALESCE(heartbeat_at, started_at) >= ?
+            ORDER BY started_at DESC LIMIT 1`,
+      args: [threadId, heartbeatCutoff],
+    });
+    if (rows.length > 0) {
+      return { claimed: false, activeRunId: (rows[0] as { id: string }).id };
+    }
+    return { claimed: true, activeRunId: null };
+  }
   const { rows } = await client.execute({
     sql: `SELECT id FROM agent_runs
           WHERE thread_id = ?
             AND status = 'running'
-            AND COALESCE(heartbeat_at, started_at) >= ?
+            AND COALESCE(heartbeat_at, started_at) >= ${backgroundAwareStaleCutoffSql()}
           ORDER BY started_at DESC LIMIT 1`,
-    args: [threadId, heartbeatCutoff],
+    args: [threadId, now],
   });
   if (rows.length > 0) {
     const row = rows[0] as { id: string };
@@ -335,12 +431,20 @@ export async function bumpRunProgress(runId: string): Promise<void> {
  */
 export async function reapIfStale(
   runId: string,
-  maxStaleMs: number = RUN_STALE_MS,
+  maxStaleMs?: number,
 ): Promise<boolean> {
   await ensureRunTables();
   const client = getDbExec();
   const completedAt = Date.now();
-  const cutoff = completedAt - maxStaleMs;
+  // Background-dispatched runs get the wider stale window so a slow cold-start
+  // isn't reaped; foreground runs keep the tight 15s window. An explicit
+  // override forces a flat window for callers that want one.
+  const staleClause =
+    typeof maxStaleMs === "number"
+      ? `COALESCE(heartbeat_at, started_at) < ?`
+      : `COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`;
+  const staleArgs =
+    typeof maxStaleMs === "number" ? [completedAt - maxStaleMs] : [completedAt];
   const { rowsAffected } = await client.execute({
     sql: `UPDATE agent_runs
           SET status = 'errored',
@@ -349,13 +453,13 @@ export async function reapIfStale(
               error_detail = ?
           WHERE id = ?
             AND status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ?`,
+            AND ${staleClause}`,
     args: [
       completedAt,
       STALE_RUN_ERROR_EVENT.errorCode,
       STALE_RUN_ERROR_EVENT.details,
       runId,
-      cutoff,
+      ...staleArgs,
     ],
   });
   const reaped = (rowsAffected ?? 0) > 0;
@@ -675,12 +779,13 @@ export async function getCurrentTurnEventsForThread(
 export async function reapAllStaleRuns(): Promise<number> {
   await ensureRunTables();
   const client = getDbExec();
-  const heartbeatCutoff = Date.now() - RUN_STALE_MS;
+  const now = Date.now();
+  // Background-dispatched runs use the wider window; everything else 15s.
   const stale = await client.execute({
     sql: `SELECT id FROM agent_runs
           WHERE status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ?`,
-    args: [heartbeatCutoff],
+            AND COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`,
+    args: [now],
   });
   const completedAt = Date.now();
   const { rowsAffected } = await client.execute({
@@ -690,12 +795,12 @@ export async function reapAllStaleRuns(): Promise<number> {
               error_code = ?,
               error_detail = ?
           WHERE status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ?`,
+            AND COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`,
     args: [
       completedAt,
       STALE_RUN_ERROR_EVENT.errorCode,
       STALE_RUN_ERROR_EVENT.details,
-      heartbeatCutoff,
+      completedAt,
     ],
   });
   for (const row of stale.rows) {
@@ -730,15 +835,15 @@ export async function cleanupOldRuns(
   // SELECT covers BOTH UPDATE conditions so the terminal-event-append loop
   // below catches every row we're about to flip — a 24h-old row with a
   // somehow-fresh heartbeat would slip past a heartbeat-only SELECT.
-  const heartbeatCutoff = Date.now() - RUN_STALE_MS;
+  const now = Date.now();
   const stale = await client.execute({
     sql: `SELECT id FROM agent_runs
           WHERE status = 'running'
             AND (
-              COALESCE(heartbeat_at, started_at) < ?
+              COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}
               OR started_at < ?
     )`,
-    args: [heartbeatCutoff, cutoff],
+    args: [now, cutoff],
   });
   const completedAt = Date.now();
   await client.execute({
@@ -755,7 +860,8 @@ export async function cleanupOldRuns(
       cutoff,
     ],
   });
-  // Also expire runs whose heartbeat is stale — producer has died.
+  // Also expire runs whose heartbeat is stale — producer has died. Uses the
+  // background-aware window so a slow background cold-start isn't reaped early.
   await client.execute({
     sql: `UPDATE agent_runs
           SET status = 'errored',
@@ -763,12 +869,12 @@ export async function cleanupOldRuns(
               error_code = ?,
               error_detail = ?
           WHERE status = 'running'
-            AND COALESCE(heartbeat_at, started_at) < ?`,
+            AND COALESCE(heartbeat_at, started_at) < ${backgroundAwareStaleCutoffSql()}`,
     args: [
       completedAt,
       STALE_RUN_ERROR_EVENT.errorCode,
       STALE_RUN_ERROR_EVENT.details,
-      heartbeatCutoff,
+      completedAt,
     ],
   });
   for (const row of stale.rows) {

package/corpus/core/src/agent/types.ts

@@ -129,6 +129,26 @@ export interface AgentChatRequest {
   attachments?: AgentChatAttachment[];
   /** Internal retry/continuation requests should not create visible user turns. */
   internalContinuation?: boolean;
+  /**
+   * Internal marker set ONLY by the durable-background self-dispatch (see
+   * `AGENT_CHAT_BACKGROUND_RUN_FIELD`). Present when the agent-chat handler is
+   * re-entered as the background worker: it carries the pre-claimed `runId` and
+   * logical `turnId` so the worker runs the loop inline with the background
+   * soft-timeout instead of re-claiming the slot or re-dispatching. Untrusted
+   * on its own — the `_process-run` route HMAC-verifies the dispatch before
+   * invoking the handler. Absent on every normal client request.
+   */
+  __backgroundRun?: {
+    runId: string;
+    turnId?: string;
+    /**
+     * Number of server-driven background→background continuations already
+     * chained into this logical turn (0 on the first chunk). The worker
+     * increments this when it re-fires `_process-run` at a soft-timeout
+     * boundary and refuses to chain past `MAX_BACKGROUND_RUN_CONTINUATIONS`.
+     */
+    continuationCount?: number;
+  };
   /**
    * Stable identity for the logical assistant turn this request belongs to.
    * The client sends the SAME turnId for the initial POST and every

package/corpus/core/src/client/AgentPanel.tsx

@@ -1072,6 +1072,18 @@ function AgentPanelInner({
             </button>
           </DropdownMenuTrigger>
           <DropdownMenuContent align="end" sideOffset={6} className="w-48">
+            {onCollapse && (
+              <>
+                <DropdownMenuItem onSelect={onCollapse}>
+                  <IconLayoutSidebarRightCollapse
+                    size={14}
+                    className="shrink-0"
+                  />
+                  Collapse sidebar
+                </DropdownMenuItem>
+                <DropdownMenuSeparator />
+              </>
+            )}
             {mode === "chat" && toggleHistory && (
               <DropdownMenuItem onSelect={toggleHistory}>
                 <IconHistory size={14} className="shrink-0" />
@@ -1133,15 +1145,6 @@ function AgentPanelInner({
                 {isFullscreen ? "Exit fullscreen" : "Fullscreen"}
               </DropdownMenuItem>
             )}
-            {onCollapse && (
-              <DropdownMenuItem onSelect={onCollapse}>
-                <IconLayoutSidebarRightCollapse
-                  size={14}
-                  className="shrink-0"
-                />
-                Collapse sidebar
-              </DropdownMenuItem>
-            )}
             {((mode === "chat" && activeTabId) ||
               (mode === "cli" && canUseCodeTools && activeCliTab)) && (
               <>

package/corpus/core/src/client/blocks/library/FileTreeBlock.tsx

@@ -119,6 +119,10 @@ interface FolderNode {
   /** Full slash path of the folder, used as a stable key. */
   path: string;
   children: TreeNode[];
+  /** Present when the folder was authored as an explicit directory entry (a
+   * `path` ending in `/`), carrying its note/metadata + flat `entries` index. */
+  entry?: FileTreeEntry;
+  index?: number;
 }
 
 type TreeNode = FolderNode | FileLeaf;
@@ -136,6 +140,10 @@ interface FolderBuild {
   files: FileLeaf[];
   /** Insertion order of child names (folders + files) for stable rendering. */
   order: string[];
+  /** Set when an explicit directory entry (trailing slash) targets this folder,
+   * carrying its note/metadata + flat `entries` index. */
+  entry?: FileTreeEntry;
+  index?: number;
 }
 
 function makeFolder(name: string, path: string): FolderBuild {
@@ -154,8 +162,15 @@ function buildTree(entries: FileTreeEntry[]): TreeNode[] {
   entries.forEach((entry, index) => {
     const segments = entry.path.split("/").filter(Boolean);
     if (segments.length === 0) return;
-    const fileName = segments[segments.length - 1] as string;
-    const folderSegments = segments.slice(0, -1);
+
+    // A trailing slash marks a DIRECTORY entry: every segment is a folder and
+    // the entry's note/metadata attaches to the deepest folder (the last segment
+    // does NOT become a file leaf). Because folders are keyed by name, this also
+    // merges with any folder the sibling file paths already implied — so
+    // `packages/shared/` and `packages/shared/src/…` collapse onto one `shared`
+    // folder instead of a duplicate folder + file pair.
+    const isDir = /\/\s*$/.test(entry.path);
+    const folderSegments = isDir ? segments : segments.slice(0, -1);
 
     let cursor = root;
     let prefix = "";
@@ -170,6 +185,17 @@ function buildTree(entries: FileTreeEntry[]): TreeNode[] {
       cursor = next;
     }
 
+    if (isDir) {
+      // Attach metadata to the deepest folder (first declaration wins, so an
+      // explicit note isn't clobbered by a later bare prefix re-declaration).
+      if (!cursor.entry) {
+        cursor.entry = entry;
+        cursor.index = index;
+      }
+      return;
+    }
+
+    const fileName = segments[segments.length - 1] as string;
     cursor.files.push({
       kind: "file",
       name: fileName,
@@ -191,6 +217,8 @@ function buildTree(entries: FileTreeEntry[]): TreeNode[] {
           name: child.name,
           path: child.path,
           children: materialize(child),
+          entry: child.entry,
+          index: child.index,
         });
       } else {
         const file = folder.files[Number(key.slice(2))];
@@ -212,7 +240,16 @@ function compactFolderNode(folder: FolderNode): FolderNode {
   let path = folder.path;
   let children = folder.children;
 
-  while (children.length === 1 && children[0]?.kind === "folder") {
+  // Collapse single-child folder chains (a/b/c) into one row — but never across
+  // a folder that carries its own directory note, so an explicitly authored
+  // directory (e.g. `packages/shared/` with a note) keeps its own row instead of
+  // being folded into its parent or child and losing the note.
+  while (
+    !folder.entry &&
+    children.length === 1 &&
+    children[0]?.kind === "folder" &&
+    !children[0].entry
+  ) {
     const child = children[0];
     names.push(child.name);
     path = child.path;
@@ -223,6 +260,8 @@ function compactFolderNode(folder: FolderNode): FolderNode {
     kind: "folder",
     name: names.join("/"),
     path,
+    entry: folder.entry,
+    index: folder.index,
     children: compactTree(children),
   };
 }
@@ -353,30 +392,49 @@ export function FileTreeRead({
     const indent = depth * INDENT_STEP;
     if (node.kind === "folder") {
       const collapsed = collapsedFolders[node.path] ?? false;
+      // An explicit directory entry (trailing-slash path) can be a leaf folder
+      // with no children — e.g. `apps/mail/`. It still renders as a folder, just
+      // without a toggle chevron. Its authored note shows inline like a file's.
+      const expandable = node.children.length > 0;
+      const note = node.entry?.note?.trim();
+      const open = expandable && !collapsed;
       return (
         <div key={`d:${node.path}`}>
           <button
             type="button"
             data-plan-interactive
-            aria-expanded={!collapsed}
-            onClick={() => toggleFolder(node.path)}
+            disabled={!expandable}
+            aria-expanded={expandable ? !collapsed : undefined}
+            onClick={expandable ? () => toggleFolder(node.path) : undefined}
             style={{ paddingLeft: indent + 8 }}
-            className="flex w-full items-center gap-1.5 rounded-md py-1 pr-2 text-left text-[13px] transition-colors hover:bg-accent/40"
+            className={cn(
+              "flex w-full items-center gap-1.5 rounded-md py-1 pr-2 text-left text-[13px] transition-colors",
+              expandable ? "hover:bg-accent/40" : "cursor-default",
+            )}
           >
-            <IconChevronRight
-              className={cn(
-                "size-3.5 shrink-0 text-plan-muted transition-transform",
-                !collapsed && "rotate-90",
-              )}
-            />
-            {collapsed ? (
-              <IconFolder className="size-4 shrink-0 text-plan-muted" />
+            {expandable ? (
+              <IconChevronRight
+                className={cn(
+                  "size-3.5 shrink-0 text-plan-muted transition-transform",
+                  !collapsed && "rotate-90",
+                )}
+              />
             ) : (
+              <span className="size-3.5 shrink-0" aria-hidden />
+            )}
+            {open ? (
               <IconFolderOpen className="size-4 shrink-0 text-plan-muted" />
+            ) : (
+              <IconFolder className="size-4 shrink-0 text-plan-muted" />
             )}
             <span className="min-w-0 truncate font-medium text-plan-text">
               {node.name}
             </span>
+            {note && (
+              <span className="ml-1 min-w-0 flex-1 truncate text-xs text-plan-muted">
+                {note}
+              </span>
+            )}
           </button>
         </div>
       );