@jals1212/pi-spaces 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,42 @@ commands and options and a patch version fixes.
 
 ## Unreleased
 
+## 0.4.0
+
+### Added
+
+- `pi --space <name> <command> [args...]` runs one of Pi's package commands
+  (`install`, `remove`, `uninstall`, `update`, `list`) in a space, or in the
+  base home with `base`, through the same Pi: `pi --space work update
+  --extensions`. Options before `--space`, such as a launcher's own `-e`, are
+  left out, since Pi runs a package command only as its first argument.
+
+### Changed
+
+- The command words `list`, `new`, `remove`, `rename`, `switch`, `update`,
+  `install` and `uninstall` are reserved and can no longer name a space, so
+  `pi-space <name>` never reads as a command. A folder with such a name in the
+  spaces folder is no longer listed as a space.
+
+## 0.3.0
+
+### Added
+
+- Pi knows the space it runs in. Every Pi with the extension sets
+  `PI_SPACE` (unset in the base home), `PI_SPACE_HOME` (its agent home) and
+  `PI_SPACES_COMMAND` (its configured value, else `pi`), with or without a
+  switch, and the system prompt gets a `<pi_space>` section with the same
+  facts. `spaceInfo`, `exportSpaceInfo` and `spacePrompt` in the core build
+  them.
+- A `pi-spaces` skill, declared in the package, that tells agents what a
+  space is, how to read the current space, home and command, and which
+  `/space` or `pi-space` action to use.
+
+### Changed
+
+- The status line shows the active space as `◆ <name>` instead of
+  `space: <name>`, so it stands out among other extensions' statuses.
+
 ## 0.2.0
 
 ### Added

package/README.md

@@ -45,8 +45,9 @@ From your shell:
 ```sh
 pi --space work                         # start Pi in "work"
 pi --space work "review this branch"    # with a prompt
-pi-space --new work                     # create a space (optional CLI)
-pi-space --remove work                  # delete it, after asking; keeps a backup unless told not to (optional CLI)
+pi-space new work                       # create a space (optional CLI)
+pi-space remove work                    # delete it, after asking; keeps a backup unless told not to (optional CLI)
+pi-space update --every                 # update the packages of base and of every space (optional CLI)
 pi-space                                # pick from a numbered list (optional CLI)
 ```
 
@@ -64,16 +65,17 @@ A new space starts empty except for a `settings.json` that declares this package
 | `/space rename <old> <new>` | Renames a space. The active space cannot be renamed. |
 | `/space remove <name> [--yes] [--no-backup]` | Deletes a space after asking, then asks whether to keep a backup in `<spaces folder>/.backups` (keeping one is first in the list; dismissing the question keeps the space). `--yes` skips the questions and keeps a backup; it is required without a dialog (print and JSON modes). `--no-backup` deletes without one. |
 | `pi --space <name>` | Starts Pi directly in a space, keeping the prompt and every other option. |
+| `pi --space <name> <command> [args...]` | Runs one of Pi's package commands (`install`, `remove`, `uninstall`, `update`, `list`) in a space, or in the base home with `base`: `pi --space work update --extensions`, `pi --space work install npm:<package>`. |
 
-The status line shows `space: <name>` while a space is active, and nothing in the base home.
+The status line shows `◆ <name>` while a space is active, and nothing in the base home.
 
 Choosing an argument such as `switch` from the `/space ` suggestions only fills the line; press Enter again to run it. `/space` and Enter opens the picker in one step.
 
-**Names**: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters. `base` is reserved.
+**Names**: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters. `base` is reserved, and so are the command words `list`, `new`, `remove`, `rename`, `switch`, `update`, `install` and `uninstall`.
 
 ## The `pi-space` command
 
