@amsterdamdatalabs/enact-extensions 0.1.30 → 0.1.35

package/extensions/enact-factory/skills/cmux-leader/SKILL.md

@@ -1,130 +1,70 @@
 ---
 name: cmux-leader
-description: "Become the cmux LEADER — spawn, brief, poll, unblock, and verify up to 5 parallel claude follower terminals in one cmux workspace. Use when orchestrating multi-session work across sibling terminals, driving followers, or coordinating parallel agents. Followers message back via the cmux-send skill."
+description: "Become the cmux LEADER — spawn, root-per-repo, brief, poll, unblock, and verify parallel claude follower terminals from a neutral leader. Use when orchestrating multi-session work across sibling terminals. Followers reply via the cmux-send skill."
 ---
 
 # cmux-leader — you are the LEADER
 
-You are a Claude Code session running **inside a cmux workspace**. You act as the
-**leader/orchestrator**: you spawn, brief, poll, unblock, and verify **follower** claude sessions
-running in sibling terminals of the same workspace. You coordinate; followers do the hands-on work.
+You run inside a cmux workspace and orchestrate **follower** claude sessions in sibling terminals.
+You coordinate; followers do the hands-on work. Keep your own context for the plan and the gates.
 
-## Hard rules
+## Hard rules (learned the hard way)
 
