@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor-skills.ts

@@ -0,0 +1,283 @@
+/**
+ * Bundled skill content.
+ *
+ * Files under `vendor/skills/` are vendored from `galaxyproject/agentic-plugins`
+ * at a pinned commit by `scripts/sync-skills.mjs` and ship inside the package --
+ * both the npm CLI (`files: ["extensions/", ...]`) and the Orbit installers
+ * (forge's `ORBIT_BUNDLE_FILES` includes `extensions`) pick them up with no
+ * packaging change. That is deliberate: the guidance has to be available
+ * offline, at a version we reviewed, with no runtime dependency on GitHub.
+ *
+ * Three kinds of content live here. The galaxy-skills mirror backs the
+ * configured repo of the same name: its generated `_catalog.json` is what the
+ * system-prompt router renders, and `skills_fetch` reads it from disk. The
+ * Foundry casts back nothing configured and never enter the router -- nothing in
+ * them is ambient guidance the model needs to know exists up front, so a hint
+ * names the exact file at the moment it becomes relevant (see
+ * `invocation-failure-hint.ts`). Orbit's staging skills come from `skills/` in
+ * this repo rather than from agentic-plugins: skills Orbit needs before they
+ * have a permanent home, each naming where it should move. They are routed
+ * under the reserved `orbit` repo.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isBundledSkillRepo } from "../../shared/orbit-config.js";
+import type { SkillEntry } from "./skills-discovery";
+
+/** Reserved repo name for `skills_fetch({ repo: "foundry" })`. */
+export const VENDOR_REPO_NAME = "foundry";
+
+/** Reserved repo name for Orbit's staging skills, `skills_fetch({ repo: "orbit" })`. */
+export const STAGING_REPO_NAME = "orbit";
+
+/**
+ * Names `skills_fetch` answers from the package without any configured repo
+ * behind them. A configured repo of the same name still wins, so an explicitly
+ * chosen repo is never silently answered from the package.
+ */
+const RESERVED_REPOS: ReadonlySet<string> = new Set([VENDOR_REPO_NAME, STAGING_REPO_NAME]);
+
+export function isReservedRepo(name: unknown): name is string {
+  return typeof name === "string" && RESERVED_REPOS.has(name);
+}
+
+export interface VendorManifestEntry {
+  target: string;
+  plugin: string;
+  source: string;
+  bytes: number;
+  sha256: string;
+  why?: string;
+}
+
+export interface VendorManifestPlugin {
+  plugin: string;
+  /** "local" for a plugin synced from this repo; absent for agentic-plugins. */
+  source?: "local";
+  /** The repo-relative source directory of a local plugin. */
+  dir?: string;
+  as: string;
+  repo?: string;
+  /** "catalog" puts this plugin's skills in the prompt router; "never" keeps them out. */
+  router: string;
+}
+
+export interface VendorManifest {
+  repo: string;
+  /** Commit, not tag: tags move, and "what did we ship" has to stay answerable. */
+  commit: string;
+  /** A label for the commit, null while the pin is ahead of the newest tag. */
+  tag?: string | null;
+  commitDate?: string;
+  plugins?: VendorManifestPlugin[];
+  files: VendorManifestEntry[];
+}
+
+/** Re-exported so brain-side callers do not reach across into shared/ directly. */
+export { isBundledSkillRepo as isBundledRepo };
+
+/** The vendored tree handed over by a shell that cannot read the package from disk. */
+export interface VendorSkillsSource {
+  /** Parsed `_catalog.json`; filtered here exactly as the file is. */
+  catalog: unknown;
+  /** Parsed `_manifest.json`; checked here exactly as the file is. */
+  manifest: unknown;
+  /** Text of one manifest target, or null when the tree has no such file. */
+  read(target: string): string | null;
+}
+
+let installedSource: VendorSkillsSource | null = null;
+
+export function setVendorSkillsSource(next: VendorSkillsSource | null): void {
+  installedSource = next;
+}
+
+function catalogFrom(data: unknown): Record<string, SkillEntry[]> | null {
+  if (!data || typeof data !== "object") return null;
+  const out: Record<string, SkillEntry[]> = {};
+  for (const [key, value] of Object.entries(data)) {
+    // The file's own $comment.
+    if (key.startsWith("$")) continue;
+    if (Array.isArray(value)) out[key] = value as SkillEntry[];
+  }
+  return out;
+}
+
+/** The generated router catalog, keyed by configured repo name. */
+export function readBundledCatalog(): Record<string, SkillEntry[]> | null {
+  if (installedSource) return catalogFrom(installedSource.catalog);
+  try {
+    const raw = fs.readFileSync(path.join(vendorSkillsDir(), "_catalog.json"), "utf-8");
+    return catalogFrom(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether the manifest says this exact target belongs to the plugin backing
+ * `repoName`. Ownership, not a path prefix: two plugins can share a prefix, and
+ * one of them writes at the root. Reading is scoped by it so a repo answers for
+ * its own files and nothing else -- the same path has to mean the same thing
+ * whether the repo is read from the package or fetched from GitHub, and a path
+ * that 404s live must not quietly resolve here.
+ */
+function ownedTargets(repoName: string): string[] {
+  const manifest = readVendorManifest();
+  const plugin = manifest?.plugins?.find((p) => p.repo === repoName)?.plugin;
+  if (!plugin) return [];
+  return (manifest?.files ?? []).filter((f) => f.plugin === plugin).map((f) => f.target);
+}
+
+/**
+ * Read one file for a bundled repo. Never touches the network, so a miss lists
+ * that repo's own skills rather than every file in the package.
+ */
+export function readBundledRepoFile(repo: { name: string }, rawPath: string): VendorReadResult {
+  const owned = ownedTargets(repo.name);
+  // What to offer on a miss. A repo in the router has a catalog and its skills
+  // are the useful answer; a repo that is deliberately out of the router has
+  // none, and offering nothing is how the reserved reference set used to
+  // dead-end on the relative paths its own SKILL.md prints.
+  const catalog = (readBundledCatalog()?.[repo.name] ?? []).map((s) => s.path);
+  const available = catalog.length ? catalog : summarise(owned);
+  const clean = (typeof rawPath === "string" ? rawPath : "")
+    .replace(/^\/+/, "")
+    .replace(/\\/g, "/");
+  const target = LEGACY_FLAT_PATHS[clean] ?? clean;
+  if (!owned.includes(target)) {
+    return { ok: false, error: `No file "${rawPath}" in ${repo.name}`, available };
+  }
+  const res = readVendoredSkill(target);
+  return res.ok ? res : { ...res, available };
+}
+
+/**
+ * Every entry point, plus a count of what sits under each. Printing 149 paths
+ * at a model that mistyped one is not help; the SKILL.md files are where it
+ * should start, and the count tells it the references exist.
+ */
+function summarise(targets: string[]): string[] {
+  const entries = targets.filter((t) => t.endsWith("SKILL.md")).sort();
+  const rest = targets.length - entries.length;
+  return rest > 0 ? [...entries, `(and ${rest} reference files alongside these)`] : entries;
+}
+
+/** True when the package actually holds any content for this repo name. */
+export function hasBundledContent(repoName: string): boolean {
+  return ownedTargets(repoName).length > 0;
+}
+
+/** Absolute path to the vendored skills directory (sibling of this module). */
+export function vendorSkillsDir(): string {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), "vendor", "skills");
+}
+
+/**
+ * Resolve a vendored file path to an absolute path inside the vendor dir, or
+ * null if it escapes. A leading slash is stripped and a backslash is read as a
+ * separator, the way the GitHub path does it; a literal `..` anywhere is
+ * rejected outright rather than resolved, so percent-encoded traversal never
+ * gets a chance to become one.
+ */
+export function resolveVendorPath(rawPath: string): string | null {
+  const clean = rawPath.replace(/^\/+/, "").replace(/\\/g, "/");
+  if (!clean || clean.includes("..")) return null;
+  const dir = vendorSkillsDir();
+  const abs = path.resolve(dir, clean);
+  // path.resolve collapses traversal; confirm the result is still contained.
+  // The trailing separator stops `/vendor/skillsX` from passing as `/vendor/skills`.
+  if (abs !== dir && !abs.startsWith(dir + path.sep)) return null;
+  return abs;
+}
+
+function manifestFrom(data: unknown): VendorManifest | null {
+  if (!data || typeof data !== "object" || !Array.isArray((data as VendorManifest).files)) {
+    return null;
+  }
+  return data as VendorManifest;
+}
+
+let warnedSourceManifest = false;
+
+export function readVendorManifest(): VendorManifest | null {
+  if (installedSource) {
+    const manifest = manifestFrom(installedSource.manifest);
+    // Without the manifest no repo has bundled content and skills_fetch goes to
+    // the network instead; a half-built source should say so once, not hide.
+    if (!manifest && !warnedSourceManifest) {
+      warnedSourceManifest = true;
+      console.warn("[skills] the vendor skills source has no manifest; bundled skills are off");
+    }
+    return manifest;
+  }
+  try {
+    const raw = fs.readFileSync(path.join(vendorSkillsDir(), "_manifest.json"), "utf-8");
+    return manifestFrom(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Bare names the vendor tree used before targets mirrored their upstream path.
+ * A session resumed across that change still carries them in its transcript --
+ * two were named in a failure hint, and the third was listed to the model every
+ * time a fetch missed. They keep resolving for one release; delete them once
+ * 0.8.0 has shipped.
+ *
+ * Null prototype on purpose. `path` reaches here straight from the model, and a
+ * plain object answers "constructor" with a function, which is not a path.
+ */
+const LEGACY_FLAT_PATHS: Record<string, string> = Object.assign(Object.create(null), {
+  "galaxy-collection-semantics.yml":
+    "debug-galaxy-workflow-output/references/notes/galaxy-collection-semantics.yml",
+  "galaxy-tool-job-failure-reference.md":
+    "debug-galaxy-workflow-output/references/notes/galaxy-tool-job-failure-reference.md",
+  "galaxy-workflow-invocation-failure-reference.md":
+    "debug-galaxy-workflow-output/references/notes/galaxy-workflow-invocation-failure-reference.md",
+});
+
+export type VendorReadResult =
+  { ok: true; text: string } | { ok: false; error: string; available: string[] };
+
+/** Read one vendored file. Never touches the network. */
+export function readVendoredSkill(rawPath: string): VendorReadResult {
+  const available = () => (readVendorManifest()?.files ?? []).map((f) => f.target);
+  if (typeof rawPath !== "string") {
+    return { ok: false, error: `Invalid vendored skill path`, available: available() };
+  }
+  const target = LEGACY_FLAT_PATHS[rawPath] ?? rawPath;
+  if (installedSource) {
+    // The string-level rules resolveVendorPath applies before it touches the disk.
+    const clean = target.replace(/^\/+/, "").replace(/\\/g, "/");
+    if (!clean || clean.includes("..")) {
+      return {
+        ok: false,
+        error: `Invalid vendored skill path "${rawPath}"`,
+        available: available(),
+      };
+    }
+    const text = installedSource.read(clean);
+    return text === null
+      ? { ok: false, error: `No vendored file "${rawPath}"`, available: available() }
+      : { ok: true, text };
+  }
+  const abs = resolveVendorPath(target);
+  if (!abs) {
+    return { ok: false, error: `Invalid vendored skill path "${rawPath}"`, available: available() };
+  }
+  try {
+    // lstat, not stat: the containment check above is about the path string, and
+    // a symlink planted in the package would read straight past it. Nothing we
+    // vendor is a link, and the sync refuses to write one.
+    if (!fs.lstatSync(abs).isFile()) {
+      return { ok: false, error: `Not a vendored file "${rawPath}"`, available: available() };
+    }
+    return { ok: true, text: fs.readFileSync(abs, "utf-8") };
+  } catch {
+    return { ok: false, error: `No vendored file "${rawPath}"`, available: available() };
+  }
+}

package/extensions/orbit/workspace-state-dir.ts

@@ -0,0 +1,46 @@
+/**
+ * The per-analysis state dir (`<cwd>/.loom/` today, `<cwd>/.orbit/` after the
+ * rename). A workspace keeps whichever one it already has -- the conda env
+ * under it has hardcoded prefixes and cannot be moved -- so the active name is
+ * resolved per workspace, while the exec-guard protects every name in
+ * WORKSPACE_STATE_DIR_NAMES no matter which one is active.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const ORBIT_STATE_DIR_NAME = ".orbit";
+export const LEGACY_STATE_DIR_NAME = ".loom";
+
+export type WorkspaceStateDirName = typeof ORBIT_STATE_DIR_NAME | typeof LEGACY_STATE_DIR_NAME;
+
+/** Every spelling the security code treats as Orbit state, in resolution order. */
+export const WORKSPACE_STATE_DIR_NAMES: readonly WorkspaceStateDirName[] = [
+  ORBIT_STATE_DIR_NAME,
+  LEGACY_STATE_DIR_NAME,
+];
+
+// What a workspace with neither dir gets. Deliberately still `.loom` in the
+// rename release: registry.ts, galaxy-provenance and submission capture
+// hardcode `.loom/...` and persist relative paths, so flipping this alone would
+// split a workspace's state in two. Route those through the resolver first.
+export const NEW_WORKSPACE_STATE_DIR_NAME: WorkspaceStateDirName = LEGACY_STATE_DIR_NAME;
+
+function isDir(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** `.orbit` if the workspace has one, else `.loom` if it has that, else the default. */
+export function resolveWorkspaceStateDirName(cwd: string): WorkspaceStateDirName {
+  for (const name of WORKSPACE_STATE_DIR_NAMES) {
+    if (isDir(path.join(cwd, name))) return name;
+  }
+  return NEW_WORKSPACE_STATE_DIR_NAME;
+}
+
+export function resolveWorkspaceStateDir(cwd: string): string {
+  return path.join(cwd, resolveWorkspaceStateDirName(cwd));
+}

package/extensions/orbit-handoff/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Orbit hand-off — terminal-CLI shell glue, deliberately NOT part of the Orbit
+ * core.
+ *
+ * All Orbit-specific knowledge (install paths, bundle layout, the `--cwd`
+ * launch protocol, the release URL) lives here so `extensions/orbit/` stays
+ * shell-neutral. bin/orbit.js loads this extension alongside the brain; because
+ * the same bin/orbit.js also runs as Orbit's embedded brain, the handler no-ops
+ * when it's already inside Orbit rather than handing the session off to itself.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { findOrbit, launchOrbit } from "./orbit-launcher";
+import { isDesktopShell } from "../../shared/orbit-env.js";
+
+const RELEASE_URL = "https://github.com/galaxyproject/orbit/releases";
+
+export async function handleOrbitHandoff(
+  _args: string | undefined,
+  ctx: ExtensionContext,
+): Promise<void> {
+  // Already inside Orbit: there's nothing to hand off to, and shutting down
+  // here would just tear the embedded session down. No-op with a note.
+  if (isDesktopShell()) {
+    ctx.ui.notify("You're already in Orbit -- nothing to hand off to.", "info");
+    return;
+  }
+
+  const orbitPath = findOrbit();
+  if (!orbitPath) {
+    ctx.ui.notify(
+      `Orbit is not installed. Grab a release for your platform from ${RELEASE_URL}, ` +
+        `then run /desktop again. (If Orbit is installed in a non-standard location, ` +
+        `set ORBIT_DESKTOP_BIN to the binary path.)`,
+      "warning",
+    );
+    return;
+  }
+
+  try {
+    const result = launchOrbit(orbitPath, ctx.cwd);
+    // We deliberately do NOT auto-close the CLI. ctx.shutdown() only sets a flag
+    // that pi's interactive mode reads at agent_end, so a slash command can't
+    // trigger a graceful exit (terminal restore + the session_shutdown lifecycle),
+    // and a bare process.exit() would leave the terminal in raw mode. So we launch
+    // and ask the user to close the CLI themselves. (Orbit's embedded RPC brain
+    // honors shutdown-from-command; the terminal CLI doesn't yet -- once it does,
+    // this can move the launch into a session_shutdown handler and exit cleanly.)
+    ctx.ui.notify(
+      `Orbit is opening on ${ctx.cwd} (pid ${result.pid ?? "?"}). Your work continues there -- ` +
+        `press Ctrl-D or type /exit to close this CLI so both don't write the same notebook.`,
+      "info",
+    );
+  } catch (err) {
+    ctx.ui.notify(
+      `Failed to launch Orbit at ${orbitPath}: ${err instanceof Error ? err.message : String(err)}`,
+      "error",
+    );
+  }
+}
+
+export default function orbitHandoffExtension(pi: ExtensionAPI): void {
+  pi.registerCommand("desktop", {
+    description: "Hand off this session to the Orbit desktop app",
+    handler: handleOrbitHandoff,
+  });
+  // The command was /orbit while the CLI was called Loom. Kept as an alias so
+  // muscle memory and old docs keep working; drop it in the sunset release.
+  pi.registerCommand("orbit", {
+    description: "Alias of /desktop",
+    handler: handleOrbitHandoff,
+  });
+}

package/extensions/orbit-handoff/orbit-launcher.ts

@@ -0,0 +1,142 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { readEnv } from "../../shared/orbit-env.js";
+
+/**
+ * Dependencies findOrbit() reads from the environment. Threaded as a
+ * parameter so tests can pass a synthetic platform/env/fs without fighting
+ * vi.stubGlobal on process (some code paths capture process.platform at
+ * module load and never re-read it).
+ */
+export interface FindOrbitDeps {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+  homedir: string;
+  existsSync: (p: string) => boolean;
+  /** Optional so synthetic deps default to "every path is its own target". */
+  realpathSync?: (p: string) => string;
+}
+
+function realDeps(): FindOrbitDeps {
+  return {
+    platform: process.platform,
+    env: process.env,
+    homedir: os.homedir(),
+    existsSync: fs.existsSync,
+    realpathSync: fs.realpathSync,
+  };
+}
+
+/**
+ * True when a candidate resolves to a Node CLI entry point rather than the
+ * Electron binary. Once the CLI is published as `orbit`, a global npm install
+ * under /usr or /usr/local puts its shim at exactly the path the old desktop
+ * .deb used, and spawning that would just start another terminal session.
+ */
+export function isNodeCliShim(resolved: string): boolean {
+  const p = resolved.replace(/\\/g, "/");
+  return (
+    /\.(c|m)?js$/i.test(p) ||
+    p.includes("/node_modules/.bin/") ||
+    p.includes("/node_modules/@galaxyproject/")
+  );
+}
+
+function acceptable(candidate: string, deps: FindOrbitDeps): boolean {
+  if (!deps.existsSync(candidate)) return false;
+  let resolved: string;
+  try {
+    resolved = deps.realpathSync ? deps.realpathSync(candidate) : candidate;
+  } catch {
+    return false;
+  }
+  return !isNodeCliShim(resolved);
+}
+
+/**
+ * Locate an installed Orbit binary on disk.
+ *
+ * Priority:
+ *   1. $ORBIT_DESKTOP_BIN, or its older alias $ORBIT_BIN (escape hatch for
+ *      non-standard installs / dev builds).
+ *   2. Platform-conventional install paths (Applications, /usr/bin, etc.).
+ *
+ * Any candidate that resolves to a Node CLI shim is skipped -- see isNodeCliShim.
+ *
+ * Returns the absolute path or null if Orbit isn't installed.
+ */
+export function findOrbit(deps: FindOrbitDeps = realDeps()): string | null {
+  // readEnv prefers ORBIT_DESKTOP_BIN over the older ORBIT_BIN alias.
+  const override = readEnv("DESKTOP_BIN", deps.env);
+  if (override) {
+    return acceptable(override, deps) ? override : null;
+  }
+  if (deps.platform === "darwin") {
+    // forge.config.ts sets executableName "Orbit" on darwin, which
+    // CFBundleExecutable inherits, so the real binary is capital-O. The
+    // lowercase pair covers bundles built before that was the case.
+    const candidates = [
+      "/Applications/Orbit.app/Contents/MacOS/Orbit",
+      `${deps.homedir}/Applications/Orbit.app/Contents/MacOS/Orbit`,
+      "/Applications/Orbit.app/Contents/MacOS/orbit",
+      `${deps.homedir}/Applications/Orbit.app/Contents/MacOS/orbit`,
+    ];
+    for (const c of candidates) if (acceptable(c, deps)) return c;
+    return null;
+  }
+  if (deps.platform === "linux") {
+    // The desktop's Linux executable is moving to `orbit-desktop` so the CLI
+    // can own `orbit` on PATH. electron-installer-debian/redhat install the app
+    // under /usr/lib/<package name>/ and symlink /usr/bin/<package name> to it,
+    // so the lib paths catch a package whose name hasn't changed yet.
+    const candidates = [
+      `${deps.homedir}/.local/bin/Orbit.AppImage`,
+      "/usr/bin/orbit-desktop",
+      "/usr/local/bin/orbit-desktop",
+      "/usr/lib/orbit-desktop/orbit-desktop",
+      "/usr/lib/orbit/orbit-desktop",
+      "/usr/bin/orbit",
+      "/usr/local/bin/orbit",
+      `${deps.homedir}/Applications/Orbit.AppImage`,
+    ];
+    for (const c of candidates) if (acceptable(c, deps)) return c;
+    return null;
+  }
+  if (deps.platform === "win32") {
+    const localAppData = deps.env.LOCALAPPDATA;
+    if (!localAppData) return null;
+    const candidates = [
+      `${localAppData}\\orbit\\Orbit.exe`,
+      `${localAppData}\\Programs\\orbit\\Orbit.exe`,
+    ];
+    for (const c of candidates) if (acceptable(c, deps)) return c;
+    return null;
+  }
+  return null;
+}
+
+export interface LaunchResult {
+  pid: number | undefined;
+}
+
+/**
+ * Launch Orbit detached with --cwd <cwd>. Returns immediately. The caller
+ * is responsible for the rest of session-shutdown -- launchOrbit does not
+ * wait for Orbit to start.
+ */
+export function launchOrbit(orbitPath: string, cwd: string): LaunchResult {
+  const child = spawn(orbitPath, ["--cwd", cwd], {
+    detached: true,
+    stdio: "ignore",
+  });
+  // spawn reports a failed launch (ENOENT, not executable, damaged bundle) via
+  // an async 'error' event, not a throw -- and on an unref'd child with no
+  // listener that surfaces as an unhandled error. Best-effort note to stderr;
+  // by now the CLI is already tearing down, so there's nothing to recover.
+  child.on("error", (err) => {
+    process.stderr.write(`orbit launch failed: ${err.message}\n`);
+  });
+  child.unref();
+  return { pid: child.pid };
+}

package/extensions/whats-new/index.ts

@@ -0,0 +1,98 @@
+/**
+ * What's-new notice -- CLI-shell glue, NOT part of the loom brain.
+ *
+ * On the first session after an upgrade, surfaces the running version's curated
+ * highlights (from the shipped CHANGELOG.md) once via ctx.ui.notify, then stamps
+ * a sidecar so it shows once per upgrade. Also registers /whatsnew to re-view on
+ * demand. No-ops inside Orbit, which owns its own what's-new banner. Lives here,
+ * alongside cli-update, so extensions/orbit/ stays shell-neutral.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+// bin/ and shared/ are siblings of extensions/.
+import { getOrbitVersion } from "../../bin/update-check.js";
+import {
+  parseChangelog,
+  decideWhatsNew,
+  selectEntries,
+  formatHighlightsText,
+  releaseUrlFor,
+} from "../../shared/whats-new.js";
+import { isDesktopShell } from "../../shared/orbit-env.js";
+import { resolveStateDir } from "../../shared/state-dir.js";
+
+// This file lives at <pkg>/extensions/whats-new/index.ts, so the package root is two up.
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const CHANGELOG_PATH = path.join(PKG_ROOT, "CHANGELOG.md");
+const seenFile = () => path.join(resolveStateDir(), "whats-new-seen.json");
+
+function loadEntries() {
+  try {
+    return parseChangelog(fs.readFileSync(CHANGELOG_PATH, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+
+function readSeen(): string | undefined {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(seenFile(), "utf-8"));
+    return typeof parsed?.version === "string" ? parsed.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeSeen(version: string): void {
+  try {
+    const file = seenFile();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify({ version }));
+  } catch {}
+}
+
+export default function whatsNewExtension(pi: ExtensionAPI): void {
+  let shown = false;
+  pi.on("before_agent_start", async (_event, ctx: ExtensionContext) => {
+    if (shown) return;
+    shown = true;
+    // Orbit owns its own what's-new banner for the embedded brain.
+    if (isDesktopShell()) return;
+    try {
+      const running = getOrbitVersion();
+      const decision = decideWhatsNew(loadEntries(), readSeen(), running, "latest");
+      if (decision.entries.length) {
+        const body = formatHighlightsText(decision.entries);
+        ctx.ui.notify(`${body}\n  Full notes: /whatsnew  or  ${releaseUrlFor(running)}`, "info");
+      }
+      // Stamp even with no entries: silently advances the sidecar for versions
+      // without Highlights so we don't re-check on every later launch.
+      if (decision.stamp) writeSeen(decision.stamp);
+    } catch {
+      // A notice must never break a session.
+    }
+  });
+
+  pi.registerCommand("whatsnew", {
+    description: "Show what's new in this version of loom",
+    handler: async (_args: string | undefined, ctx: ExtensionContext) => {
+      try {
+        const running = getOrbitVersion();
+        const entries = selectEntries(loadEntries(), undefined, running, "latest");
+        if (entries.length) {
+          ctx.ui.notify(
+            `${formatHighlightsText(entries)}\n  Full notes: ${releaseUrlFor(running)}`,
+            "info",
+          );
+        } else {
+          ctx.ui.notify(`No what's-new notes for loom ${running}.`, "info");
+        }
+      } catch {
+        ctx.ui.notify("Could not load what's-new notes.", "warning");
+      }
+    },
+  });
+}

package/lessons/LICENSE

@@ -0,0 +1,17 @@
+Creative Commons Attribution 4.0 International (CC BY 4.0)
+
+The lesson corpus in this directory -- every <namespace>/<slug>.md file and the
+snapshot.json built from them -- is licensed under the Creative Commons
+Attribution 4.0 International License. The rest of the Orbit repository is MIT;
+this directory is the exception, so that any project can reuse the lessons with
+attribution and nothing more.
+
+SPDX-License-Identifier: CC-BY-4.0
+Full legal code:  https://creativecommons.org/licenses/by/4.0/legalcode
+Plain-language summary:  https://creativecommons.org/licenses/by/4.0/
+
+Attribute as: "Orbit lesson bank, galaxyproject/orbit, CC BY 4.0", with a link to
+the lesson's page or to the repository.
+
+validate.mjs and build-snapshot.mjs in this directory are code, not corpus, and
+stay under the repository's MIT licence.