-The optional `@jals1212/pi-spaces-cli` package adds a `pi-space` command to your shell: `pi-space` picks a space from a numbered list and starts Pi in it, `pi-space <name> [pi args...]` starts Pi in a named space, `pi-space --new <name>` creates one, `pi-space --remove <name>` deletes one, and `pi-space list` lists them. `--command` and `--dir` (or `PI_SPACES_COMMAND` and `PI_SPACES_DIR`) make it run another program that runs Pi, with that program's spaces. It only runs `pi --space <name>`, so this extension must be installed in the home it opens. See [`cli/README.md`](cli/README.md) for the commands, the options and the exit status.
+The optional `@jals1212/pi-spaces-cli` package adds a `pi-space` command to your shell: `pi-space` picks a space from a numbered list and starts Pi in it, `pi-space <name> [pi args...]` starts Pi in a named space, `pi-space new <name>` creates one, `pi-space rename <old> <new>` renames one, `pi-space remove <name>` deletes one, and `pi-space list` lists them. `pi-space list|update|install|uninstall <name|--every> ...` runs Pi's package commands in a space, or in every space. `--command` and `--dir` (or `PI_SPACES_COMMAND` and `PI_SPACES_DIR`) make it run another program that runs Pi, with that program's spaces. It only runs `pi --space <name> [command]`, so this extension must be installed in the home it opens. See [`cli/README.md`](cli/README.md) for the commands, the options and the exit status.
 
 ## Configuration reference
 
@@ -99,6 +101,22 @@ Set for the Pi a switch starts:
 | `PI_SPACE` | The space's name. Unset in the base home. |
 | `PI_SPACES_BASE_HOME` | The home Pi started with, so `base` and the spaces folder survive switches. |
 
+Set in every Pi this extension runs in, even one started without a switch, for its tools and the programs they start:
+
+| Variable | Meaning |
+| --- | --- |
+| `PI_SPACE` | The active space's name, unset in the base home: the same variable a switch sets. |
+| `PI_SPACE_HOME` | The agent home this Pi runs with: the space's folder, or the base home. |
+| `PI_SPACES_COMMAND` | Kept when it has a value; set to `pi` when it is unset or blank. |
+
+### What the model is told
+
+Before each run the system prompt gets a `<pi_space>` section with the same three facts: the space (or the base home), the agent home, and the command, with `<command> --space <name>` and `/space` as the ways to change space. The model knows where it runs without reading the environment. A Pi without structured prompt sections gets no section; the variables are still set.
+
+### The `pi-spaces` skill
+
+The package also ships a `pi-spaces` skill (`skills/pi-spaces/SKILL.md`). It tells agents what a space is, how to read the current space, home and command, and which `/space` or `pi-space` action to use or propose for listing, creating, switching and removing spaces. Pi loads it when a task is about spaces; `/skill:pi-spaces` loads it by hand.
+
 ### Exit status
 
 | Status | `pi --space` |
@@ -119,13 +137,15 @@ Pi reads its agent home once, when it starts, so a running session cannot move t
 
 `pi --space <name>` acts before Pi opens its interface or runs anything, so it keeps the prompt and the session options too, in every mode.
 
+`pi --space <name> <command> ...`, where `<command>` is one of Pi's package commands right after the name, runs Pi again in that home with only `<command> ...`: Pi runs a package command only as its first argument. Options before `--space`, such as a launcher's own `-e`, are left out. The same Pi runs it, so a launcher's own Pi manages the space's packages; `base` and the current home work too.
+
 ## What it leaves on your machine
 
 Only the spaces you create, each a folder in the spaces folder, and its `settings.json`. Pi fills a space as it would any home. Removing a space moves its folder to `.backups/<name>-<UTC time>` in the spaces folder, or deletes it with `--no-backup` or when you choose so; nothing else is written outside it. A backup is a whole space: move it back to restore it (`mv ~/.pi/spaces/.backups/work-2026-10-28T14-30-05Z ~/.pi/spaces/work`), or delete it when you no longer need it. Backups are never removed for you, and `.backups` is never listed as a space.
 
 ## Safety
 
-`/space remove`, `/space rename` and `pi-space --remove` refuse, before they ask:
+`/space remove`, `/space rename`, `pi-space remove` and `pi-space rename` refuse, before they ask:
 
 - `base` and the active space;
 - symlinks, and anything that is not a real folder directly inside the spaces folder;

package/dist/command.js