-- **Terminal surfaces only.** Followers are `claude` running in a **terminal** surface. `agent-session`
-  surfaces (`new-surface --type agent-session`) are NOT scriptable — `send` / `read-screen` fail on them
-  with `Surface is not a terminal`. Always launch followers as `claude` in a terminal.
-- **Max 5 parallel claude sessions**, all **horizontal splits** in **one** workspace.
-- **Start each follower from the directory its work lives in** — so enact-context warms the right repo
-  (`enact-context: ON` must print on that session's shell start).
-- **Lead from a NEUTRAL parent dir** (e.g. the common parent of all repos). The enact-loop **Stop hook
-  resolves the active loop by SHELL cwd** — if you `cd` into a follower's repo you inherit that loop's
-  Stop boulder and it blocks YOUR exit. To inspect a follower's repo use `git -C <path> …` /
-  absolute paths; **never `cd` into a follower repo.**
-- **You orchestrate, you don't do the followers' work.** Assign → poll → unblock → verify. Keep your own
-  context for the plan and the merge/verification gates.
-- One leader per workspace. If another session is already leading, don't fight it — coordinate.
+- **One surface per directory.** A working tree cannot have two drivers — two followers, or leader +
+  a follower, in the same repo causes git collisions and duplicate PRs. If two must touch one repo,
+  give each its own `git worktree`.
+- **Verify cwd BEFORE launching claude.** `new-split`/`new-surface` do NOT take a working-directory
+  flag — a new pane inherits the parent's cwd. Always `cd <repo>` then confirm `pwd` *before* you run
+  `claude`, or the follower boots in the wrong repo.
+- **Lead from a NEUTRAL dir** (the common parent of all repos). The enact-loop Stop hook resolves the
+  active loop by SHELL cwd — if you `cd` into a follower's repo you inherit its Stop boulder and it
+  blocks your exit. Inspect a follower's repo with `git -C <path> …`, never a persistent `cd`.
+- **Spawn on demand.** Don't pre-create followers for ungreenlit work — idle sessions burn tokens.
+  Create one only when a concrete task is ready; `close-surface` it when its work is done.
+- **Before opening a PR, check no follower already opened one** for that branch (avoid duplicate PRs).
+- **Don't accept self-reported green** — verify against real output (tests, build, PR state).
+- **Max 5 claude sessions**, horizontal splits, one workspace.
 
-## Orient first (always run these)
+## Commands I use
 
 ```bash
-cmux current-window                       # which window
-cmux workspace list                       # workspaces (this leader's is [selected])
-cmux list-panes                           # panes in the workspace
-cmux list-pane-surfaces                   # surfaces (sessions) in the focused pane
-cmux list-pane-surfaces --pane pane:N     # surfaces in a specific pane
-```
-
-Identify each surface by name (e.g. `FOLLOWER-enact-wiki`). A surface you can `read-screen` is a
-terminal session you can drive. Re-discover topology each session — never hardcode surface numbers.
-
-## Read a follower
-
-```bash
-cmux read-screen --surface surface:N --lines 40         # tail of the live screen
-cmux read-screen --surface surface:N --scrollback       # full scrollback
-```
-
-**In every follower briefing, tell the follower to use the `cmux-send` skill** for all replies — the
-`[from] to [to]` envelope and the send→verify→enter submit protocol. A follower that doesn't know
-cmux-send will park half-formed messages and break the relay.
-
-## Drive a follower (see the cmux-send skill for the full messaging protocol)
-
-```bash
-cmux send --surface surface:N "your prompt here\n"      # \n = Enter
-cmux read-screen --surface surface:N --lines 12         # VERIFY it submitted
-cmux send-key --surface surface:N enter                 # if it parked in the ❯ box (booting/thinking)
-cmux send-key --surface surface:N ctrl+c                # interrupt a runaway follower
-```
-
-**Always `read-screen` after every `send`** to confirm it landed. If still in the `❯` box, follow with
-`send-key … enter` — NOT `ctrl+b`. `ctrl+b` only flushes a *queued* message when the follower has a
-**running bash command** to background; while it is purely thinking, `ctrl+b` does nothing — just wait.
-
-## Spawn a new follower (horizontal split, rooted in the work dir)
+# Orient (re-discover every turn; surface numbers renumber)
+cmux list-panes
+cmux list-pane-surfaces [--pane pane:N]      # name each surface
+cmux tree                                    # process/Surface tree (optional)
+
+# Read a follower
+cmux read-screen --surface surface:N [--lines 40] [--scrollback]
+
+# Drive a follower  (\n = Enter)
+cmux send --surface surface:N "text\n"
+cmux send-key --surface surface:N enter      # submit a parked message
+cmux send-key --surface surface:N ctrl+c     # interrupt a runaway
+cmux send-key --surface surface:N ctrl+b     # flush a QUEUED msg — only if a command is running
+
+# Spawn a follower (root it correctly, THEN launch claude)
+cmux new-split right --focus false                 # -> surface:N
+cmux send --surface surface:N "cd /abs/repo && pwd\n"
+cmux read-screen --surface surface:N --lines 5     # CONFIRM pwd == the repo
+cmux send --surface surface:N "claude\n"
 
-```bash
-cmux new-split right --focus false                          # -> "OK surface:N pane:M ..."
-cmux send --surface surface:N "cd /abs/path/to/repo && claude\n"
-cmux read-screen --surface surface:N --lines 20             # confirm boot
-cmux send --surface surface:N "You are a FOLLOWER under the cmux leader. <role + task>.\n"
-cmux send-key --surface surface:N enter                     # Enter explicitly (it was booting)
+# Close a finished/dead follower
+cmux close-surface --surface surface:N
 ```
 
-One-shot terminal with an explicit cwd (no `cd` needed):
-
-```bash
-cmux new-surface --type terminal --working-directory /abs/path/to/repo --pane pane:M --focus false
-cmux send --surface surface:N "claude\n"
-```
+## Messaging — always use the cmux-send skill
 
-Keep all splits horizontal; stop at 5 claude sessions total.
+Every follower briefing must tell the follower to use the **cmux-send** skill. Each message: prefix
+`[LEADER] to [FOLLOWER-<name>] `, end with `Respond back once you are done with using prefix
+"[FOLLOWER-<name>] to [LEADER] "`. After every `send`, `read-screen` to confirm it submitted; if it's
+parked in the `❯` box, `send-key … enter` (NOT `ctrl+b`).
 
 ## Leader loop
 
-1. **Plan & shard.** Break the goal into independent slices, one per follower (≤5). Pick each slice's
-   repo/dir so enact-context warms the right context.
-2. **Spawn & brief.** Split → `cd <dir> && claude` → send a self-contained briefing (role, scope,
-   exit criteria, "report back in one line when done/blocked") using the cmux-send envelope.
-3. **Poll.** Round-robin `read-screen` each follower. Watch for: finished, blocked, asking a question,
-   or idle at the `❯` prompt.
-4. **Unblock.** Answer questions / re-scope via `send`. Never reach into a follower's repo yourself
-   unless you're the session that owns it.
-5. **Verify & gate.** When a follower claims done, verify against real output (tests, build, PR state)
-   before you treat the slice as green. Don't accept self-reported green.
-6. **Close.** Summarize across followers; drive the merge / final gate from the leader.
-
-## Standing watch — poll every ~15 min, never go idle while followers run
-
-A follower that finishes its task goes **idle at the `❯` prompt** — from the leader's seat that looks
-identical to "stalled." `done` ≠ `handled`. If you go idle too, every lane stops and the user sees a
-stalled board. Keep a **~15-minute poll cadence** for as long as any follower is live:
-
-1. **(Re)discover topology first** — `cmux list-pane-surfaces [--pane pane:N]`. Never assume surface
-   numbers held across turns; they renumber.
-2. **`read-screen` every follower** and classify each: *working* · *idle-done* · *parked message in the
-   `❯` box* · *blocked / asking* · *ctx ≥ 80% (needs `/compact`)*.
-3. **Act per state:** idle-done → assign the next work package or explicitly park it · parked → `send-key
-   enter` · blocked/asking → answer · ctx ≥ 80% → tell it to `/compact` then resume.
-4. **Report deltas to the user**, then schedule the next poll ~15 min out (e.g. via the `loop` skill or a
-   self-scheduled wake-up). Idle followers are wasted parallelism — the poll is how you keep all lanes fed.
-
-## Quick reference (verified surface)
-
-| Need | Command |
-|---|---|
-| List sessions | `cmux list-pane-surfaces [--pane pane:N]` |
-| Read a session | `cmux read-screen --surface surface:N --lines 40` |
-| Send + submit | `cmux send --surface surface:N "text\n"` |
-| Submit a parked msg | `cmux send-key --surface surface:N enter` |
-| Flush a queued msg (only if a command is running) | `cmux send-key --surface surface:N ctrl+b` |
-| Interrupt | `cmux send-key --surface surface:N ctrl+c` |
-| New right split | `cmux new-split right --focus false` |
-| Terminal w/ cwd | `cmux new-surface --type terminal --working-directory <path> --pane pane:N` |
-| Focus a pane | `cmux focus-pane --pane pane:N` |
-
-Gotchas: agent-session ≠ scriptable (terminal only) · `\n` may not submit during boot/thinking (use
-`send-key enter`) · `read-screen` takes `--surface`, not `--pane` · a `send` to a busy follower queues
-and delivers at turn-end — `ctrl+b` flushes it **only if a command is running** · leader must not `cd`
-into a follower repo (Stop-hook boulder capture — use `git -C`).
+1. **Shard** the goal into independent slices, one repo per follower.
+2. **Spawn & brief** — split → `cd <repo>` (verify pwd) → `claude` → self-contained briefing (role,
+   scope, exit criteria, "use cmux-send to reply, report in one line").
+3. **Poll on a ~15-min cadence** — never go idle while followers run. Re-discover topology, `read-screen`
+   each, classify (working / idle-done / parked / blocked / ctx≥80%), and act: parked → `send-key enter`;
+   ctx≥80% → tell it to `/compact`; blocked → answer; idle-done → assign next or `close-surface`.
+4. **Verify & gate** — confirm real output before treating a slice as green; drive merges from the leader.

package/extensions/enact-factory/skills/cmux-send/SKILL.md

@@ -1,28 +1,26 @@
 ---
 name: cmux-send
-description: "How to correctly send a message to a cmux follower surface — the send→verify→enter protocol and the [from] to [to] message envelope. Use whenever messaging a cmux session (leader→follower or follower→leader)."
+description: "How to correctly message a cmux surface — the send→verify→enter protocol and the [from] to [to] envelope. Use whenever messaging a cmux session (leader→follower or follower→leader)."
 ---
 
 # cmux-send — message a cmux surface correctly
 
-Sending a cmux message has two parts that are easy to get wrong: **submitting** it, and **wrapping** it.
+Two parts are easy to get wrong: **submitting** the message and **wrapping** it.
 
 ## 1. Submit protocol (always verify the Enter landed)
 
 ```bash
 cmux send --surface surface:N "<one-line message>\n"   # \n = Enter
 cmux read-screen --surface surface:N --lines 12         # VERIFY it submitted
-# If the text is still sitting in the `❯` box (not submitted):
-cmux send-key --surface surface:N enter
+cmux send-key --surface surface:N enter                 # if still in the ❯ box (booting/thinking)
 ```
 
-- **Always `read-screen` after `send`.** A `\n` may NOT submit if the follower was booting or thinking —
-  the text parks in the `❯` box.
-- **To submit a parked message, use `send-key … enter` — NOT `ctrl+b`.** `ctrl+b` only flushes a
-  *queued* message when the follower has a **running bash command** to background; on an idle or
-  purely-thinking follower it does nothing.
+- **Always `read-screen` after `send`.** A `\n` may not submit while the follower is booting or
+  thinking — the text parks in the `❯` box.
+- **To submit a parked message use `send-key … enter`, NOT `ctrl+b`.** `ctrl+b` only flushes a *queued*
+  message when the follower has a **running bash command** to background; while it is purely thinking,
+  `ctrl+b` does nothing — just wait.
 - **One line only.** Every literal `\n` submits, so a multi-line prompt fires early and fragments.
-  Compose the whole message on a single line; the trailing `\n` is the only submit.
 - `read-screen` takes `--surface`, not `--pane`.
 
 ## 2. Message envelope (every message)
@@ -30,8 +28,8 @@ cmux send-key --surface surface:N enter
 - **Start with:** `[<from-surface-name>] to [<to-surface-name>] `
 - **End with:** `Respond back once you are done with using prefix "[<to-surface-name>] to [<from-surface-name>] "`
 
-Surface names are the human labels (e.g. `LEADER`, `FOLLOWER-enact-wiki`), not `surface:N`. Map them with
-`cmux list-pane-surfaces [--pane pane:N]`.
+Surface names are the human labels (e.g. `LEADER`, `FOLLOWER-enact-wiki`), not `surface:N`. Map them
+with `cmux list-pane-surfaces [--pane pane:N]`.
 
 ### Example (leader → follower)
 
@@ -40,13 +38,3 @@ cmux send --surface surface:3 "[LEADER] to [FOLLOWER-enact-wiki] <instruction on
 cmux read-screen --surface surface:3 --lines 12
 # still in the ❯ box? -> cmux send-key --surface surface:3 enter
 ```
-
-## Quick reference
-
-| Need | Command |
-|---|---|
-| Send + submit | `cmux send --surface surface:N "text\n"` |
-| Verify it landed | `cmux read-screen --surface surface:N --lines 12` |
-| Submit a parked message | `cmux send-key --surface surface:N enter` |
-| Flush a QUEUED msg (only if a command is running) | `cmux send-key --surface surface:N ctrl+b` |
-| Interrupt a runaway | `cmux send-key --surface surface:N ctrl+c` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amsterdamdatalabs/enact-extensions",
-  "version": "0.1.30",
+  "version": "0.1.35",
   "description": "Create and validate Enact multi-platform plugin manifests",
   "license": "UNLICENSED",
   "type": "module",

package/scripts/enact-extensions.mjs

@@ -938,6 +938,8 @@ if (command === "serve") {
 //     Reads a UserPromptSubmit hook payload from stdin, extracts the prompt,
 //     builds the skill catalog from the bundled extensions dir, routes the
 //     prompt, and writes the hook response to stdout.
+//     Set ENACT_EXTENSIONS_UPS_ROUTER=0 to disable this hook locally without
+//     removing the installed plugin.
 //
 // Output contract (Claude Code hooks):
 //   Match:    { continue: true, hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: <string> } }
@@ -960,13 +962,12 @@ if (command === "hook") {
   (async () => {
     if (subCommand === "session-start") {
       try {
-        const { computeOutdated } = await import("./lib/outdated.mjs");
-        const outdated = (computeOutdated() ?? []).filter((entry) => entry?.status === "outdated");
-        if (outdated.length > 0) {
-          const pairs = outdated.map((entry) => `${entry.name}/${entry.platform}`).join(", ");
-          process.stdout.write(
-            `[enact-extensions] ${outdated.length} plugin surface${outdated.length === 1 ? "" : "s"} outdated: ${pairs}. Run: enact-extensions update --all\n`,
-          );
+        const { handleSessionStartDrift } = await import("./lib/auto-update.mjs");
+        // Opt-in is the USER's: gate auto-apply on the env var they set.
+        const autoApply = !!process.env.ENACT_EXTENSIONS_AUTO_UPDATE;
+        const result = handleSessionStartDrift({ autoApply });
+        if (result.line) {
+          process.stdout.write(`${result.line}\n`);
         }
       } catch {
         // Fail-silent for session-start hooks.
@@ -974,6 +975,11 @@ if (command === "hook") {
       process.exit(0);
     }
 
+    if (process.env.ENACT_EXTENSIONS_UPS_ROUTER === "0") {
+      process.stdout.write(JSON.stringify({ continue: true }) + "\n");
+      process.exit(0);
+    }
+
     // Read stdin to get the hook payload JSON.
     let payload;
     try {

package/scripts/hooks/session-start-drift-check.mjs

@@ -5,12 +5,13 @@
  * Registered as a session-start hook for Claude, Codex, Cursor, and Enact.
  * Checks whether any installed enact-extensions plugins have drifted from
  * their canonical source (i.e. are outdated) and prints a concise advisory
- * if so.
+ * if so. When the user opts in via ENACT_EXTENSIONS_AUTO_UPDATE, the drifted
+ * surfaces are refreshed in place instead of merely advised.
  *
  * Design constraints:
  *   - FAIL-SILENT: wrap everything in try/catch; never throw; always exit 0.
- *   - FAST: imports computeOutdated directly (no subprocess) for speed.
- *   - READ-ONLY: never writes any state.
+ *   - FAST: imports the helper directly (no subprocess) for speed.
+ *   - READ-ONLY by default: only mutates state when the user opts into auto-apply.
  *   - NO OUTPUT on success (or error): only print when there are outdated entries.
  *   - DEPENDENCY-FREE: only node builtins + enact-extensions own modules.
  */
@@ -24,33 +25,22 @@ const REPO_ROOT = resolve(__dirname, "..", "..");
 
 try {
   // Dynamically import so any module-load failure is caught by the outer try/catch.
-  const { computeOutdated } = await import(join(REPO_ROOT, "scripts", "lib", "outdated.mjs"));
+  const { handleSessionStartDrift } = await import(join(REPO_ROOT, "scripts", "lib", "auto-update.mjs"));
 
-  let entries;
+  // Opt-in is the USER's: gate auto-apply on the env var they set.
+  const autoApply = !!process.env.ENACT_EXTENSIONS_AUTO_UPDATE;
+
+  let result;
   try {
-    entries = computeOutdated();
+    result = handleSessionStartDrift({ autoApply });
   } catch {
-    // computeOutdated threw (ledger missing, I/O error, etc.) — stay silent.
+    // Drift resolution threw (ledger missing, I/O error, etc.) — stay silent.
     process.exit(0);
   }
 
-  // Filter to only outdated entries (not fresh, not orphaned).
-  const outdated = (entries ?? []).filter((e) => e && e.status === "outdated");
-
-  if (outdated.length === 0) {
-    // Nothing to report.
-    process.exit(0);
+  if (result.line) {
+    process.stdout.write(`${result.line}\n`);
   }
-
-  // Build a concise list of (plugin, surface) pairs.
-  const pairs = outdated
-    .map((e) => `${e.name}/${e.platform}`)
-    .join(", ");
-
-  // Single advisory line to stdout.
-  process.stdout.write(
-    `[enact-extensions] ${outdated.length} plugin surface${outdated.length === 1 ? "" : "s"} outdated: ${pairs}. Run: enact-extensions update --all\n`,
-  );
 } catch {
   // Any top-level error (import failure, parse error, etc.) — silent exit 0.
 }

package/scripts/lib/auto-update.mjs

@@ -0,0 +1,75 @@
+/**
+ * auto-update.mjs — SessionStart drift resolution: advise by default, or
+ * auto-apply when opted in via ENACT_EXTENSIONS_AUTO_UPDATE.
+ *
+ * Single export:
+ *   handleSessionStartDrift({ autoApply, home, cwd }) → { outdated, applied, updated, line }
+ *
+ * Behaviour:
+ *   - Compute the outdated (drifted) surfaces from the ledger vs canonical source.
+ *   - No outdated surfaces           → { outdated: [], applied: false, line: null }.
+ *   - Outdated + autoApply=false     → advisory line (default; mutates nothing).
+ *   - Outdated + autoApply=true      → runUpdate({ all: true }); summary line naming
+ *                                      what was refreshed. If the refresh updated
+ *                                      nothing actionable (e.g. all orphaned), fall
+ *                                      back to the advisory line.
+ *
+ * The opt-in is the USER's: callers derive `autoApply` from
+ * process.env.ENACT_EXTENSIONS_AUTO_UPDATE. This module never reads env itself.
+ * Reuses computeOutdated + runUpdate; it adds no new install/refresh logic.
+ */
+
+import { computeOutdated } from "./outdated.mjs";
+import { runUpdate } from "./run-update.mjs";
+
+/** Format the "name/platform, ..." pair list for a set of entries. */
+function pairs(entries) {
+  return entries.map((e) => `${e.name}/${e.platform}`).join(", ");
+}
+
+/** The default advisory line (unchanged wording: names surfaces + manual command). */
+export function driftAdvisoryLine(outdated) {
+  return (
+    `[enact-extensions] ${outdated.length} plugin surface${outdated.length === 1 ? "" : "s"} ` +
+    `outdated: ${pairs(outdated)}. Run: enact-extensions update --all`
+  );
+}
+
+/** The auto-apply summary line, naming the surfaces that were refreshed. */
+export function autoUpdateSummaryLine(updated) {
+  return (
+    `[enact-extensions] auto-updated ${updated.length} plugin surface${updated.length === 1 ? "" : "s"}: ` +
+    `${pairs(updated)}`
+  );
+}
+
+/**
+ * Resolve SessionStart drift: advise by default, or auto-apply when opted in.
+ *
+ * @param {object} [opts]
+ * @param {boolean} [opts.autoApply] — when true, refresh outdated surfaces in place.
+ * @param {string}  [opts.home]      — ledger home override (defaults to os.homedir()).
+ * @param {string}  [opts.cwd]       — canonical-source resolution dir (defaults to cwd).
+ * @returns {{ outdated: object[], applied: boolean, updated: object[], line: string|null }}
+ */
+export function handleSessionStartDrift({ autoApply, home, cwd } = {}) {
+  const outdated = (computeOutdated({ home, cwd }) ?? []).filter(
+    (e) => e && e.status === "outdated",
+  );
+
+  if (outdated.length === 0) {
+    return { outdated, applied: false, updated: [], line: null };
+  }
+
+  if (autoApply) {
+    const summary = runUpdate({ all: true, home, cwd });
+    const updated = summary?.updated ?? [];
+    if (updated.length === 0) {
+      // Nothing actionable was refreshed (e.g. orphaned source) — advise instead.
+      return { outdated, applied: false, updated, line: driftAdvisoryLine(outdated) };
+    }
+    return { outdated, applied: true, updated, line: autoUpdateSummaryLine(updated) };
+  }
+
+  return { outdated, applied: false, updated: [], line: driftAdvisoryLine(outdated) };
+}

package/scripts/lib/postinstall-offer.mjs

@@ -0,0 +1,83 @@
+/**
+ * postinstall-offer.mjs — interactive drift-refresh offer shown at postinstall.
+ *
+ * Exports ONE function:
+ *   offerDriftRefresh({ isTTY, computeOutdatedFn, promptYesNo, runUpdateFn, write })
+ *
+ * Contract:
+ *   - non-TTY                → silent; return { offered: false, updated: false }
+ *   - TTY + zero outdated    → silent; return { offered: false, updated: false }
+ *   - TTY + outdated entries → write summary, then:
+ *       - autoYes set → apply WITHOUT prompting; return { offered: true, updated: true }
+ *       - else prompt:
+ *           - user yes → runUpdateFn({ all: true }); return { offered: true, updated: true }
+ *           - user no  → write manual command hint; return { offered: true, updated: false }
+ *   - Any error              → fail-silent; return { offered: false, updated: false }
+ *                              (except: if runUpdateFn throws after a yes answer,
+ *                               return { offered: true, updated: false })
+ *
+ * `autoYes` is the USER's opt-in (callers derive it from
+ * process.env.ENACT_EXTENSIONS_AUTO_UPDATE); this module never reads env itself.
+ */
+
+/**
+ * Offer the user a drift refresh if any installed plugins are outdated.
+ *
+ * @param {object} opts
+ * @param {boolean} opts.isTTY - whether the terminal is interactive
+ * @param {boolean} [opts.autoYes] - when true, apply without prompting (user opt-in)
+ * @param {() => Promise<import("./outdated.mjs").OutdatedEntry[]>} opts.computeOutdatedFn
+ * @param {(question: string) => Promise<boolean>} opts.promptYesNo
+ * @param {(opts: { all: boolean }) => void | Promise<void>} opts.runUpdateFn
+ * @param {(msg: string) => void} opts.write
+ * @returns {Promise<{ offered: boolean, updated: boolean }>}
+ */
+export async function offerDriftRefresh({ isTTY, autoYes, computeOutdatedFn, promptYesNo, runUpdateFn, write }) {
+  try {
+    // Non-interactive: exit immediately without any work.
+    if (!isTTY) {
+      return { offered: false, updated: false };
+    }
+
+    // Compute outdated entries and filter to status === "outdated" only.
+    const entries = await computeOutdatedFn();
+    const outdated = entries.filter((e) => e.status === "outdated");
+
+    // Nothing to do.
+    if (outdated.length === 0) {
+      return { offered: false, updated: false };
+    }
+
+    // Write summary line listing the outdated name/platform pairs.
+    const pairs = outdated.map((e) => `${e.name}/${e.platform}`).join(", ");
+    write(`\nenact-extensions: ${outdated.length} plugin(s) have drifted from their source: ${pairs}\n`);
+
+    // Opt-in auto-apply: skip the prompt and refresh directly.
+    if (autoYes) {
+      try {
+        await runUpdateFn({ all: true });
+        return { offered: true, updated: true };
+      } catch {
+        return { offered: true, updated: false };
+      }
+    }
+
+    // Prompt user.
+    const yes = await promptYesNo("Update all now? [Y/n] ");
+
+    if (yes) {
+      try {
+        await runUpdateFn({ all: true });
+        return { offered: true, updated: true };
+      } catch {
+        return { offered: true, updated: false };
+      }
+    } else {
+      write(`Run \`enact-extensions update --all\` to update manually.\n`);
+      return { offered: true, updated: false };
+    }
+  } catch {
+    // Fail-silent: never throw from postinstall-related code.
+    return { offered: false, updated: false };
+  }
+}

