@adhdev/daemon-core 1.0.18-rc.5 → 1.0.18-rc.7

package/dist/mesh/coordinator-prompt.d.ts

@@ -68,6 +68,20 @@ export interface CoordinatorOperatingNote {
     category?: 'provider_quirk' | 'pattern_to_avoid' | 'recovery_lesson';
     createdAt?: string;
     sourceCoordinator?: string;
+    /**
+     * Operating-notes lifecycle (minimal first cut). When true the note ALWAYS
+     * rides into the coordinator prompt — it is never dropped by TTL expiry and
+     * survives the injection cap ahead of unpinned notes. Legacy notes without
+     * this field default to false.
+     */
+    pinned?: boolean;
+    /**
+     * Optional explicit expiry ISO timestamp. When set and in the past, an
+     * UNPINNED note is dropped from the injected prompt (read-side only — the
+     * ledger entry is never pruned by age). When absent, the category→TTL map
+     * (see isNoteExpired) governs expiry; pinned notes never expire regardless.
+     */
+    expiresAt?: string;
 }
 export interface CoordinatorPromptContext {
     mesh: LocalMeshEntry;
@@ -102,6 +116,24 @@ export interface CoordinatorPromptContext {
     magiKindPanels?: MagiKindPanelMap;
 }
 export declare function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string;
+/**
+ * Operating-notes lifecycle selection (read-side, minimal first cut). Given the
+ * effective notes (oldest-first, ledger order) and the current time, produce the
+ * ordered, capped list that rides into the prompt:
+ *   (i)   ALWAYS include pinned notes.
+ *   (ii)  drop expired UNPINNED notes (per category TTL / explicit expiresAt).
+ *   (iii) rank pinned-first, then durable-category, then recency (newest first).
+ *   (iv)  apply the existing OPERATING_NOTES_PROMPT_CAP to the ranked list.
+ * Pure + deterministic given `now`. Returns { shown, omittedCount }.
+ *
+ * Ranking is stable on the original ledger index so, within a tier, the original
+ * oldest-first order is preserved before the recency comparison flips it — i.e.
+ * newest notes lead each tier. The cap keeps the leading (highest-priority) N.
+ */
+export declare function selectOperatingNotesForPrompt(notes: CoordinatorOperatingNote[], now: number, cap?: number): {
+    shown: CoordinatorOperatingNote[];
+    omittedCount: number;
+};
 /**
  * Render the machine-local MAGI kind-panel bindings so the coordinator KNOWS
  * which cross-verification panels (rca / design / claim_audit / freeform) are

package/dist/mesh/mesh-disk-retention.d.ts

@@ -0,0 +1,105 @@
+import type { SessionHostSurfaceRecordLike } from '../session-host/runtime-surface.js';
+import type { LocalMeshEntry } from '../repo-mesh-types.js';
+export declare const DAY_MS: number;
+/** JSONL ledger files are legacy after the SQLite ledger — 30-day lifetime. */
+export declare const LEDGER_JSONL_MAX_AGE_MS: number;
+/** Terminated session-host runtimes: conservative 14-day retention. */
+export declare const SESSION_HOST_RUNTIME_MAX_AGE_MS: number;
+/** mesh-runtime.db.bak-* backups: 7-day retention. */
+export declare const DB_BAK_MAX_AGE_MS: number;
+/** A file candidate for age-based pruning: absolute path + last-modified epoch ms. */
+export interface AgedFile {
+    path: string;
+    mtimeMs: number;
+}
+/**
+ * PURE. Select the JSONL ledger files whose mtime is older than `maxAgeMs`
+ * relative to `now`. A file exactly at the threshold is KEPT (strict `>`), so a
+ * 30-day-old file survives its 30th day and is pruned on the 31st. Deterministic:
+ * no fs access, no clock read.
+ */
+export declare function selectExpiredLedgerJsonl(files: AgedFile[], now: number, maxAgeMs?: number): AgedFile[];
+/** A parsed session-host runtime file: its path, mtime, and the wrapped record. */
+export interface SessionHostRuntimeFile {
+    path: string;
+    mtimeMs: number;
+    /** The `record` object from the on-disk `{ record, snapshot, updatedAt }` file. */
+    record: SessionHostSurfaceRecordLike | null;
+}
+/**
+ * PURE. Select the session-host runtime files safe to delete: ONLY those whose
+ * runtime is terminated/dead (NOT a live runtime — decided by the session-host-core
+ * SSOT `isSessionHostLiveRuntime`) AND older than `maxAgeMs`. A live runtime, or a
+ * dead-but-recent one, is always kept. A file whose record failed to parse is treated
+ * as NON-live but is still age-gated, so a corrupt-but-fresh file is never removed.
+ */
+export declare function selectExpiredSessionHostRuntimes(files: SessionHostRuntimeFile[], now: number, maxAgeMs?: number): SessionHostRuntimeFile[];
+/** True for a `mesh-runtime.db.bak-*` backup filename (basename only). */
+export declare function isDbBackupFileName(name: string): boolean;
+/** PURE. Select `.bak-*` backups older than `maxAgeMs`. Strict `>` (see ledger). */
+export declare function selectExpiredDbBackups(files: AgedFile[], now: number, maxAgeMs?: number): AgedFile[];
+/** Minimal shape needed to decide whether a worktree path is orphaned. */
+export interface WorktreePathLike {
+    path: string;
+    bare?: boolean;
+}
+/** A live mesh node's known workspace paths (self workspace + repoRoot, normalized). */
+export interface LiveNodeWorkspaceLike {
+    workspace?: string;
+    repoRoot?: string;
+}
+/**
+ * PURE. Given the worktrees git reports on disk and the set of live-node workspace
+ * paths, return the worktrees that have NO matching live node — the orphan
+ * cleanup_candidates.
+ *
+ * SAFETY:
+ *  - `mainWorktreePath` (the primary repo checkout, i.e. worktree[0]) is NEVER an
+ *    orphan — it is the base repo, not a mesh clone.
+ *  - `bare` worktrees are skipped (git's internal bookkeeping, not a node checkout).
+ *  - Matching is path-equality after trailing-separator normalization against the
+ *    union of every live node's `workspace` and `repoRoot`.
+ * This is DETECTION ONLY — the caller signals a cleanup_candidate; it must not delete.
+ */
+export declare function detectOrphanWorktrees(worktrees: WorktreePathLike[], liveNodes: LiveNodeWorkspaceLike[], mainWorktreePath: string): WorktreePathLike[];
+/**
+ * Prune expired legacy JSONL ledger files under ~/.adhdev/mesh-ledger/.
+ * Matches only `*.jsonl` (never the SQLite .db / -wal / -shm files). Returns the
+ * count deleted. Best-effort: individual unlink failures are logged, not thrown.
+ */
+export declare function pruneExpiredLedgerJsonl(now?: number): number;
+/**
+ * Prune expired `mesh-runtime.db.bak-*` backups under ~/.adhdev/mesh-ledger/.
+ * Never touches the live DB (only names matching the .bak- prefix). Returns count.
+ */
+export declare function pruneExpiredDbBackups(now?: number): number;
+/**
+ * Prune terminated session-host runtime files older than 14 days across every
+ * ~/.adhdev/session-host/<app>/runtimes/ directory. A LIVE runtime is never deleted
+ * regardless of age (isSessionHostLiveRuntime SSOT). Returns count deleted.
+ */
+export declare function pruneExpiredSessionHostRuntimes(now?: number): number;
+/**
+ * Run the file-deleting retention passes (JSONL ledger, DB backups, session-host
+ * runtimes) once. Each pass is isolated so one failing pass never blocks the others.
+ * Orphan-worktree DETECTION is driven separately in the reconcile loop (it needs the
+ * live mesh config + git worktree list and emits a ledger signal rather than deleting).
+ */
+export declare function runDiskRetentionSweep(now?: number): {
+    ledgerJsonl: number;
+    dbBackups: number;
+    sessionHostRuntimes: number;
+};
+/**
+ * Detect orphaned worktrees for ONE mesh and emit a `worktree_cleanup_candidate`
+ * ledger signal for each — DETECTION ONLY, never deletes. An orphan is a git worktree
+ * on disk with no matching live mesh node (compared by path). It:
+ *   1. picks a base (non-worktree) node owned by this mesh to anchor `git worktree list`;
+ *   2. diffs the reported worktrees against the union of every node's workspace/repoRoot;
+ *   3. skips the main worktree + bare entries (detectOrphanWorktrees safety);
+ *   4. suppresses a repeat for a worktreePath already signalled within the recent window
+ *      (idempotent re-emit guard), so the hourly sweep doesn't spam the ledger.
+ * Returns the list of newly-signalled orphan paths. Best-effort: git/ledger failures are
+ * logged and yield an empty result, never thrown.
+ */
+export declare function detectAndSignalOrphanWorktrees(mesh: LocalMeshEntry, now?: number): Promise<string[]>;

package/dist/mesh/mesh-ledger.d.ts

@@ -15,7 +15,7 @@
 import { EventEmitter } from 'events';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
 import { type MeshLedgerOriginatingCoordinatorV2 } from './contracts.js';
-export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'p2p_dispatch_failed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled' | 'direct_fast_forward' | 'delivery_unroutable' | 'direct_dispatch_pruned' | 'event_held' | 'event_held_requeued' | 'task_reclaimed' | 'coordinator_operating_note' | 'coordinator_operating_note_tombstone' | 'mission_created' | 'mission_status_changed' | 'mission_goal_updated' | 'magi_dispatched' | 'magi_synthesis' | 'key_injection';
+export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'p2p_dispatch_failed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled' | 'direct_fast_forward' | 'delivery_unroutable' | 'direct_dispatch_pruned' | 'event_held' | 'event_held_requeued' | 'task_reclaimed' | 'coordinator_operating_note' | 'coordinator_operating_note_tombstone' | 'mission_created' | 'mission_status_changed' | 'mission_goal_updated' | 'magi_dispatched' | 'magi_synthesis' | 'key_injection' | 'worktree_cleanup_candidate';
 export interface MeshLedgerEntry {
     id: string;
     meshId: string;
@@ -162,6 +162,33 @@ export declare const OPERATING_NOTE_KIND: MeshLedgerKind;
 export declare const OPERATING_NOTE_TOMBSTONE_KIND: MeshLedgerKind;
 export declare const OPERATING_NOTE_DEDUPE_WINDOW = 40;
 export declare const OPERATING_NOTE_KEEP_LATEST = 100;
+export declare const OPERATING_NOTE_CATEGORY_TTL_DAYS: Readonly<Record<string, number>>;
+/**
+ * Shape isNoteExpired reads. Structural so mesh-ledger stays free of a
+ * coordinator-prompt import (CoordinatorOperatingNote satisfies this).
+ */
+export interface OperatingNoteExpiryInput {
+    category?: string;
+    pinned?: boolean;
+    createdAt?: string;
+    /** Explicit expiry override; wins over the category TTL when parseable. */
+    expiresAt?: string;
+    /** Fallback creation time (ledger entry timestamp) when createdAt absent. */
+    timestamp?: string;
+}
+/**
+ * Pure helper: is this UNPINNED operating note expired as of `now` (epoch ms)?
+ *
+ * Rules:
+ *  - pinned notes NEVER expire (always false).
+ *  - an explicit, parseable `expiresAt` in the past → expired.
+ *  - otherwise the category TTL applies; a durable category (provider_quirk,
+ *    uncategorized, or any category not in the TTL map) never expires.
+ *  - age is measured from createdAt, falling back to `timestamp` (ledger entry
+ *    time). If neither is a valid date, the note is treated as NOT expired
+ *    (never silently drop a note we cannot age).
+ */
+export declare function isNoteExpired(note: OperatingNoteExpiryInput, now: number): boolean;
 export declare function getLedgerDir(): string;
 /**
  * Footer to append to worker task messages so workers output structured results

package/dist/mesh/mesh-runtime-store.d.ts

@@ -23,6 +23,17 @@ export declare class MeshRuntimeStore {
     private static loggedGetInstanceFailure;
     static getInstance(): MeshRuntimeStore;
     static resetForTests(): void;
+    /**
+     * VACUUM the SQLite database to reclaim on-disk space. Retention prunes rows
+     * with DELETE, which frees pages inside the file but does NOT shrink it — the
+     * mesh-runtime.db grew to hundreds of MB (mission 86def38d disk-accumulation
+     * bootstrap failure) precisely because the file was never compacted. This
+     * rewrites the DB into a minimal footprint. Best-effort: a VACUUM failure (e.g.
+     * insufficient temp space, a read lock) is logged and swallowed so it can never
+     * block daemon shutdown. Called once on shutdown (see daemon-lifecycle), never
+     * on the hot path — VACUUM takes an exclusive lock and rewrites the whole file.
+     */
+    vacuum(): void;
     close(): void;
     transaction<T>(fn: () => T): T;
     private migrate;

package/dist/providers/cli-provider-instance-types.d.ts

@@ -39,6 +39,8 @@ export declare const COMPLETED_FINALIZATION_RETRY_MS = 1000;
 export declare const COMPLETED_FINALIZATION_MAX_WAIT_MS = 30000;
 export declare const NATIVE_HISTORY_MESH_IDLE_SETTLE_MS = 4000;
 export declare const PTY_PARSED_FINAL_ASSISTANT_QUIET_DWELL_MS = 1200;
+export declare const ANTIGRAVITY_HOLD_QUIET_DWELL_MS = 3000;
+export declare const ANTIGRAVITY_HOLD_HARD_CAP_MS: number;
 export declare const BACKGROUND_TASK_HOLD_MAX_MS: number;
 export declare const USER_INPUT_ACK_DEDUP_WINDOW_MS = 60000;
 export declare const STARTUP_GRACE_IDLE_COLLAPSE_WINDOW_MS = 12000;

package/dist/providers/cli-provider-instance.d.ts

@@ -473,6 +473,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private completionFinalSummary;
     private buildCompletedFinalizationDiagnostic;
     private hasAdapterPendingResponse;
+    private antigravityHoldPtyStillActive;
     private shouldSuppressStaleParsedBusyStatus;
     private getCompletedFinalizationBlock;
     private hasApprovalResolutionEvidence;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "1.0.18-rc.5",
+  "version": "1.0.18-rc.7",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,8 +47,8 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "1.0.18-rc.5",
-    "@adhdev/session-host-core": "1.0.18-rc.5",
+    "@adhdev/mesh-shared": "1.0.18-rc.7",
+    "@adhdev/session-host-core": "1.0.18-rc.7",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

package/src/boot/daemon-lifecycle.ts

@@ -39,6 +39,7 @@ import type { IdeProviderInstance } from '../providers/ide-provider-instance.js'
 import { createDefaultGitCommandServices } from '../git/git-commands.js';
 import { setupMeshEventForwarding } from '../mesh/mesh-events.js';
 import { setupMeshReconcileLoop } from '../mesh/mesh-reconcile-loop.js';
+import { MeshRuntimeStore } from '../mesh/mesh-runtime-store.js';
 import { loadMeshCoordinatorRegistry } from '../mesh/coordinator-registry.js';
 import { applyProcessHardening } from './process-hardening.js';
 import { installProviderProcessShim } from '../providers/sdk/v1/sandbox/require-whitelist.js';
@@ -503,4 +504,13 @@ export async function shutdownDaemonComponents(components: DaemonComponents): Pr
         try { m.disconnect(); } catch { /* noop */ }
     }
     cdpManagers.clear();
+
+    // 7. VACUUM the mesh runtime DB. Retention prunes rows with DELETE (frees pages
+    // inside the file but never shrinks it); the mesh-runtime.db grew to hundreds of
+    // MB (mission 86def38d disk-accumulation bootstrap failure) because it was never
+    // compacted. Do this LAST, after all writers (reconcile loop, CLIs, instances)
+    // are stopped, so nothing contends for the exclusive VACUUM lock. Best-effort —
+    // vacuum() swallows its own errors; the try/catch guards the getInstance() throw
+    // when the store never opened (degraded JSONL-only mode).
+    try { MeshRuntimeStore.getInstance().vacuum(); } catch { /* store unavailable — nothing to vacuum */ }
 }