@@ -157,7 +157,7 @@ function switchTo(name        , deps                  )       {
 /** Status line text: the active space, or nothing in the base home. */
 export function statusText(dir        , currentHome        )                     {
 	const active = activeSpace(dir, currentHome);
-	return active === undefined ? undefined : `space: ${active}`;
+	return active === undefined ? undefined : `◆ ${active}`;
 }
 
 export function completeSpaceArgs(prefix        , dir        )                                            {

package/dist/context.js

@@ -0,0 +1,63 @@
+// What this Pi process knows about its space: the active space, the agent home and the command
+// that starts Pi. It is exported to the environment (for tools and child processes) and told to the model.
+import { resolve } from "node:path";
+import { activeSpace,          } from "./spaces.js";
+
+                            
+	                                                       
+	                          
+	                                        
+	             
+	                                                                  
+	                
+ 
+
+/**
+ * Read once, when the extension loads: Pi keeps its agent home for the whole process, and
+ * the active space cannot be renamed or removed, so the facts hold until Pi exits.
+ */
+export function spaceInfo(dir        , agentHome        , env     )            {
+	return {
+		space: activeSpace(dir, agentHome),
+		home: resolve(agentHome),
+		// A blank value counts as unset, so the default is pi, as in the pi-space command.
+		command: env.PI_SPACES_COMMAND?.trim() || "pi",
+	};
+}
+
+/** Sets PI_SPACE (removed in the base home), PI_SPACE_HOME and PI_SPACES_COMMAND. */
+export function exportSpaceInfo(env     , info           )       {
+	if (info.space === undefined) delete env.PI_SPACE;
+	else env.PI_SPACE = info.space;
+	env.PI_SPACE_HOME = info.home;
+	env.PI_SPACES_COMMAND = info.command;
+}
+
+/** The system prompt section that tells the model where it runs. */
+export function spacePrompt(info           )         {
+	const where = info.space === undefined
+		? "This Pi runs in the base home, outside any space."
+		: `This Pi runs in the space "${info.space}" (PI_SPACE).`;
+	const home = `Agent home: ${info.home} (PI_SPACE_HOME).`;
+	const start = `\`${info.command} --space <name>\` starts it in a space`;
+	const manage = "`/space` lists, creates, removes and switches spaces";
+	const command = `Command that starts Pi: ${info.command} (PI_SPACES_COMMAND); ${start}, and ${manage}.`;
+	return [where, home, command].join("\n");
+}
+
+/** The part of a run's structured prompt options this package writes. */
+                                 
+	                                  
+ 
+
+/**
+ * Sets the <pi_space> section in a run's structured prompt options, creating the section map when
+ * it is missing and replacing an earlier pi_space section. Other sections and the rest of the
+ * prompt are left alone. Without structured options (an older Pi) nothing is added; the
+ * environment still has the facts.
+ */
+export function addSpaceSection(options                            , info           )       {
+	if (options === undefined) return;
+	options.sections ??= {};
+	options.sections.pi_space = spacePrompt(info);
+}

package/dist/relaunch.js

@@ -123,10 +123,14 @@ export function relaunchCommand(proc       = process, args           = filterArg
 
 const SPACE_FLAG_ERROR = "--space needs a space name: pi --space <name>.";
 
-/** Finds --space <name> or --space=<name> before "--", and returns the other arguments unchanged. */
-export function parseSpaceFlag(args          )                                                                   {
+/**
+ * Finds --space <name> or --space=<name> before "--", and returns the other arguments unchanged,
+ * and the arguments that follow the name.
+ */
+export function parseSpaceFlag(args          )                                                                                        {
 	const rest           = [];
 	let name                    ;
+	let afterName           = [];
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (arg === "--") {
@@ -138,36 +142,48 @@ export function parseSpaceFlag(args          )
 			if (value === undefined || value === "" || value.startsWith("-")) return { error: SPACE_FLAG_ERROR };
 			name = value;
 			i++;
+			afterName = args.slice(i + 1);
 		} else if (arg.startsWith("--space=")) {
 			name = arg.slice("--space=".length);
 			if (name === "") return { error: SPACE_FLAG_ERROR };
+			afterName = args.slice(i + 1);
 		} else {
 			rest.push(arg);
 		}
 	}
-	return { name, rest };
+	return { name, rest, afterName };
 }
 
+// Pi runs these only as its first argument, before extensions load.
+const PACKAGE_COMMANDS = new Set(["install", "remove", "uninstall", "update", "list"]);
+
                                                                                                                                    
 
 /**
  * What `pi --space <name>` does at startup: nothing without the flag or when Pi already runs in that
  * space; otherwise run Pi again in the space with every other argument, since nothing has run yet.
+ * `pi --space <name> <package command> ...` always runs Pi again, even in the current home, because
+ * Pi runs a package command (install, remove, uninstall, update, list) only as its first argument.
  */
 export function planStartup(input                                                            )              {
 	const { proc, dir, currentHome, env } = input;
 	const parsed = parseSpaceFlag(proc.argv.slice(2));
 	if ("error" in parsed) return { kind: "error", message: parsed.error };
 	if (parsed.name === undefined) return { kind: "none" };
+	// A package command runs alone: options before --space (a launcher may add its own) are for a session.
+	const packageCommand = PACKAGE_COMMANDS.has(parsed.afterName[0] ?? "");
+	const args = packageCommand ? parsed.afterName : parsed.rest;
 	let target              ;
 	try {
 		target = resolveSwitch({ dir, name: parsed.name, currentHome, env });
 	} catch (error) {
 		if (!(error instanceof SpaceError)) throw error;
-		if (error.message.startsWith("Already in")) return { kind: "none" };
+		if (error.message.startsWith("Already in")) {
+			return packageCommand ? { kind: "relaunch", command: relaunchCommand(proc, args), env } : { kind: "none" };
+		}
 		return { kind: "error", message: error.message };
 	}
-	return { kind: "relaunch", command: relaunchCommand(proc, parsed.rest), env: relaunchEnv(env, { ...target, currentHome }) };
+	return { kind: "relaunch", command: relaunchCommand(proc, args), env: relaunchEnv(env, { ...target, currentHome }) };
 }
 
 /** Runs the command now with inherited stdio and returns its exit code (1 when it cannot start). */

package/dist/spaces.js

@@ -37,9 +37,13 @@ export function spacesDir(env      = process.env, home         = osHomedir())
 	return join(dirname(resolve(baseHome)), "spaces");
 }
 
+// The words of the pi-space and /space commands, so a space name never reads as one.
+const COMMANDS = new Set(["list", "new", "remove", "rename", "switch", "update", "install", "uninstall"]);
+
 /** Returns the error message for an unusable name, or undefined when the name is valid. */
 export function validateName(name        )                     {
 	if (name === BASE) return `"${BASE}" is reserved for the home Pi started with.`;
+	if (COMMANDS.has(name)) return `"${name}" is reserved: it is a pi-space or /space command.`;
 	if (!NAME.test(name)) {
 		return `Invalid space name "${name}": use lowercase letters, digits, "-" and "_", starting with a letter or digit (at most 64 characters).`;
 	}

package/extensions/spaces.ts

@@ -4,6 +4,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { completeSpaceArgs, runSpaceCommand, statusText } from "../src/command.ts";
+import { addSpaceSection, exportSpaceInfo, spaceInfo } from "../src/context.ts";
 import { planStartup, relaunchCommand, runNow, scheduleRelaunch } from "../src/relaunch.ts";
 import { findOwnDeclaration, spacesDir } from "../src/spaces.ts";
 
@@ -20,6 +21,11 @@ export default function (pi: ExtensionAPI) {
 	}
 	if (plan.kind === "relaunch") process.exit(runNow(plan.command, plan.env));
 
+	// Where this Pi runs: exported for tools and the programs they start, and told to the model before each run.
+	const info = spaceInfo(spacesDir(), getAgentDir(), process.env);
+	exportSpaceInfo(process.env, info);
+	pi.on("before_agent_start", (event) => addSpaceSection(event.systemPromptOptions, info));
+
 	pi.registerFlag("space", { description: "Start Pi in this space (see /space list)", type: "string" });
 
 	pi.on("session_start", (_event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/pi-spaces",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Named spaces for Pi: keep several agent homes (sign-ins, packages, settings) and pick one by name.",
   "license": "MIT",
   "author": "jals1212",
@@ -25,12 +25,16 @@
   "pi": {
     "extensions": [
       "./extensions/spaces.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "files": [
     "dist",
     "src",
     "extensions",
+    "skills",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -41,7 +45,10 @@
   "scripts": {
     "build": "node --disable-warning=ExperimentalWarning scripts/build.mjs",
     "prepack": "npm run build",
-    "test": "node scripts/link-self.mjs && npm run build && node --test 'tests/*.test.ts' && npm test --prefix cli"
+    "test": "node scripts/link-self.mjs && npm run build && node --test \"tests/*.test.ts\" && npm test --prefix cli"
+  },
+  "devDependencies": {
+    "cross-spawn": "^7.0.6"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/skills/pi-spaces/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: pi-spaces
+description: "Trigger: pi-spaces, space, spaces, /space, pi-space, pi --space, PI_SPACE, PI_SPACE_HOME, PI_SPACES_COMMAND, which space, agent home, base home, update, install, uninstall. Know which Pi space this session runs in, its home and start command, and how spaces and their packages are listed, created, updated, switched and removed."
+license: MIT
+metadata:
+  author: jals1212
+  version: "1.0"
+---
+
+## Activation Contract
+
+Use when a task depends on which Pi agent home this session uses (settings, sign-ins, installed packages, sessions), or when the user asks about spaces. A space is a separate Pi agent home kept in a folder of the spaces folder; the base home is the one Pi started with. Pi reads its home once at startup, so one process stays in one space.
+
+## Hard Rules
+
+- Read where you run from the `<pi_space>` system prompt section; in a shell, from `PI_SPACE` (unset in the base home), `PI_SPACE_HOME` (this Pi's agent home) and `PI_SPACES_COMMAND` (the program that starts Pi, default `pi`). Never guess from `~/.pi/agent`.
+- Files of this session's home (`settings.json`, `extensions/`, `sessions/`, installed packages) live under `PI_SPACE_HOME`; `pi install` and settings changes apply to this space only.
+- Never read `auth.json` or other credential files in any home.
+- You cannot move this session to another space. Ask the user to run `/space switch <name>` (interactive terminal only; Pi restarts), or start another Pi with `$PI_SPACES_COMMAND --space <name>`.
+- Never set `PI_CODING_AGENT_DIR` yourself, and never create, rename or delete space folders with file commands; use `/space` or `pi-space`.
+- Removing a space deletes everything in it: only on the user's explicit request, and keep the backup unless they say otherwise.
+
+## Decision Gates
+
+| Need | Action |
+| --- | --- |
+| Which space, home, command | `<pi_space>` section, or `echo "$PI_SPACE|$PI_SPACE_HOME|$PI_SPACES_COMMAND"` |
+| List spaces from a shell | `pi-space list` (optional `@jals1212/pi-spaces-cli`) |
+| Spaces folder | `PI_SPACES_DIR`, else `spaces` next to the base home (`PI_SPACES_BASE_HOME`, else this home) |
+| Create a space | `pi-space new <name>`, or ask the user for `/space new <name>` |
+| Work in another space | User runs `/space switch <name>`, or `$PI_SPACES_COMMAND --space <name> "<prompt>"` |
+| Remove a space | User request only: `pi-space remove <name> --yes` keeps a backup in `.backups` |
+| Packages of a space | `pi-space update <name|base|--every> --extensions`, `pi-space install <name> <source>`, `pi-space uninstall <name> <source>`, `pi-space list <name>`; without the CLI, `$PI_SPACES_COMMAND --space <name|base> update --extensions` |
+
+Names: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters; `base` (the base home) and the command words (`list`, `new`, `remove`, `rename`, `switch`, `update`, `install`, `uninstall`) are reserved.
+
+## Execution Steps
+
+1. Read the `<pi_space>` section or the three variables before touching any home file.
+2. Pick the action from Decision Gates; prefer telling the user the `/space` command when it needs the interactive terminal.
+3. Report the space and home you acted on.
+
+## Output Contract
+
+State the space (or "base home"), the agent home path, and the command or `/space` action used or proposed.
+
+## References
+
+- `../../README.md` — commands, environment variables and how switching works.

package/src/command.ts

@@ -157,7 +157,7 @@ function switchTo(name: string, deps: SpaceCommandDeps): void {
 /** Status line text: the active space, or nothing in the base home. */
 export function statusText(dir: string, currentHome: string): string | undefined {
 	const active = activeSpace(dir, currentHome);
-	return active === undefined ? undefined : `space: ${active}`;
+	return active === undefined ? undefined : `◆ ${active}`;
 }
 
 export function completeSpaceArgs(prefix: string, dir: string): { value: string; label: string }[] | null {

package/src/context.ts

@@ -0,0 +1,63 @@
+// What this Pi process knows about its space: the active space, the agent home and the command
+// that starts Pi. It is exported to the environment (for tools and child processes) and told to the model.
+import { resolve } from "node:path";
+import { activeSpace, type Env } from "./spaces.ts";
+
+export interface SpaceInfo {
+	/** The active space, or undefined in the base home. */
+	space: string | undefined;
+	/** The agent home this Pi runs with. */
+	home: string;
+	/** PI_SPACES_COMMAND, the program that starts Pi (default pi). */
+	command: string;
+}
+
+/**
+ * Read once, when the extension loads: Pi keeps its agent home for the whole process, and
+ * the active space cannot be renamed or removed, so the facts hold until Pi exits.
+ */
+export function spaceInfo(dir: string, agentHome: string, env: Env): SpaceInfo {
+	return {
+		space: activeSpace(dir, agentHome),
+		home: resolve(agentHome),
+		// A blank value counts as unset, so the default is pi, as in the pi-space command.
+		command: env.PI_SPACES_COMMAND?.trim() || "pi",
+	};
+}
+
+/** Sets PI_SPACE (removed in the base home), PI_SPACE_HOME and PI_SPACES_COMMAND. */
+export function exportSpaceInfo(env: Env, info: SpaceInfo): void {
+	if (info.space === undefined) delete env.PI_SPACE;
+	else env.PI_SPACE = info.space;
+	env.PI_SPACE_HOME = info.home;
+	env.PI_SPACES_COMMAND = info.command;
+}
+
+/** The system prompt section that tells the model where it runs. */
+export function spacePrompt(info: SpaceInfo): string {
+	const where = info.space === undefined
+		? "This Pi runs in the base home, outside any space."
+		: `This Pi runs in the space "${info.space}" (PI_SPACE).`;
+	const home = `Agent home: ${info.home} (PI_SPACE_HOME).`;
+	const start = `\`${info.command} --space <name>\` starts it in a space`;
+	const manage = "`/space` lists, creates, removes and switches spaces";
+	const command = `Command that starts Pi: ${info.command} (PI_SPACES_COMMAND); ${start}, and ${manage}.`;
+	return [where, home, command].join("\n");
+}
+
+/** The part of a run's structured prompt options this package writes. */
+export interface PromptSections {
+	sections?: Record<string, string>;
+}
+
+/**
+ * Sets the <pi_space> section in a run's structured prompt options, creating the section map when
+ * it is missing and replacing an earlier pi_space section. Other sections and the rest of the
+ * prompt are left alone. Without structured options (an older Pi) nothing is added; the
+ * environment still has the facts.
+ */
+export function addSpaceSection(options: PromptSections | undefined, info: SpaceInfo): void {
+	if (options === undefined) return;
+	options.sections ??= {};
+	options.sections.pi_space = spacePrompt(info);
+}

package/src/relaunch.ts

@@ -123,10 +123,14 @@ export function relaunchCommand(proc: Proc = process, args: string[] = filterArg
 
 const SPACE_FLAG_ERROR = "--space needs a space name: pi --space <name>.";
 
-/** Finds --space <name> or --space=<name> before "--", and returns the other arguments unchanged. */
-export function parseSpaceFlag(args: string[]): { name: string | undefined; rest: string[] } | { error: string } {
+/**
+ * Finds --space <name> or --space=<name> before "--", and returns the other arguments unchanged,
+ * and the arguments that follow the name.
+ */
+export function parseSpaceFlag(args: string[]): { name: string | undefined; rest: string[]; afterName: string[] } | { error: string } {
 	const rest: string[] = [];
 	let name: string | undefined;
+	let afterName: string[] = [];
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (arg === "--") {
@@ -138,36 +142,48 @@ export function parseSpaceFlag(args: string[]): { name: string | undefined; rest
 			if (value === undefined || value === "" || value.startsWith("-")) return { error: SPACE_FLAG_ERROR };
 			name = value;
 			i++;
+			afterName = args.slice(i + 1);
 		} else if (arg.startsWith("--space=")) {
 			name = arg.slice("--space=".length);
 			if (name === "") return { error: SPACE_FLAG_ERROR };
+			afterName = args.slice(i + 1);
 		} else {
 			rest.push(arg);
 		}
 	}
-	return { name, rest };
+	return { name, rest, afterName };
 }
 
+// Pi runs these only as its first argument, before extensions load.
+const PACKAGE_COMMANDS = new Set(["install", "remove", "uninstall", "update", "list"]);
+
 export type StartupPlan = { kind: "none" } | { kind: "error"; message: string } | { kind: "relaunch"; command: Command; env: Env };
 
 /**
  * What `pi --space <name>` does at startup: nothing without the flag or when Pi already runs in that
  * space; otherwise run Pi again in the space with every other argument, since nothing has run yet.
+ * `pi --space <name> <package command> ...` always runs Pi again, even in the current home, because
+ * Pi runs a package command (install, remove, uninstall, update, list) only as its first argument.
  */
 export function planStartup(input: { proc: Proc; dir: string; currentHome: string; env: Env }): StartupPlan {
 	const { proc, dir, currentHome, env } = input;
 	const parsed = parseSpaceFlag(proc.argv.slice(2));
 	if ("error" in parsed) return { kind: "error", message: parsed.error };
 	if (parsed.name === undefined) return { kind: "none" };
+	// A package command runs alone: options before --space (a launcher may add its own) are for a session.
+	const packageCommand = PACKAGE_COMMANDS.has(parsed.afterName[0] ?? "");
+	const args = packageCommand ? parsed.afterName : parsed.rest;
 	let target: SwitchTarget;
 	try {
 		target = resolveSwitch({ dir, name: parsed.name, currentHome, env });
 	} catch (error) {
 		if (!(error instanceof SpaceError)) throw error;
-		if (error.message.startsWith("Already in")) return { kind: "none" };
+		if (error.message.startsWith("Already in")) {
+			return packageCommand ? { kind: "relaunch", command: relaunchCommand(proc, args), env } : { kind: "none" };
+		}
 		return { kind: "error", message: error.message };
 	}
-	return { kind: "relaunch", command: relaunchCommand(proc, parsed.rest), env: relaunchEnv(env, { ...target, currentHome }) };
+	return { kind: "relaunch", command: relaunchCommand(proc, args), env: relaunchEnv(env, { ...target, currentHome }) };
 }
 
 /** Runs the command now with inherited stdio and returns its exit code (1 when it cannot start). */

package/src/spaces.ts

@@ -37,9 +37,13 @@ export function spacesDir(env: Env = process.env, home: string = osHomedir()): s
 	return join(dirname(resolve(baseHome)), "spaces");
 }
 
+// The words of the pi-space and /space commands, so a space name never reads as one.
+const COMMANDS = new Set(["list", "new", "remove", "rename", "switch", "update", "install", "uninstall"]);
+
 /** Returns the error message for an unusable name, or undefined when the name is valid. */
 export function validateName(name: string): string | undefined {
 	if (name === BASE) return `"${BASE}" is reserved for the home Pi started with.`;
+	if (COMMANDS.has(name)) return `"${name}" is reserved: it is a pi-space or /space command.`;
 	if (!NAME.test(name)) {
 		return `Invalid space name "${name}": use lowercase letters, digits, "-" and "_", starting with a letter or digit (at most 64 characters).`;
 	}