package/scripts/lib/ups-router.mjs

@@ -1,8 +1,8 @@
 /**
  * ups-router.mjs — pure, testable module for the UserPromptSubmit keyword-router.
  *
- * Discovers plugin bundles and their skills, extracts trigger keywords from
- * SKILL.md frontmatter, and routes a user prompt to matching skills.
+ * Discovers plugin bundles and their skills, extracts explicit trigger phrases
+ * from SKILL.md frontmatter, and routes a user prompt to matching skills.
  *
  * Two exports:
  *   buildSkillCatalog(extensionsDir)  → CatalogEntry[]
@@ -147,49 +147,11 @@ function extractExplicitTriggers(description) {
   return quoted;
 }
 
-/**
- * Derive salient keywords from a skill's description text.
- *
- * Conservative: only extracts tokens that are plausibly skill identifiers:
- *   - Hyphenated compound tokens (e.g. "contract-runner", "test-driven")
- *   - $skill-name mentions (e.g. "$loop", "$tdd")
- *   - Quoted short phrases other than the "Triggers on" section
- *   - Unquoted tokens that are longer (>=6 chars) and not stop-words
- *
- * @param {string} description
- * @returns {string[]}
- */
-function descriptionKeywords(description) {
-  const tokens = new Set();
-
-  // $skill mentions: "$foo", "$foo-bar"
-  const dollarRe = /\$([a-z][a-z0-9-]+)/gi;
-  let m;
-  while ((m = dollarRe.exec(description)) !== null) {
-    tokens.add(m[1].toLowerCase());
-  }
-
-  // Hyphenated compound tokens: at least two segments, each 2+ chars
-  const hyphenRe = /\b([a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)+)\b/gi;
-  while ((m = hyphenRe.exec(description)) !== null) {
-    const tok = m[1].toLowerCase();
-    if (!isStopWord(tok)) tokens.add(tok);
-  }
-
-  // Longer bare words (>=6 chars) that don't look like common English prose.
-  const longWordRe = /\b([a-z]{6,})\b/gi;
-  while ((m = longWordRe.exec(description)) !== null) {
-    const tok = m[1].toLowerCase();
-    if (!isStopWord(tok)) tokens.add(tok);
-  }
-
-  return [...tokens];
-}
-
 /**
  * Derive the full keyword set for a single skill.
- * Priority: explicit "Triggers on" > skill name > salient description terms.
- * Deduplicates and excludes stop-words.
+ * Only explicit `Triggers on "..."` phrases and the skill name are used.
+ * Do not mine arbitrary words from descriptions; that makes everyday prompts
+ * like "change this contract" trigger unrelated skill hints.
  *
  * @param {string} skillName
  * @param {string|null} description
@@ -208,8 +170,6 @@ function deriveKeywords(skillName, description) {
   if (description) {
     // Explicit triggers have highest priority.
     for (const t of extractExplicitTriggers(description)) push(t);
-    // Salient terms from the description.
-    for (const t of descriptionKeywords(description)) push(t);
   }
 
   return [...seen];

package/scripts/postinstall.mjs

@@ -48,6 +48,44 @@ try {
     stdio: "inherit",
     env: { ...process.env },
   });
+
+  // Offer a drift refresh if any installed plugins are outdated.
+  const { offerDriftRefresh } = await import("./lib/postinstall-offer.mjs");
+  const { computeOutdated } = await import("./lib/outdated.mjs");
+  const { runUpdate } = await import("./lib/run-update.mjs");
+  const { createInterface } = await import("node:readline");
+
+  /**
+   * promptYesNo — asks a yes/no question on stdin/stdout.
+   * Default is YES: empty input / "y" / "yes" (case-insensitive) → true.
+   * EOF (Ctrl-D) resolves as false (decline) via the 'close' event so the
+   * script can never hang waiting for a promise that will never settle.
+   * @param {string} question
+   * @returns {Promise<boolean>}
+   */
+  function promptYesNo(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      // EOF / Ctrl-D fires 'close' before the question callback — treat as decline.
+      rl.once("close", () => resolve(false));
+      rl.question(question, (answer) => {
+        rl.close();
+        const t = (answer ?? "").trim().toLowerCase();
+        resolve(t === "" || t === "y" || t === "yes");
+      });
+    });
+  }
+
+  await offerDriftRefresh({
+    isTTY: true,
+    // User opt-in: ENACT_EXTENSIONS_AUTO_UPDATE=1 applies drift refreshes without prompting.
+    autoYes: !!env.ENACT_EXTENSIONS_AUTO_UPDATE,
+    computeOutdatedFn: () => computeOutdated(),
+    runUpdateFn: (opts) => runUpdate(opts),
+    write: (s) => process.stdout.write(s),
+    promptYesNo,
+  });
+
   process.exit(0);
 } catch {
   // CRITICAL: never let an error propagate from postinstall.