fix(scan,ui): restore files-rail stale-clock icon via sidecar status

The corpus/render split rebuilt the files rail from the lightweight
GET /api/folders payload instead of the sidecar-carrying branch nodes.
It threaded errorCount / warnCount for the error/warn badges but dropped
the sidecar drift status, so the rail's per-row stale-clock icon went
dark in both demo and sm serve mode.

Thread a sidecarStatus field end to end: the kernel lite-node loader
selects scan_nodes.sidecar_status, the BFF emits it on /api/folders, and
the UI projects it onto node.sidecar so the rail flags staleness
corpus-wide without hydrating the branch payload. The demo static data
source mirrors the same lite shape. spec/cli-contract.md documents the
additive field and spec/index.json is regenerated.

The e2e sidecar smoke test was stale: folders now render collapsed by
default, so it expands the tree (files-expand-all) before asserting the
stale icon on the nested leaf row.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NF5XoRisDA9Z3fNK2KMoy9

Author: crystian

.changeset/files-rail-stale-clock-sidecar-status.md

@@ -0,0 +1,10 @@
+---
+"@skill-map/cli": patch
+"@skill-map/spec": patch
+---
+
+Restores the files rail's per-row stale-clock icon, dropped when the rail switched to building from the lightweight `GET /api/folders` payload (which carried the error / warn counts but not the sidecar drift status). The endpoint now emits a `sidecarStatus` field (the persisted `scan_nodes.sidecar_status`, `null` when there is no parseable sidecar), threaded from the kernel loader through the BFF into the rail so staleness flags corpus-wide in demo and `sm serve` mode.
+
+## User-facing
+
+The files rail again flags out-of-date nodes with the clock icon, so you can see at a glance which files have drifted since their last review.

e2e/smoke/sidecar.spec.ts