package/src/commands/high-family/mesh-coordinator-launch.ts

@@ -131,6 +131,11 @@ export const meshCoordinatorLaunchHandlers: Record<string, HighFamilyHandler> =
                                         category,
                                         createdAt: typeof p.createdAt === 'string' ? p.createdAt : e.timestamp,
                                         sourceCoordinator: typeof p.sourceCoordinator === 'string' ? p.sourceCoordinator : undefined,
+                                        // Operating-notes lifecycle: thread pinned/expiresAt so the
+                                        // injection-side selection can honor them. Legacy notes lack
+                                        // these → pinned defaults false, expiry governed by category TTL.
+                                        pinned: p.pinned === true,
+                                        ...(typeof p.expiresAt === 'string' ? { expiresAt: p.expiresAt } : {}),
                                     };
                                 })
                                 .filter((n): n is NonNullable<typeof n> => n !== null);

package/src/commands/windows-atomic-upgrade.ts

@@ -162,13 +162,31 @@ function quotePowerShellLiteral(value: string): string {
 function pinStagedShims(prefix: string, portableNode: string, cliEntry: string): void {
   const cmdPath = path.join(prefix, 'adhdev.cmd');
   const ps1Path = path.join(prefix, 'adhdev.ps1');
+  // The no-extension `adhdev` shim is what `where.exe adhdev` can resolve first
+  // and what git-bash / MSYS / WSL and `spawnSync('adhdev')` invoke. npm generates
+  // it as a POSIX `sh` shim whose ELSE branch falls back to the FIRST `node` on
+  // PATH (`else exec node ...`). On a box where system PATH node is v24, that
+  // fallback trips adhdev's own Node-24 guard and `adhdev doctor` reports the
+  // runtime surface broken. Rewrite it too so it hard-codes the portable Node 22
+  // absolute path with NO system-node fallback — mirroring the .cmd/.ps1 pins.
+  const noExtPath = path.join(prefix, 'adhdev');
   const cmd = `@echo off\r\n"${portableNode}" "${cliEntry}" %*\r\n`;
   const ps1 = `#!/usr/bin/env pwsh\r\n& ${quotePowerShellLiteral(portableNode)} ${quotePowerShellLiteral(cliEntry)} @args\r\nexit $LASTEXITCODE\r\n`;
+  // sh shim: single unconditional exec of the pinned node — no `if -x node` /
+  // `else exec node` branch, so PATH ordering can never shadow the runtime.
+  const noExt = `#!/bin/sh\nexec "${portableNode}" "${cliEntry}" "$@"\n`;
   fs.writeFileSync(cmdPath, cmd, 'ascii');
   fs.writeFileSync(ps1Path, ps1, 'utf8');
+  fs.writeFileSync(noExtPath, noExt, 'ascii');
   const cmdReadback = fs.readFileSync(cmdPath, 'utf8');
   const ps1Readback = fs.readFileSync(ps1Path, 'utf8');
-  if (!cmdReadback.includes(portableNode) || !ps1Readback.includes(portableNode)) {
+  const noExtReadback = fs.readFileSync(noExtPath, 'utf8');
+  if (
+    !cmdReadback.includes(portableNode)
+    || !ps1Readback.includes(portableNode)
+    || !noExtReadback.includes(portableNode)
+    || /(^|\s)exec\s+node(\s|$)/m.test(noExtReadback)
+  ) {
     throw new Error('portable Node 22 pin validation failed');
   }
 }

package/src/config/mesh-json-config.ts

@@ -160,6 +160,10 @@ function normalizeOperatingNote(value: unknown): CoordinatorOperatingNote | null
         ...(category ? { category } : {}),
         ...(typeof value.createdAt === 'string' ? { createdAt: value.createdAt } : {}),
         ...(typeof value.sourceCoordinator === 'string' ? { sourceCoordinator: value.sourceCoordinator } : {}),
+        // Operating-notes lifecycle: a repo-declared note may pin itself or set an
+        // explicit expiry, same as a runtime-recorded one.
+        ...(value.pinned === true ? { pinned: true } : {}),
+        ...(typeof value.expiresAt === 'string' ? { expiresAt: value.expiresAt } : {}),
     };
 }
 

