@sous-io/sous 0.2.30 → 0.2.32

package/README.md

@@ -40,6 +40,18 @@ output. When the two versions differ, one line on standard error names the versi
 to; `--verbose` announces every hand-off and adds where both installs are. Set
 `SOUS_NO_DELEGATE=1` to run the copy you invoked instead.
 
+To update, run `sous update`. It updates the global install, the project's own install, or both
+(whichever this directory has), through the package manager that installed each one (npm, pnpm or
+Yarn), and asks before each one. By default each install moves to the newest version in its current
+major; `--major` goes past it, `--version <version|range|tag>` picks one (a downgrade included),
+`--global` and `--project` narrow the run, `--yes` answers every question and `--dry-run` only
+prints the plan. After a project update, the new copy builds the project, so its lockfile moves to
+the new version too.
+
+```bash
+sous update --dry-run     # show what would be installed where, and install nothing
+```
+
 Or run it from a clone (useful when developing sous itself):
 
 ```bash

package/docs/markdown/README.md

@@ -59,6 +59,58 @@ $ SOUS_NO_DELEGATE=1 sous --version
 v0.3.0
 ```
 
+### Updating
+
+`sous update` moves each copy of sous to a newer version (or one you choose) through the package
+manager that installed it, so you never need to remember which one that was or its syntax:
+
+- **Outside a project**, or in a project that does not install sous, it updates the global install.
+  Each of npm, pnpm and Yarn classic is asked where its global packages live, and every global
+  install found is updated with its own manager (`npm i -g`, `pnpm add -g`, `yarn global add`).
+- **In a project that installs sous**, it updates the project's install with the project's own
+  manager (`npm i -D -E`, `pnpm add -D -E`, `yarn add -D -E`), which pins the exact version in
+  `package.json` and updates the lockfile. A dependency declared under `dependencies` stays there.
+  It updates the global install as well when there is one. A Yarn Plug'n'Play project, which has
+  no `node_modules`, counts as installing sous when its `package.json` declares it and a `.pnp.cjs`
+  sits beside it or above it; the installed version is read from `yarn.lock`.
+- **After a project update**, the newly installed copy builds the project, so
+  `.sous/sous.lock.json` pins the core recipe at the new version. Under Yarn Plug'n'Play, Yarn
+  runs that build (`yarn run --binaries-only sous build`). `--no-build` skips it.
+
+Under Yarn Plug'n'Play, sous runs only from a copy Yarn has unpacked; from inside Yarn's zip cache
+it fails with `EBADF: bad file descriptor`. Unpack it in `package.json`, then run `yarn install`:
+
+```json
+"dependenciesMeta": { "@sous-io/sous": { "unplugged": true } }
+```
+
+`update` always runs in the copy you invoked, never handed off to the project's own; a project copy
+may be too old to have the command. A project config this copy cannot load (one written for a newer
+sous, say) is a warning rather than a stop, since installing a newer copy may be the fix.
+
+Every plan is worked out before anything is installed, and each install prints its plan and asks
+its own question. Each is judged on its own version:
+
+- By default, the newest published version in the install's current major (for a 0.x install,
+  anything below 1.0.0). A default run never downgrades.
+- `--major`: the newest published version, whatever its major.
+- `--version <version|range|tag>`: exactly that version, the newest one in that range, or the one a
+  dist-tag such as `next` points at. This is how you downgrade, and the plan says when it is one.
+- `--prerelease` counts prerelease versions, and is on by default when the installed version is a
+  prerelease; `--no-prerelease` switches it off.
+- `--global` or `--project` updates only that install; `-y, --yes` answers every question;
+  `--dry-run` prints the plans, with the command each would run, and installs nothing.
+
+A copy run through `npx`, or one managed by Volta or by a manager sous does not drive, is listed
+with the command to run by hand, and the rest are still updated. A package manager's own failure
+is printed as the manager reported it; sous never retries with `sudo`.
+
+```term
+$ sous update --dry-run
+// every install's plan, and nothing installed
+$ sous update --global --yes
+```
+
 ## Where to look
 
 - Watch the [animated introduction](../) for the full pitch

package/docs/markdown/_sidebar.md