@@ -70,6 +70,11 @@ test.describe('sidecar UI surface (Step 9.6.5)', () => {
     // `stale-both` sidecar, so its row must render the stale clock icon.
     await gotoWorkspace(page);
 
+    // Folders now render COLLAPSED by default, so a nested leaf row is not
+    // mounted until its ancestor folders are open. Expand the whole tree
+    // (the rail's expand-all control) to surface `content-editor.md`.
+    await page.getByTestId('files-expand-all').click();
+
     const row = page.getByTestId(`files-leaf-${STALE_PATH}`);
     await expect(row).toBeVisible();
     await expect(row.locator('.files__stale-icon')).toBeVisible();

spec/cli-contract.md

@@ -602,7 +602,7 @@ The reference implementation ships a Hono BFF rooted at `src/server/`. One Node
 | `GET /api/nodes/:pathB64[?include=body]` | implemented | Single-node detail envelope: `{ schemaVersion, kind: 'node', item: Node, links: { incoming: Link[], outgoing: Link[] }, issues: Issue[] }`. `:pathB64` is base64url (RFC 4648 §5, no padding) of `node.path`. Missing node or malformed `pathB64` → 404 `not-found`. **`?include=body`** (Step 14.5.a), opt-in flag adding `item.body: string \| null` to the response. The body is read from disk on demand at request time (the kernel persists `bodyHash` only). `null` means the source file was missing / unreadable when the request landed (the watcher re-emits `scan.completed` on catch-up). Without the flag, `item.body` is `undefined` and the handler does not touch the filesystem. |
 | `GET /api/links?kind=&from=&to=` | implemented | `RestEnvelope` (`kind: 'links'`), list of links. Filters: `kind` (CSV whitelist of `link.kind`), `from` (exact match on `link.source`), `to` (exact match on `link.target`). No pagination at v14.2. |
 | `GET /api/issues?severity=&analyzerId=&node=` | implemented | `RestEnvelope` (`kind: 'issues'`), list of issues. Filters: `severity` (CSV from `error\|warn\|info`), `analyzerId` (CSV; qualified or short suffix per `sm check --analyzers`), `node` (filter to issues whose `nodeIds` includes the path). No pagination at v14.2. |
-| `GET /api/folders` | implemented | `RestEnvelope` (`kind: 'folders'`), lightweight full-corpus projection: one entry per scanned node `{ path, kind, linksInCount, linksOutCount, tokensTotal, modifiedAtMs, errorCount, warnCount }`. Only cheap scalar columns of `scan_nodes` (no frontmatter, body, links, signals, or contributions), so the SPA folders tree renders the whole corpus (up to `scan.maxScan`) with per-node data columns + per-folder issue badges without hydrating the full `ScanResult`. `tokensTotal` / `modifiedAtMs` are nullable (tokenization disabled / unknown mtime). `errorCount` / `warnCount` are the count of error / warn issues whose `nodeIds` include that path (the same incidence the tree rolls up across descendants). No pagination (the complete tree is the point; the corpus is already bounded by `scan.maxScan`). DB absent → zero items. |
+| `GET /api/folders` | implemented | `RestEnvelope` (`kind: 'folders'`), lightweight full-corpus projection: one entry per scanned node `{ path, kind, linksInCount, linksOutCount, tokensTotal, modifiedAtMs, errorCount, warnCount, sidecarStatus }`. Only cheap scalar columns of `scan_nodes` (no frontmatter, body, links, signals, or contributions), so the SPA folders tree renders the whole corpus (up to `scan.maxScan`) with per-node data columns + per-folder issue badges without hydrating the full `ScanResult`. `tokensTotal` / `modifiedAtMs` are nullable (tokenization disabled / unknown mtime). `errorCount` / `warnCount` are the count of error / warn issues whose `nodeIds` include that path (the same incidence the tree rolls up across descendants). `sidecarStatus` is the node's sidecar drift status (`scan_nodes.sidecar_status`), `null` when there is no parseable sidecar, so the folders tree can flag per-row staleness without hydrating the branch payload. No pagination (the complete tree is the point; the corpus is already bounded by `scan.maxScan`). DB absent → zero items. |
 | `GET /api/branch?path=<prefix>&path=<prefix>&limit=<n>` | implemented | Branch projection for the map. `path` is **repeatable**: the response is the UNION of the subtrees under every given prefix (forward-slash; a node matches a prefix when its path equals it or starts with `<prefix>/`). No `path` (or a single empty one) = the whole corpus. The union is capped at `limit` nodes (default and effective max = the scan's `maxRenderNodes`), so the response stays bounded regardless of how many prefixes are sent. Direct shape (no envelope wrap, like `/api/scan`): `{ schemaVersion, kind: 'branch', branch: { paths, total, rendered, truncated, cap }, nodes: Node[], links: Link[], issues: Issue[] }`, where `paths` echoes the requested prefixes. `nodes` is the first `rendered` nodes of the union in stable path order; `links` carries only edges whose source AND target are in `nodes`; `issues` carries those touching `nodes`. `truncated` is `total > cap`. Lets the SPA render a multi-folder selection without hydrating the full `ScanResult`. DB absent → empty branch (zero nodes). Validation: `limit` integer ≥ 1 else 400 `bad-query`. |
 | `GET /api/graph?format=ascii\|json\|md` | implemented | formatter-rendered graph. `Content-Type` per format: `text/plain` (ascii), `application/json` (json), `text/markdown` (md / mermaid). Default `format=ascii`. Unknown format → 400 `bad-query`. |
 | `GET /api/config` | implemented | `RestEnvelope` (`kind: 'config'`), merged effective config (defaults → user → user-local → project → project-local → override). |

spec/index.json

@@ -181,7 +181,7 @@
       "CHANGELOG.md": "3c44981379253010e1181af77ae3d5910a5037a013d2a49fba870e8a31338a70",
       "README.md": "a790cd010b46d47883d1f37e3893cea9d7aa69ec4750c0202e6a0c99991e7980",
       "architecture.md": "5eb1b54e66b3db3d28091830a9a990e94dc72b4488f94ab9506cd509aa884e8b",
-      "cli-contract.md": "21679f985b15371c05b0b0619ee4b56b2ceb600533c4c81e9e387d5bfbde426e",
+      "cli-contract.md": "3733b1277c92d2af9e0728b0bcdd0579dd13bf0c3adfd7f272a18efd3a8c8257",
       "conformance/README.md": "dcbef7249f161acf597552a05dcadc813cd0ced430dcd3f813fcf5e1c876335d",
       "conformance/cases/backtick-path-extraction.json": "4620e7f8bc161fc57cb44001e9d99879c7e22b4865a0c27a20dc28969cd936d9",
       "conformance/cases/extractor-collision-detection.json": "179a02c61892f0d26492de0c4e2c327fa6b4986d1265a8f119e871df6afe4658",

src/kernel/adapters/sqlite/__tests__/branch-folders-storage.spec.ts

@@ -2,7 +2,7 @@
  * Acceptance tests for the lazy-load storage primitives the BFF
  * `/api/folders` + `/api/branch` endpoints consume:
  *
- *   - `port.scans.listLiteNodes()`, `{ path, kind, linksInCount, linksOutCount, tokensTotal, modifiedAtMs }[]` ordered by path.
+ *   - `port.scans.listLiteNodes()`, `{ path, kind, linksInCount, linksOutCount, tokensTotal, modifiedAtMs, sidecarStatus }[]` ordered by path.
  *   - `port.scans.issueCountsByPath()`, per-node error / warn incidence
  *     via `json_each` + GROUP BY (info ignored).
  *   - `port.scans.effectiveMaxRenderNodes()`, the scan's recorded cap
@@ -125,7 +125,7 @@ describe('port.scans.listLiteNodes', () => {
     }
   });
 
-  it('returns { path, kind } ordered by path ASC', async () => {
+  it('returns { path, kind, sidecarStatus } ordered by path ASC', async () => {
     const adapter = new SqliteStorageAdapter({ databasePath: freshDbPath('lite'), autoBackup: false });
     await adapter.init();
     try {
@@ -140,6 +140,7 @@ describe('port.scans.listLiteNodes', () => {
           linksOutCount: 0,
           tokensTotal: null,
           modifiedAtMs: null,
+          sidecarStatus: null,
         },
         {
           path: 'skills/zeta.md',
@@ -148,12 +149,45 @@ describe('port.scans.listLiteNodes', () => {
           linksOutCount: 0,
           tokensTotal: null,
           modifiedAtMs: null,
+          sidecarStatus: null,
         },
       ]);
     } finally {
       await adapter.close();
     }
   });
+
+  it('carries the persisted sidecar_status when a sidecar is present', async () => {
+    const adapter = new SqliteStorageAdapter({ databasePath: freshDbPath('lite-sidecar'), autoBackup: false });
+    await adapter.init();
+    try {
+      await adapter.db
+        .insertInto('scan_nodes')
+        .values({
+          path: 'docs/drift.md',
+          kind: 'note',
+          provider: 'claude',
+          frontmatterJson: '{}',
+          bodyHash: HASH,
+          frontmatterHash: HASH,
+          bytesFrontmatter: 0,
+          bytesBody: 0,
+          bytesTotal: 0,
+          tokensFrontmatter: null,
+          tokensBody: null,
+          tokensTotal: null,
+          scannedAt: Date.now(),
+          sidecarPresent: 1,
+          sidecarStatus: 'stale-body',
+        })
+        .execute();
+      const rows = await adapter.scans.listLiteNodes();
+      assert.equal(rows.length, 1);
+      assert.equal(rows[0]?.sidecarStatus, 'stale-body');
+    } finally {
+      await adapter.close();
+    }
+  });
 });
 
 describe('port.scans.issueCountsByPath', () => {

src/kernel/adapters/sqlite/scan-load.ts

@@ -286,6 +286,7 @@ export async function loadLiteNodes(
       'linksOutCount',
       'tokensTotal',
       'modifiedAtMs',
+      'sidecarStatus',
     ])
     .orderBy('path', 'asc')
     .execute();
@@ -296,6 +297,7 @@ export async function loadLiteNodes(
     linksOutCount: r.linksOutCount,
     tokensTotal: r.tokensTotal,
     modifiedAtMs: r.modifiedAtMs,
+    sidecarStatus: r.sidecarStatus,
   }));
 }
 

src/kernel/types/storage.ts

@@ -81,6 +81,12 @@ export interface ILiteNode {
   linksOutCount: number;
   tokensTotal: number | null;
   modifiedAtMs: number | null;
+  /**
+   * The persisted `scan_nodes.sidecar_status`, null when there is no
+   * parseable sidecar. Lets the folders rail flag staleness corpus-wide,
+   * sibling of the issue counts.
+   */
+  sidecarStatus: string | null;
 }
 
 /**

src/server/routes/__tests__/folders-endpoint.spec.ts

@@ -3,12 +3,14 @@
  *
  * Boots a real `createServer()` against a primed-DB tempdir, fires
  * `fetch()`, and asserts on the `RestEnvelope` (`kind: 'folders'`) shape:
- * one item per scanned node `{ path, kind, errorCount, warnCount }`, the
- * error / warn incidence rolled up per node from `scan_issues`.
+ * one item per scanned node `{ path, kind, errorCount, warnCount,
+ * sidecarStatus }`, the error / warn incidence rolled up per node from
+ * `scan_issues` and the sidecar drift status carried straight from the
+ * lite node.
  *
  * Coverage:
  *   - empty / absent DB → zero items.
- *   - one item per node with `{ path, kind }`.
+ *   - one item per node with `{ path, kind, sidecarStatus }`.
  *   - errorCount / warnCount roll up issue incidence; info ignored.
  *   - no pagination (counts.total == items.length, no counts.page).
  *
@@ -24,7 +26,7 @@ import { after, before, beforeEach, describe, it } from 'node:test';
 
 import { SqliteStorageAdapter } from '../../../kernel/adapters/sqlite/index.js';
 import { persistScanResult } from '../../../kernel/adapters/sqlite/scan-persistence.js';
-import type { Issue, Node, ScanResult } from '../../../kernel/types.js';
+import type { Issue, Node, ScanResult, SidecarStatus } from '../../../kernel/types.js';
 import {
   createServer,
   type IServerOptions,
@@ -54,7 +56,7 @@ beforeEach(() => {
   rmSync(root.dbPath, { force: true });
 });
 
-function makeNode(path: string, kind = 'note'): Node {
+function makeNode(path: string, kind = 'note', sidecarStatus?: SidecarStatus): Node {
   return {
     path,
     kind,
@@ -65,6 +67,7 @@ function makeNode(path: string, kind = 'note'): Node {
     linksOutCount: 0,
     linksInCount: 0,
     externalRefsCount: 0,
+    ...(sidecarStatus ? { sidecar: { present: true, status: sidecarStatus } } : {}),
   };
 }
 
@@ -132,7 +135,13 @@ function url(handle: IServerHandle, path: string): string {
 interface IFoldersBody {
   schemaVersion: string;
   kind: string;
-  items: Array<{ path: string; kind: string; errorCount: number; warnCount: number }>;
+  items: Array<{
+    path: string;
+    kind: string;
+    errorCount: number;
+    warnCount: number;
+    sidecarStatus: string | null;
+  }>;
   counts: { total: number; returned: number; page?: unknown };
 }
 
@@ -150,7 +159,12 @@ describe('GET /api/folders', () => {
   });
 
   it('one item per node with { path, kind }, ordered by path', async () => {
-    await prime([makeNode('skills/zeta.md', 'skill'), makeNode('agents/alpha.md', 'agent')], []);
+    await prime(
+      // alpha carries a non-fresh sidecar, zeta has none, so the lite
+      // payload exercises both the non-null and null sidecarStatus paths.
+      [makeNode('skills/zeta.md', 'skill'), makeNode('agents/alpha.md', 'agent', 'stale-body')],
+      [],
+    );
     await bootAndUse(async (handle) => {
       const res = await fetch(url(handle, '/api/folders'));
       assert.equal(res.status, 200);
@@ -163,6 +177,11 @@ describe('GET /api/folders', () => {
           { path: 'skills/zeta.md', kind: 'skill' },
         ],
       );
+      // sidecarStatus rides the lite payload: the node with a parseable
+      // sidecar carries its drift status, the plain node carries null.
+      const byPath = new Map(body.items.map((i) => [i.path, i]));
+      assert.equal(byPath.get('agents/alpha.md')!.sidecarStatus, 'stale-body');
+      assert.equal(byPath.get('skills/zeta.md')!.sidecarStatus, null);
       // Only the cheap scalar columns: no frontmatter / body / signals /
       // contributions leaked onto the item.
       assert.deepEqual(Object.keys(body.items[0]!).sort(), [
@@ -172,6 +191,7 @@ describe('GET /api/folders', () => {
         'linksOutCount',
         'modifiedAtMs',
         'path',
+        'sidecarStatus',
         'tokensTotal',
         'warnCount',
       ]);

src/server/routes/folders.ts

@@ -2,9 +2,9 @@
  * `GET /api/folders`, lightweight full-corpus projection.
  *
  * One item per scanned node `{ path, kind, linksInCount, linksOutCount,
- * tokensTotal, modifiedAtMs, errorCount, warnCount }`, only cheap scalar
- * columns of `scan_nodes` (no frontmatter / body / links / signals /
- * contributions) and no pagination. Feeds the SPA
+ * tokensTotal, modifiedAtMs, errorCount, warnCount, sidecarStatus }`,
+ * only cheap scalar columns of `scan_nodes` (no frontmatter / body /
+ * links / signals / contributions) and no pagination. Feeds the SPA
  * folders tree so it renders the WHOLE corpus (up to `scan.maxScan`)
  * with per-folder issue badges without hydrating the full `ScanResult`
  * (the graph map lazy-loads its branch via `/api/branch`).
@@ -16,6 +16,11 @@
  * never by loading every issue into memory. The `info` severity is
  * intentionally ignored (the tree badges only error / warn).
  *
+ * `sidecarStatus` is the node's sidecar drift status
+ * (`scan_nodes.sidecar_status`), `null` when there is no parseable
+ * sidecar, so the folders rail can flag per-row staleness without
+ * hydrating the branch payload.
+ *
  * Response is the canonical list envelope (`kind: 'folders'`), mirroring
  * `/api/nodes` / `/api/links`. No pagination: the complete tree is the
  * point and the corpus is already bounded by `scan.maxScan`, so
@@ -40,6 +45,7 @@ interface IFolderItem {
   modifiedAtMs: number | null;
   errorCount: number;
   warnCount: number;
+  sidecarStatus: string | null;
 }
 
 export function registerFoldersRoute(app: Hono, deps: IRouteDeps): void {
@@ -67,6 +73,7 @@ export function registerFoldersRoute(app: Hono, deps: IRouteDeps): void {
         modifiedAtMs: n.modifiedAtMs,
         errorCount: counts?.error ?? 0,
         warnCount: counts?.warn ?? 0,
+        sidecarStatus: n.sidecarStatus,
       };
     });
 

ui/src/app/views/files-view/__tests__/files-view.interactions.spec.ts

@@ -82,6 +82,7 @@ function makeLoaderStub(
     modifiedAtMs: null,
     errorCount: counts[n.path]?.errorCount ?? 0,
     warnCount: counts[n.path]?.warnCount ?? 0,
+    sidecarStatus: null,
   }));
   return {
     nodes: signal(nodes),