package/src/mesh/coordinator-prompt.ts

@@ -34,6 +34,7 @@ import type {
 import { mergeAndNormalizePolicy, resolveProviderMaxParallel } from '../repo-mesh-types.js';
 import { getDifficultyBrains } from '../config/mesh-config.js';
 import { resolveNodeCapabilitySlots } from './mesh-node-slots.js';
+import { isNoteExpired, OPERATING_NOTE_CATEGORY_TTL_DAYS } from './mesh-ledger.js';
 import { MESH_TASK_DIFFICULTIES } from '@adhdev/mesh-shared';
 import type { MagiKindPanelMap, MagiSlot, MagiTaskKind } from '@adhdev/mesh-shared';
 
@@ -84,6 +85,20 @@ export interface CoordinatorOperatingNote {
     category?: 'provider_quirk' | 'pattern_to_avoid' | 'recovery_lesson';
     createdAt?: string;
     sourceCoordinator?: string;
+    /**
+     * Operating-notes lifecycle (minimal first cut). When true the note ALWAYS
+     * rides into the coordinator prompt — it is never dropped by TTL expiry and
+     * survives the injection cap ahead of unpinned notes. Legacy notes without
+     * this field default to false.
+     */
+    pinned?: boolean;
+    /**
+     * Optional explicit expiry ISO timestamp. When set and in the past, an
+     * UNPINNED note is dropped from the injected prompt (read-side only — the
+     * ledger entry is never pruned by age). When absent, the category→TTL map
+     * (see isNoteExpired) governs expiry; pinned notes never expire regardless.
+     */
+    expiresAt?: string;
 }
 
 // ─── Prompt Builder ─────────────────────────────
@@ -582,11 +597,65 @@ function buildRecentActivitySection(activity?: CoordinatorRecentActivity): strin
 const OPERATING_NOTES_PROMPT_CAP = 20;
 const OPERATING_NOTE_MAX_CHARS = 300;
 
-function buildOperatingNotesSection(notes?: CoordinatorOperatingNote[]): string {
+/**
+ * A category is "durable" (survives the cap ahead of recency) when it has no
+ * TTL entry — provider_quirk, uncategorized, or any unknown category. This
+ * mirrors isNoteExpired's durability rule so ranking and expiry agree.
+ */
+function isDurableCategory(category?: string): boolean {
+    if (!category) return true;
+    return !(category in OPERATING_NOTE_CATEGORY_TTL_DAYS);
+}
+
+/**
+ * Operating-notes lifecycle selection (read-side, minimal first cut). Given the
+ * effective notes (oldest-first, ledger order) and the current time, produce the
+ * ordered, capped list that rides into the prompt:
+ *   (i)   ALWAYS include pinned notes.
+ *   (ii)  drop expired UNPINNED notes (per category TTL / explicit expiresAt).
+ *   (iii) rank pinned-first, then durable-category, then recency (newest first).
+ *   (iv)  apply the existing OPERATING_NOTES_PROMPT_CAP to the ranked list.
+ * Pure + deterministic given `now`. Returns { shown, omittedCount }.
+ *
+ * Ranking is stable on the original ledger index so, within a tier, the original
+ * oldest-first order is preserved before the recency comparison flips it — i.e.
+ * newest notes lead each tier. The cap keeps the leading (highest-priority) N.
+ */
+export function selectOperatingNotesForPrompt(
+    notes: CoordinatorOperatingNote[],
+    now: number,
+    cap: number = OPERATING_NOTES_PROMPT_CAP,
+): { shown: CoordinatorOperatingNote[]; omittedCount: number } {
     const valid = Array.isArray(notes)
         ? notes.filter(n => n && typeof n.text === 'string' && n.text.trim())
         : [];
-    if (valid.length === 0) return '';
+
+    // (i)+(ii): keep pinned always; drop expired unpinned. Retain original index
+    // for a stable recency tiebreak (later index == newer, ledger is oldest-first).
+    const kept = valid
+        .map((note, index) => ({ note, index }))
+        .filter(({ note }) => note.pinned || !isNoteExpired(note as any, now));
+
+    // (iii): rank pinned > durable > recency (newest first within a tier).
+    const rank = (n: CoordinatorOperatingNote): number =>
+        n.pinned ? 0 : isDurableCategory(n.category) ? 1 : 2;
+    kept.sort((a, b) => {
+        const r = rank(a.note) - rank(b.note);
+        if (r !== 0) return r;
+        return b.index - a.index; // newer (higher index) first
+    });
+
+    // (iv): apply the existing cap to the ranked list.
+    const omittedCount = Math.max(0, kept.length - cap);
+    const shown = (omittedCount > 0 ? kept.slice(0, cap) : kept).map(k => k.note);
+    return { shown, omittedCount };
+}
+
+function buildOperatingNotesSection(notes?: CoordinatorOperatingNote[], now: number = Date.now()): string {
+    const hasAny = Array.isArray(notes)
+        ? notes.some(n => n && typeof n.text === 'string' && n.text.trim())
+        : false;
+    if (!hasAny) return '';
 
     const categoryLabel: Record<string, string> = {
         provider_quirk: 'provider quirk',
@@ -594,21 +663,23 @@ function buildOperatingNotesSection(notes?: CoordinatorOperatingNote[]): string
         recovery_lesson: 'recovery lesson',
     };
 
-    // Keep only the most recent OPERATING_NOTES_PROMPT_CAP notes in the prompt.
-    // `valid` is oldest-first (ledger order), so the newest are at the tail.
-    const omittedCount = Math.max(0, valid.length - OPERATING_NOTES_PROMPT_CAP);
-    const shown = omittedCount > 0 ? valid.slice(-OPERATING_NOTES_PROMPT_CAP) : valid;
+    // Lifecycle selection: pinned-always + expired-unpinned-dropped + rank
+    // (pinned > durable > recency) THEN the existing cap. `shown` is already
+    // highest-priority-first; the cap kept the leading N.
+    const { shown, omittedCount } = selectOperatingNotesForPrompt(notes ?? [], now);
+    if (shown.length === 0) return '';
 
     const lines: string[] = ['## Operating Notes', ''];
     lines.push('Lessons earlier coordinators on this mesh recorded via `mesh_record_note`. Treat them as accumulated operating knowledge — apply them. When you learn a durable lesson (a provider quirk, a pattern to avoid, a recovery lesson), record it with `mesh_record_note` so future coordinators inherit it.');
     lines.push('');
     for (const n of shown) {
+        const pin = n.pinned ? '📌 ' : '';
         const cat = n.category && categoryLabel[n.category] ? `[${categoryLabel[n.category]}] ` : '';
-        lines.push(`- ${cat}${truncateNote(n.text.trim())}`);
+        lines.push(`- ${pin}${cat}${truncateNote(n.text.trim())}`);
     }
     if (omittedCount > 0) {
         lines.push('');
-        lines.push(`_${omittedCount} older note${omittedCount === 1 ? '' : 's'} omitted (kept in ledger; prune with \`mesh_forget_note\`)._`);
+        lines.push(`_${omittedCount} lower-priority note${omittedCount === 1 ? '' : 's'} omitted (kept in ledger; expired-and-unpinned notes are also hidden from this list but retained for audit; prune with \`mesh_forget_note\`)._`);
     }
     return lines.join('\n');
 }