@@ -29,3 +29,5 @@
   - [0008: One ref parser, told where the ref came from](adrs/0008-one-ref-parser.md)
   - [0009: One whole build, everywhere](adrs/0009-whole-build-everywhere.md)
   - [0010: The index describes each version's dependencies and questions](adrs/0010-index-describes-recipes.md)
+  - [0011: `sous update` updates sous through the package managers](adrs/0011-self-update.md)
+  - [0012: Recipes do not install Sous plugins](adrs/0012-recipes-and-plugins.md)

package/docs/markdown/commands.md

@@ -146,6 +146,27 @@ so it works offline. `--limit <n>` sets how many matches to show, defaulting to
 only installed recipes and adds an Installed column. Also spelled `sous repo search`.
 Example: `sous search task --limit 50`
 
+### `sous update`
+Updates sous itself: the global install, this project's own install, or both, each through the package manager
+that installed it. It works outside a project too, and it always runs in the copy you invoked, never handed off
+to the project's own. Every plan is printed before anything is installed, and each install asks its own
+question. After a project update the new copy builds the project, so the lockfile pins the core recipe at the new
+version. A project config this copy cannot load is one warning, not a stop. Takes `-y, --yes` and `--dry-run`
+(which also prints the command each install would run). See [Updating](README.md#updating).
+
+- `--major`: install the newest published version, whatever its major. By default each install moves to the
+  newest version in its current major, and never down.
+- `--version <version|range|tag>`: install exactly this version, the newest in this range, or the one this
+  dist-tag names. This is how you downgrade.
+- `--prerelease`, `--no-prerelease`: count prerelease versions as candidates, or not. On by default when the
+  installed version is a prerelease. `--pre` is the same flag.
+- `--global`, `--project`: update only that install.
+- `--no-build`: update the project install without building the project afterwards.
+
+`--major` and `--version` exclude each other, and so do `--global` and `--project`.
+
+Example: `sous update --version next --dry-run`
+
 ### `sous help [COMMAND]`
 Prints the help for sous, or for one command or topic. Works from any directory, including one with no config
 above it. Example: `sous help repo add`

package/docs/markdown/repositories-file-formats.md

@@ -80,9 +80,9 @@ contents:                           # what a subscriber actually receives
 | `contents`, `variables` | no | Contents default to an empty list, which is what a curated bundle publishes; a duplicated variable name, or two definitions claiming one `env`, is an error |
 | `submissions` | no | Whether this recipe takes proposed changes, winning over the repository's block; see [The submissions block](#the-submissions-block) |
 
-`contents[].kind` is `skills`, `memories`, `prompts` or `config`. The first three are written to the
-destinations named by [`recipeOutputs`](#recipeoutputs-where-the-files-land); `config` entries become config
-layers instead. `include` needs at least one glob, and both lists are recipe-relative.
+`contents[].kind` is `skills`, `memories`, `prompts` or `config`; there is no kind for a sous plugin. The
+first three are written to the destinations named by [`recipeOutputs`](#recipeoutputs-where-the-files-land);
+`config` entries become config layers instead. `include` needs at least one glob, and both lists are recipe-relative.
 
 ### The submissions block
 

package/docs/markdown/repositories.md

@@ -47,7 +47,8 @@ $ sous namespace list
 
 A recipe is the unit you subscribe to and the only thing that carries a version. It may hold
 skills, memories, prompts, config layers and variable definitions in any mixture, and
-subscribing to it gets all of them.
+subscribing to it gets all of them. A recipe may ship a plugin for a coding tool (a Claude Code
+plugin, say), but never a plugin for sous itself; those come only with sous or as npm packages.
 
 ```yaml
 # recipes/workflow/task-files/sous.recipe.yaml
@@ -193,10 +194,10 @@ this machine.
 Subscribing decides what is switched on, and it is not a second security gate. A recipe is
 **active** when the project subscribes to it directly or through its namespace, or when an active
 recipe lists it under `subscribes`; only an active recipe registers entry points of its own, such as
-output files, skills and hooks. A recipe held only through `depends` is a library: an active recipe
-may include, call or import its files, but it registers nothing itself. Activation keeps a project
-from running what it has no use for and keeps unrelated recipes from colliding; everything in a
-trusted repository is already trusted.
+output files, skills, tool hooks and tool plugins. A recipe held only through `depends` is a library:
+an active recipe may include, call or import its files, but it registers nothing itself. Activation
+keeps a project from running what it has no use for and keeps unrelated recipes from colliding;
+everything in a trusted repository is already trusted.
 
 ## The official repository, and the built-in core
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.30",
+  "version": "0.2.32",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",
@@ -60,6 +60,7 @@
     "jsonc-parser": "^3.3.1",
     "liquidjs": "^10.25.0",
     "minimatch": "^10.2.4",
+    "package-manager-detector": "^1.8.0",
     "semver": "^7.8.5",
     "tiktoken": "^1.0.22",
     "tsx": "^4",

package/recipes/core/sous-skills/skills/about-liquid-templates/SKILL.tpl.md

@@ -188,6 +188,13 @@ wins**; if none exist, the build errors listing every path tried:
 
 ## Custom Tags
 
+The tags below are built into sous. A recipe cannot add a tag or a filter, since that would be a
+Sous plugin; a Sous plugin comes only from sous's built-ins or an npm-style module.
+
+> "recipes will not be allowed to install _Sous_ plugins. All Sous plugins, besides any built-ins that ship with Sous, itself, will come from a NPM repo (or similar) as modules. Recipes _will_ be allowed to install tool plugins (e.g. Claude Code Plugins)."
+>
+>   -- **Luke Chavers** in an agent session (2026-09-29)
+
 **`showVars`**: dumps all variables currently in scope as a fenced JSON block.
 Useful during development to see exactly what variables are available at a given point
 in a template. Remove before finalizing.

package/recipes/core/sous-skills/skills/about-sous/SKILL.tpl.md

@@ -65,8 +65,14 @@ trust question reads only its index.
 Subscribing decides what is switched on, not what is safe. A recipe is active when the
 project subscribes to it, directly or through its namespace, or when an active recipe
 lists it under `subscribes`, and only an active recipe registers entry points of its own
-(output files, skills, hooks). A recipe held only through `depends` is a library: an active
-recipe may include, call or import its files, but it registers nothing itself.
+(output files, skills, tool hooks and tool plugins). A recipe held only through `depends` is a
+library: an active recipe may include, call or import its files, but it registers nothing
+itself. No recipe installs a Sous plugin; Sous plugins come only from sous's built-ins and from
+npm-style modules.
+
+> "recipes will not be allowed to install _Sous_ plugins. All Sous plugins, besides any built-ins that ship with Sous, itself, will come from a NPM repo (or similar) as modules. Recipes _will_ be allowed to install tool plugins (e.g. Claude Code Plugins)."
+>
+>   -- **Luke Chavers** in an agent session (2026-09-29)
 
 ## Sous's Own Documentation
 

package/recipes/core/sous-skills/skills/about-sous-recipes/SKILL.tpl.md

@@ -54,6 +54,14 @@ The fields in that example:
   it MUST be `.json`, `.jsonc`, `.yaml` or `.yml`, and every key outside `_aliases`, `_vars`,
   `compilation`, `recipeOutputs`, `runtimeContext`, `store` and `varMappings` is dropped with a
   warning. A recipe that only bundles others may leave `contents` out.
+- A recipe MAY install tool plugins (a plugin for a coding agent tool, such as a Claude Code
+  plugin) and MUST NOT install a Sous plugin (one that extends sous itself). Sous plugins come only
+  from the built-ins that ship with sous and from npm-style modules. A `config` file is
+  configuration, not a Sous plugin.
+
+  > "recipes will not be allowed to install _Sous_ plugins. All Sous plugins, besides any built-ins that ship with Sous, itself, will come from a NPM repo (or similar) as modules. Recipes _will_ be allowed to install tool plugins (e.g. Claude Code Plugins)."
+  >
+  >   -- **Luke Chavers** in an agent session (2026-09-29)
 - `depends`, `subscribes` and `variables` are described below; `submissions` is in
   `about-sous-repos`.
 

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.30
+version: 0.2.32
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous

package/src/base-command.ts

@@ -88,6 +88,20 @@ export abstract class BaseCommand extends Command {
    */
   static requiresConfig = true;
 
+  /**
+   * Whether a config that cannot be located or loaded stops this command. It
+   * is false on every command but the one whose job may be to repair that
+   * config: `sous update` installs a sous that may understand a config this
+   * copy rejects (one written for a newer version, say). When true, a failure
+   * to locate or load the config becomes one warning, naming the config and
+   * quoting the error, and the run carries on with no config adopted:
+   * `hasConfig` is false, the env files are not applied, and `rejectedConfig`
+   * says where the config that failed to load was, when discovery found it.
+   * It only changes what a FAILURE does; finding no config at all is still
+   * decided by `requiresConfig`.
+   */
+  static toleratesConfigErrors = false;
+
   protected settings!: Settings;
 
   /** Where the active config was found. */
@@ -103,6 +117,13 @@ export abstract class BaseCommand extends Command {
   /** The full discovery result, including how the config was located. */
   protected discovered!: DiscoveredConfig;
 
+  /**
+   * The config discovery found but could not load, on a command that
+   * `toleratesConfigErrors`. Undefined when the config loaded, when there was
+   * none, or when the failure came before any config file was identified.
+   */
+  protected rejectedConfig?: { configPath: string; sousDir: string };
+
   /**
    * The real shell environment, snapshotted BEFORE the `.sous/` env files are
    * injected into `process.env`. The variables layer needs it to tell a value
@@ -177,7 +198,7 @@ export abstract class BaseCommand extends Command {
       [sousDirEnv, "SOUS_DIR"],
     ];
     const primary = primaryCandidates.find(([value]) => value !== undefined);
-    const requiresConfig = (this.constructor as typeof BaseCommand).requiresConfig;
+    const { requiresConfig, toleratesConfigErrors } = this.constructor as typeof BaseCommand;
 
     this.configLocator = {
       cwd,
@@ -195,6 +216,12 @@ export abstract class BaseCommand extends Command {
       try {
         discovered = resolveConfigFlag(primarySource, cwd, confDirOverride, sourceLabel);
       } catch (error) {
+        if (toleratesConfigErrors) {
+          return this.warnConfigNotLoaded(
+            error,
+            `the project config at ${this.configLocator.primary?.value} (named by ${sourceLabel})`
+          );
+        }
         // A command that creates the config is pointed at a place with none in
         // it by design; the flag still says where, so this is not a failure.
         if (!requiresConfig) return;
@@ -202,7 +229,12 @@ export abstract class BaseCommand extends Command {
         return this.exit(1);
       }
     } else {
-      discovered = discoverConfig(cwd, confDirOverride);
+      try {
+        discovered = discoverConfig(cwd, confDirOverride);
+      } catch (error) {
+        if (!toleratesConfigErrors) throw error;
+        return this.warnConfigNotLoaded(error, `the project config it found searching up from ${cwd}`);
+      }
     }
 
     if (!discovered) {
@@ -243,6 +275,7 @@ export abstract class BaseCommand extends Command {
     try {
       refreshed = refreshDiscoveredConfig(discovered);
     } catch (error) {
+      if (this.toleratesConfigErrors) return this.rejectConfig(discovered, error);
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
@@ -262,11 +295,51 @@ export abstract class BaseCommand extends Command {
     try {
       this.settings = await loadSettings(refreshed);
     } catch (error) {
+      if (this.toleratesConfigErrors) return this.rejectConfig(refreshed, error);
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
   }
 
+  /** The `toleratesConfigErrors` setting of the running command's class. */
+  private get toleratesConfigErrors(): boolean {
+    return (this.constructor as typeof BaseCommand).toleratesConfigErrors;
+  }
+
+  /**
+   * Undoes a config adoption that failed on a command that tolerates it: the
+   * env files it injected are taken back out of `process.env`, nothing is left
+   * adopted, and one warning says what happened.
+   */
+  private rejectConfig(discovered: DiscoveredConfig, error: unknown): void {
+    for (const name of Object.keys(process.env)) {
+      if (!(name in this.shellEnv)) delete process.env[name];
+    }
+    this.shellEnv = {};
+    this.discovered = undefined as unknown as DiscoveredConfig;
+    this.configContext = undefined as unknown as ConfigContext;
+    this.rejectedConfig = { configPath: discovered.configPath, sousDir: discovered.sousDir };
+    this.warnConfigNotLoaded(error, `the project config at ${discovered.configPath}`);
+  }
+
+  /**
+   * The one warning a command that tolerates config errors prints in place of
+   * failing.
+   *
+   * @param error - What locating or loading the config threw.
+   * @param config - Which config: its file, or where it was looked for.
+   */
+  private warnConfigNotLoaded(error: unknown, config: string): void {
+    const message = error instanceof Error ? error.message : String(error);
+    warning(
+      `Sous could not load ${config}, so this command carries on without it.\n` +
+        "\n" +
+        "The error was:\n" +
+        message,
+      this.errorSink
+    );
+  }
+
   /**
    * Renders any failure as a plain, readable message instead of an oclif stack
    * trace: a config mistake, a mistyped command line, or a question sous could

package/src/commands/update.ts

@@ -0,0 +1,178 @@
+/**
+ * `sous update` moves sous itself to a newer (or a chosen) version, for the
+ * global install, the project's own install, or both, through whichever
+ * package manager owns each one (sous-io/sous#135).
+ *
+ *     sous update
+ *     sous update --global
+ *     sous update --major
+ *     sous update --version 0.2.18
+ *     sous update --dry-run
+ *
+ * It runs outside a project as readily as inside one, so it opts out of the
+ * config requirement, as `sous init` does. `bin/run.js` never hands this
+ * command to a project's own copy: updating the copy that was invoked is the
+ * point. The flow itself lives in `lib/self-update/run.ts`; this class turns
+ * the flags into its options and decides the exit code.
+ */
+
+import path from "node:path";
+import { Flags } from "@oclif/core";
+import { BaseCommand } from "../base-command.js";
+import { SOUS_DIR_NAME, findConfigInSousDir } from "../lib/config-discovery.js";
+import { ConfigError, isConfigError } from "../lib/errors.js";
+import { CLI_ROOT } from "../lib/package-info.js";
+import { registryUrl, runSelfUpdate } from "../lib/self-update/run.js";
+import type { UpdateScope, VersionRequest } from "../lib/self-update/index.js";
+import { confirmationFlag } from "../utils/flags.js";
+import { footer, showCommandVars } from "../utils/formatting.js";
+
+export default class Update extends BaseCommand {
+  static description =
+    "Update sous itself, globally and in this project, through the package manager that installed each copy";
+
+  /** This command updates sous wherever it is installed; a project config is optional. */
+  static override requiresConfig = false;
+
+  /**
+   * A config this copy cannot load (one written for a newer sous, say) is the
+   * very thing an update may fix, so it is a warning here rather than a stop.
+   */
+  static override toleratesConfigErrors = true;
+
+  static examples = [
+    "<%= config.bin %> update",
+    "<%= config.bin %> update --global",
+    "<%= config.bin %> update --major",
+    "<%= config.bin %> update --version 0.2.18",
+    "<%= config.bin %> update --version next",
+    "<%= config.bin %> update --dry-run",
+  ];
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    major: Flags.boolean({
+      description: "Install the newest published version, whatever its major version",
+      default: false,
+      exclusive: ["version"],
+    }),
+    version: Flags.string({
+      description: "Install this version, the newest version in this range, or the version this dist-tag names",
+      exclusive: ["major"],
+    }),
+    prerelease: Flags.boolean({
+      description:
+        "Count prerelease versions as candidates; on by default when the installed version is a prerelease",
+      allowNo: true,
+      aliases: ["pre"],
+    }),
+    global: Flags.boolean({
+      description: "Update only the global install",
+      default: false,
+      exclusive: ["project"],
+    }),
+    project: Flags.boolean({
+      description: "Update only this project's own install",
+      default: false,
+      exclusive: ["global"],
+    }),
+    yes: confirmationFlag(),
+    "dry-run": Flags.boolean({
+      description: "Print every install's plan without installing anything",
+      default: false,
+    }),
+    "no-build": Flags.boolean({
+      description: "Update the project install without building the project afterwards",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(Update);
+    const dryRun = flags["dry-run"];
+    const request: VersionRequest =
+      flags.version !== undefined
+        ? { kind: "spec", spec: flags.version }
+        : flags.major
+          ? { kind: "major" }
+          : { kind: "default" };
+    const only: UpdateScope | undefined = flags.global
+      ? "global"
+      : flags.project
+        ? "project"
+        : undefined;
+
+    showCommandVars({
+      Directory: this.configLocator.cwd,
+      Installs: only === undefined ? "global and project" : `${only} only`,
+      Version: describeRequest(request),
+      Prereleases:
+        flags.prerelease === undefined
+          ? "counted when the installed version is one"
+          : flags.prerelease
+            ? "counted"
+            : "not counted",
+      Registry: registryUrl(),
+      "Dry Run": dryRun,
+    });
+
+    const outcome = await runSelfUpdate({
+      cwd: this.configLocator.cwd,
+      ownRoot: CLI_ROOT,
+      request,
+      ...(flags.prerelease === undefined ? {} : { prerelease: flags.prerelease }),
+      ...(only === undefined ? {} : { only }),
+      dryRun,
+      yes: flags.yes,
+      interactive: this.interactive,
+      build: !flags["no-build"],
+      buildDirFor: (projectRoot) => this.buildDirFor(projectRoot),
+    });
+
+    footer();
+
+    if (outcome.failed) {
+      throw new ConfigError(
+        "Not every step of the update succeeded; the summary above lists what completed and what failed."
+      );
+    }
+  }
+
+  /**
+   * Where a build after a project update runs: the directory of the config
+   * discovery found, when it lies inside the project that was updated, and
+   * otherwise the project root when its own `.sous/` holds a primary config.
+   * A config this copy could not load counts as found: the new copy may
+   * understand it, and its build is where any real problem is reported.
+   * Undefined means the project has no sous config, so nothing is built.
+   */
+  private buildDirFor(projectRoot: string): string | undefined {
+    const found = this.hasConfig ? this.discovered.sousDir : this.rejectedConfig?.sousDir;
+    if (found !== undefined) {
+      const configDir = path.dirname(found);
+      const relative = path.relative(projectRoot, configDir);
+      if (!relative.startsWith("..") && !path.isAbsolute(relative)) return configDir;
+    }
+    return holdsPrimaryConfig(path.join(projectRoot, SOUS_DIR_NAME)) ? projectRoot : undefined;
+  }
+}
+
+/**
+ * Whether a `.sous/` directory holds a primary config. Holding several is
+ * still holding one: the build that follows reports that mistake itself.
+ */
+function holdsPrimaryConfig(sousDir: string): boolean {
+  try {
+    return findConfigInSousDir(sousDir) !== null;
+  } catch (error) {
+    if (isConfigError(error)) return true;
+    throw error;
+  }
+}
+
+/** The version request, as the opening block says it. */
+function describeRequest(request: VersionRequest): string {
+  if (request.kind === "default") return "the newest in each install's major version";
+  if (request.kind === "major") return "the newest published, whatever its major version";
+  return request.spec;
+}

package/src/lib/project-install.d.mts

@@ -18,7 +18,11 @@ export type HandoffPlan =
 
 export function isEnvFlagOn(value: string | undefined): boolean;
 export function binEntryOf(pkg: unknown): string | undefined;
+export function readPackageJson(dir: string): Record<string, unknown> | undefined;
 export function findProjectInstall(startDir: string, ownRoot: string): ProjectInstall | undefined;
+export function findProjectCopy(startDir: string): string | undefined;
+export function realpathOr(p: string): string;
+export function describeInstall(candidate: string, ownRoot: string): ProjectInstall | undefined;
 export function formatHandoffNotice(input: {
   install: Extract<ProjectInstall, { same: false }>;
   ownVersion: string;

package/src/lib/project-install.mjs

@@ -27,6 +27,10 @@
  *   - Anything unreadable or ambiguous means "run the copy that was invoked".
  *     A hand-off is a convenience; a refusal to run is not.
  *   - `SOUS_NO_DELEGATE` (anything but 0/false/no/off) runs the invoked copy.
+ *   - `sous update` runs the invoked copy: updating the copy that was invoked
+ *     is its job, and a project copy may be too old to have the command. The
+ *     command word is the first entry on the command line that is not a flag,
+ *     so `sous subscription update` still hands off.
  *   - The notice goes to stderr, so piped stdout stays clean. It prints when
  *     the two versions differ, and on every hand-off under `SOUS_DEBUG` or
  *     with `--verbose` anywhere on the command line. Plain, it is one line
@@ -50,6 +54,20 @@ export const DEBUG_ENV = "SOUS_DEBUG";
 /** The flag that makes the notice say where both installs are. */
 export const VERBOSE_FLAG = "--verbose";
 
+/** The command that always runs in the copy that was invoked. */
+export const SELF_UPDATE_COMMAND = "update";
+
+/**
+ * The command word on a command line: its first entry that does not start
+ * with `-`, or undefined when every entry is a flag.
+ *
+ * commandWordOf(["--verbose", "update", "--yes"]) -> "update"
+ * commandWordOf(["subscription", "update"]) -> "subscription"
+ */
+export function commandWordOf(argv) {
+  return argv.find((arg) => !arg.startsWith("-"));
+}
+
 /**
  * Whether an on/off environment variable is on: set to anything but an empty
  * string, `0`, `false`, `no` or `off` (case-insensitive, whitespace trimmed).
@@ -60,10 +78,10 @@ export function isEnvFlagOn(value) {
 }
 
 /**
- * Reads a package.json, returning the parsed object or undefined for a file
- * that is missing, unreadable or not JSON.
+ * Reads the package.json in `dir`, returning the parsed object or undefined
+ * for a file that is missing, unreadable or not JSON.
  */
-function readPackageJson(dir) {
+export function readPackageJson(dir) {
   try {
     return JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
   } catch {
@@ -103,19 +121,32 @@ export function binEntryOf(pkg) {
  * older one further up would be a guess.
  */
 export function findProjectInstall(startDir, ownRoot) {
+  const candidate = findProjectCopy(startDir);
+  return candidate === undefined ? undefined : describeInstall(candidate, ownRoot);
+}
+
+/**
+ * Looks up from `startDir` for the nearest `node_modules/@sous-io/sous` that
+ * holds a package.json, and returns that path as found, WITHOUT resolving
+ * symlinks (pnpm links it into its own store, so only the unresolved path says
+ * which project holds it). Undefined when no ancestor holds one.
+ */
+export function findProjectCopy(startDir) {
   let dir = path.resolve(startDir);
   for (;;) {
     const candidate = path.join(dir, "node_modules", ...PACKAGE_NAME.split("/"));
-    if (fs.existsSync(path.join(candidate, "package.json"))) {
-      return describeInstall(candidate, ownRoot);
-    }
+    if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
     const parent = path.dirname(dir);
     if (parent === dir) return undefined;
     dir = parent;
   }
 }
 
-function realpathOr(p) {
+/**
+ * The real path of `p`, or `p` resolved when it cannot be read (it does not
+ * exist, or a link in it is broken).
+ */
+export function realpathOr(p) {
   try {
     return fs.realpathSync(p);
   } catch {
@@ -123,7 +154,13 @@ function realpathOr(p) {
   }
 }
 
-function describeInstall(candidate, ownRoot) {
+/**
+ * Describes the copy of the package at `candidate` the way `findProjectInstall`
+ * does: `{ same: true, root }` when it is `ownRoot`, compared by real path,
+ * `{ same: false, root, version, bin }` for a usable other copy, and undefined
+ * for one that is not usable.
+ */
+export function describeInstall(candidate, ownRoot) {
   const root = realpathOr(candidate);
   if (root === realpathOr(ownRoot)) return { same: true, root };
   const pkg = readPackageJson(root);
@@ -162,6 +199,7 @@ export function formatHandoffNotice({ install, ownVersion, ownRoot, verbose }) {
  */
 export function planHandoff({ cwd, ownRoot, env, argv = [] }) {
   if (isEnvFlagOn(env[NO_DELEGATE_ENV])) return { kind: "run-self" };
+  if (commandWordOf(argv) === SELF_UPDATE_COMMAND) return { kind: "run-self" };
   const install = findProjectInstall(cwd, ownRoot);
   if (!install || install.same) return { kind: "run-self" };