@jals1212/pi-spaces 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,52 @@ commands and options and a patch version fixes.
 
 ## Unreleased
 
+## 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
+
+- `/space remove` asks, after the confirmation, whether to keep a backup:
+  the space moves to `.backups/<name>-<UTC time>` in the spaces folder, and
+  keeping one is the first choice. `--yes` keeps a backup, and `--no-backup`
+  deletes without one. `backupSpace` and `BACKUPS` in the core do it, with the
+  same checks as `removeSpace`.
+
+### Changed
+
+- `/space remove <name> --yes` now keeps a backup instead of deleting the
+  space; add `--no-backup` to delete it as before.
+
+### Fixed
+
+- `/space new` copies a local path that loads another copy of this package
+  (a folder whose `package.json` is named `@jals1212/pi-spaces`) instead of
+  writing the folder of the copy that runs.
+- `/space remove` and `backupSpace` report a backup that cannot be written
+  (for example a read-only spaces folder) as an error that says the space was
+  not removed and offers `--no-backup`, instead of a raw filesystem error.
+- `findOwnDeclaration` takes an optional fallback, answered when nothing
+  matches, and an empty package folder matches a local path only by its
+  `package.json` name.
+
 ## 0.1.1
 
 ### Changed

package/README.md

@@ -45,6 +45,8 @@ 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                                # pick from a numbered list (optional CLI)
 ```
 
@@ -60,10 +62,10 @@ A new space starts empty except for a `settings.json` that declares this package
 | `/space switch <name>` | Restarts Pi in that space. `base` is the home Pi started with. |
 | `/space switch` | Same as `/space`. |
 | `/space rename <old> <new>` | Renames a space. The active space cannot be renamed. |
-| `/space remove <name>` | Deletes a space after asking. `--yes` skips the question; it is required without a dialog (print and JSON modes). |
+| `/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. |
 
-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.
 
@@ -71,7 +73,7 @@ Choosing an argument such as `switch` from the `/space ` suggestions only fills
 
 ## 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, and `pi-space list` lists them. `PI_SPACES_COMMAND` makes it run another program that runs Pi. 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, `PI_SPACES_COMMAND` 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 --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.
 
 ## Configuration reference
 
@@ -97,6 +99,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,17 +137,19 @@ Pi reads its agent home once, when it starts, so a running session cannot move t
 
 ## 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 deletes its folder; nothing else is written outside it.
+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` and `/space rename` refuse:
+`/space remove`, `/space rename` and `pi-space --remove` refuse, before they ask:
 
 - `base` and the active space;
 - symlinks, and anything that is not a real folder directly inside the spaces folder;
 - a space that holds the current or base home;
 - a spaces folder that is the filesystem root, your home folder, or the agent home (or inside it).
 
+A backup also needs `.backups` to be a real folder, not a symlink or a file.
+
 ## Development
 
 Two packages live in this repository: the Pi extension and its shared core at the root (`@jals1212/pi-spaces`), and the `pi-space` command in `cli/` (`@jals1212/pi-spaces-cli`).

package/dist/command.js

@@ -1,9 +1,24 @@
 // The /space command, kept apart from Pi's extension API so it can be tested directly.
 import { join } from "node:path";
 import {               relaunchEnv, resolveSwitch } from "./relaunch.js";
-import { activeSpace, BASE, checkRemovable, createSpace,           listSpaces,                          removeSpace, renameSpace, SpaceError } from "./spaces.js";
+import {
+	activeSpace,
+	BACKUPS,
+	BASE,
+	backupSpace,
+	checkRemovable,
+	createSpace,
+	         
+	listSpaces,
+	                        
+	removeSpace,
+	renameSpace,
+	SpaceError,
+} from "./spaces.js";
 
-export const USAGE = "Usage: /space [list | new <name> | remove <name> | rename <old> <new> | switch [<name>]]";
+export const USAGE = "Usage: /space [list | new <name> | remove <name> [--yes] [--no-backup] | rename <old> <new> | switch [<name>]]";
+const KEEP_BACKUP = "Keep a backup";
+const NO_BACKUP = "Delete without a backup";
 const SUBCOMMANDS = ["list", "new", "remove", "rename", "switch"];
 
                                       
@@ -43,9 +58,8 @@ export async function runSpaceCommand(args        , deps                  )
 			ctx.ui.notify(`Created space "${rest[0]}" at ${path}. Enter it with /space switch ${rest[0]}.`, "info");
 			return;
 		}
-		if (sub === "remove" && (rest.length === 1 || (rest.length === 2 && rest[1] === "--yes"))) {
-			return await remove(rest[0], rest[1] === "--yes", deps);
-		}
+		const removal = sub === "remove" ? parseRemove(rest) : undefined;
+		if (removal) return await remove(removal, deps);
 		if (sub === "rename" && rest.length === 2) {
 			renameSpace(deps.dir, rest[0], rest[1], deps.currentHome(), protectedHomes(deps));
 			ctx.ui.notify(`Renamed space "${rest[0]}" to "${rest[1]}".`, "info");
@@ -69,8 +83,24 @@ function list(deps                  )       {
 	deps.ctx.ui.notify(lines.join("\n"), "info");
 }
 
-async function remove(name        , yes         , deps                  )                {
+                   
+	             
+	             
+	                
+ 
+
+/** remove <name> with --yes and --no-backup after it, each at most once, in any order. */
+function parseRemove(rest          )                      {
+	const [name, ...flags] = rest;
+	if (name === undefined || name.startsWith("-")) return undefined;
+	if (flags.some((flag) => flag !== "--yes" && flag !== "--no-backup") || new Set(flags).size !== flags.length) return undefined;
+	return { name, yes: flags.includes("--yes"), backup: !flags.includes("--no-backup") };
+}
+
+/** Without --yes it asks to remove, then (without --no-backup) whether to keep a backup, keeping one first in the list. */
+async function remove({ name, yes, backup }         , deps                  )                {
 	const { ctx } = deps;
+	let keep = backup;
 	if (!yes) {
 		if (!ctx.hasUI) throw new SpaceError(`Removing a space needs confirmation; run /space remove ${name} --yes.`);
 		// Fail before asking when the space cannot be removed anyway.
@@ -79,10 +109,18 @@ async function remove(name        , yes         , deps                  )
 			`Remove space "${name}"?`,
 			`This deletes ${join(deps.dir, name)} and everything in it: sign-ins, packages, settings and sessions.`,
 		);
-		if (!ok) {
+		const choice = ok && backup ? await ctx.ui.select(`Keep a backup of "${name}" in ${join(deps.dir, BACKUPS)}?`, [KEEP_BACKUP, NO_BACKUP]) : undefined;
+		// Dismissing the backup question is not an answer to it, so nothing is removed.
+		if (!ok || (backup && choice === undefined)) {
 			ctx.ui.notify(`Kept space "${name}".`, "info");
 			return;
 		}
+		keep = backup && choice === KEEP_BACKUP;
+	}
+	if (keep) {
+		const path = backupSpace(deps.dir, name, deps.currentHome(), protectedHomes(deps));
+		ctx.ui.notify(`Removed space "${name}"; its backup is ${path}.`, "info");
+		return;
 	}
 	removeSpace(deps.dir, name, deps.currentHome(), protectedHomes(deps));
 	ctx.ui.notify(`Removed space "${name}".`, "info");
@@ -119,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/spaces.js

@@ -149,6 +149,48 @@ export function removeSpace(dir        , name        , agentHome        , protec
 	rmSync(checkRemovable(dir, name, agentHome, protect, userHome), { recursive: true, force: true });
 }
 
+/** The folder inside the spaces folder that holds removed spaces; its leading dot keeps it from being a space. */
+export const BACKUPS = ".backups";
+
+/**
+ * Removes a space by moving it to <spaces folder>/.backups/<name>-<UTC time>, after checkRemovable.
+ * Returns the backup's path. A second backup in the same second gets a number; nothing is overwritten.
+ */
+export function backupSpace(
+	dir        ,
+	name        ,
+	agentHome        ,
+	protect           = [],
+	userHome         = osHomedir(),
+	now       = new Date(),
+)         {
+	const from = checkRemovable(dir, name, agentHome, protect, userHome);
+	const folder = join(dir, BACKUPS);
+	if ((existsSync(folder) || isSymlink(folder)) && !isRealFolder(folder)) {
+		throw new SpaceError(`The backups folder ${folder} is not a folder; move it away and try again.`);
+	}
+	try {
+		mkdirSync(folder, { recursive: true });
+	} catch (error) {
+		throw backupFailed(name, error);
+	}
+	const stamp = `${now.toISOString().slice(0, 19).replaceAll(":", "-")}Z`;
+	let to = join(folder, `${name}-${stamp}`);
+	for (let n = 2; existsSync(to) || isSymlink(to); n++) to = join(folder, `${name}-${stamp}-${n}`);
+	// Inside the spaces folder, so the same filesystem: a rename, never a copy.
+	try {
+		renameSync(from, to);
+	} catch (error) {
+		throw backupFailed(name, error);
+	}
+	return to;
+}
+
+function backupFailed(name        , error         )             {
+	const reason = error instanceof Error ? error.message : String(error);
+	return new SpaceError(`Could not back up space "${name}": ${reason}. The space was not removed; fix that, or remove it without a backup with --no-backup.`);
+}
+
 /** Renames a space after the same safety checks as removal. The new name must be free. */
 export function renameSpace(dir        , oldName        , newName        , agentHome        , protect           = [], userHome         = osHomedir())       {
 	assertName(oldName);
@@ -174,22 +216,39 @@ function gitRepoName(source        )         {
 	return withoutRef.replace(/\.git$/, "").split(/[/:]/).pop() ?? "";
 }
 
+/** The name in a local package folder's package.json, or undefined when there is none. */
+function localPackageName(folder        )                     {
+	try {
+		const name = JSON.parse(readFileSync(join(folder, "package.json"), "utf8"))?.name;
+		return typeof name === "string" ? name : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 function samePath(a        , b        )          {
 	return realOrResolved(a) === realOrResolved(b);
 }
 
 /**
  * This package's declaration in the current home's settings.json, so a new space loads it the same way.
- * A local path is made absolute. Without a match (for example when loaded with -e), the package folder itself.
+ * A local path matches when it is the package folder or another folder whose package.json has this package's name,
+ * and is made absolute. Without a match (for example when loaded with -e), the fallback, which is the package folder itself
+ * unless given. An empty packageRoot (unknown folder) matches a local path only by its package.json name.
  */
-export function findOwnDeclaration(agentHome        , packageName        , packageRoot        )                     {
+export function findOwnDeclaration(
+	agentHome        ,
+	packageName        ,
+	packageRoot        ,
+	fallback                     = packageRoot,
+)                     {
 	let packages         ;
 	try {
 		packages = JSON.parse(readFileSync(join(agentHome, "settings.json"), "utf8"))?.packages;
 	} catch {
-		return packageRoot;
+		return fallback;
 	}
-	if (!Array.isArray(packages)) return packageRoot;
+	if (!Array.isArray(packages)) return fallback;
 	const repo = packageName.split("/").pop() ?? packageName;
 	for (const entry of packages) {
 		const source = typeof entry === "string" ? entry : typeof entry?.source === "string" ? entry.source : undefined;
@@ -199,11 +258,11 @@ export function findOwnDeclaration(agentHome        , packageName        , packa
 			if (npmName(source) === packageName) match = source;
 		} else if (isLocalSource(source)) {
 			const absolute = isAbsolute(source) ? source : resolve(agentHome, expandTilde(source, osHomedir()));
-			if (samePath(absolute, packageRoot)) match = absolute;
+			if ((packageRoot !== "" && samePath(absolute, packageRoot)) || localPackageName(absolute) === packageName) match = absolute;
 		} else if (gitRepoName(source) === repo) {
 			match = source;
 		}
 		if (match !== undefined) return typeof entry === "string" ? match : { ...entry, source: match };
 	}
-	return packageRoot;
+	return fallback;
 }

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.1.1",
+  "version": "0.3.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,48 @@
+---
+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. Know which Pi space this session runs in, its home and start command, and how spaces are listed, created, 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` |
+
+Names: lowercase letters, digits, `-` and `_`, starting with a letter or digit, at most 64 characters; `base` is reserved for the base home.
+
+## 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

@@ -1,9 +1,24 @@
 // The /space command, kept apart from Pi's extension API so it can be tested directly.
 import { join } from "node:path";
 import { type Command, relaunchEnv, resolveSwitch } from "./relaunch.ts";
-import { activeSpace, BASE, checkRemovable, createSpace, type Env, listSpaces, type PackageDeclaration, removeSpace, renameSpace, SpaceError } from "./spaces.ts";
+import {
+	activeSpace,
+	BACKUPS,
+	BASE,
+	backupSpace,
+	checkRemovable,
+	createSpace,
+	type Env,
+	listSpaces,
+	type PackageDeclaration,
+	removeSpace,
+	renameSpace,
+	SpaceError,
+} from "./spaces.ts";
 
-export const USAGE = "Usage: /space [list | new <name> | remove <name> | rename <old> <new> | switch [<name>]]";
+export const USAGE = "Usage: /space [list | new <name> | remove <name> [--yes] [--no-backup] | rename <old> <new> | switch [<name>]]";
+const KEEP_BACKUP = "Keep a backup";
+const NO_BACKUP = "Delete without a backup";
 const SUBCOMMANDS = ["list", "new", "remove", "rename", "switch"];
 
 export interface SpaceCommandContext {
@@ -43,9 +58,8 @@ export async function runSpaceCommand(args: string, deps: SpaceCommandDeps): Pro
 			ctx.ui.notify(`Created space "${rest[0]}" at ${path}. Enter it with /space switch ${rest[0]}.`, "info");
 			return;
 		}
-		if (sub === "remove" && (rest.length === 1 || (rest.length === 2 && rest[1] === "--yes"))) {
-			return await remove(rest[0], rest[1] === "--yes", deps);
-		}
+		const removal = sub === "remove" ? parseRemove(rest) : undefined;
+		if (removal) return await remove(removal, deps);
 		if (sub === "rename" && rest.length === 2) {
 			renameSpace(deps.dir, rest[0], rest[1], deps.currentHome(), protectedHomes(deps));
 			ctx.ui.notify(`Renamed space "${rest[0]}" to "${rest[1]}".`, "info");
@@ -69,8 +83,24 @@ function list(deps: SpaceCommandDeps): void {
 	deps.ctx.ui.notify(lines.join("\n"), "info");
 }
 
-async function remove(name: string, yes: boolean, deps: SpaceCommandDeps): Promise<void> {
+interface Removal {
+	name: string;
+	yes: boolean;
+	backup: boolean;
+}
+
+/** remove <name> with --yes and --no-backup after it, each at most once, in any order. */
+function parseRemove(rest: string[]): Removal | undefined {
+	const [name, ...flags] = rest;
+	if (name === undefined || name.startsWith("-")) return undefined;
+	if (flags.some((flag) => flag !== "--yes" && flag !== "--no-backup") || new Set(flags).size !== flags.length) return undefined;
+	return { name, yes: flags.includes("--yes"), backup: !flags.includes("--no-backup") };
+}
+
+/** Without --yes it asks to remove, then (without --no-backup) whether to keep a backup, keeping one first in the list. */
+async function remove({ name, yes, backup }: Removal, deps: SpaceCommandDeps): Promise<void> {
 	const { ctx } = deps;
+	let keep = backup;
 	if (!yes) {
 		if (!ctx.hasUI) throw new SpaceError(`Removing a space needs confirmation; run /space remove ${name} --yes.`);
 		// Fail before asking when the space cannot be removed anyway.
@@ -79,10 +109,18 @@ async function remove(name: string, yes: boolean, deps: SpaceCommandDeps): Promi
 			`Remove space "${name}"?`,
 			`This deletes ${join(deps.dir, name)} and everything in it: sign-ins, packages, settings and sessions.`,
 		);
-		if (!ok) {
+		const choice = ok && backup ? await ctx.ui.select(`Keep a backup of "${name}" in ${join(deps.dir, BACKUPS)}?`, [KEEP_BACKUP, NO_BACKUP]) : undefined;
+		// Dismissing the backup question is not an answer to it, so nothing is removed.
+		if (!ok || (backup && choice === undefined)) {
 			ctx.ui.notify(`Kept space "${name}".`, "info");
 			return;
 		}
+		keep = backup && choice === KEEP_BACKUP;
+	}
+	if (keep) {
+		const path = backupSpace(deps.dir, name, deps.currentHome(), protectedHomes(deps));
+		ctx.ui.notify(`Removed space "${name}"; its backup is ${path}.`, "info");
+		return;
 	}
 	removeSpace(deps.dir, name, deps.currentHome(), protectedHomes(deps));
 	ctx.ui.notify(`Removed space "${name}".`, "info");
@@ -119,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/spaces.ts

@@ -149,6 +149,48 @@ export function removeSpace(dir: string, name: string, agentHome: string, protec
 	rmSync(checkRemovable(dir, name, agentHome, protect, userHome), { recursive: true, force: true });
 }
 
+/** The folder inside the spaces folder that holds removed spaces; its leading dot keeps it from being a space. */
+export const BACKUPS = ".backups";
+
+/**
+ * Removes a space by moving it to <spaces folder>/.backups/<name>-<UTC time>, after checkRemovable.
+ * Returns the backup's path. A second backup in the same second gets a number; nothing is overwritten.
+ */
+export function backupSpace(
+	dir: string,
+	name: string,
+	agentHome: string,
+	protect: string[] = [],
+	userHome: string = osHomedir(),
+	now: Date = new Date(),
+): string {
+	const from = checkRemovable(dir, name, agentHome, protect, userHome);
+	const folder = join(dir, BACKUPS);
+	if ((existsSync(folder) || isSymlink(folder)) && !isRealFolder(folder)) {
+		throw new SpaceError(`The backups folder ${folder} is not a folder; move it away and try again.`);
+	}
+	try {
+		mkdirSync(folder, { recursive: true });
+	} catch (error) {
+		throw backupFailed(name, error);
+	}
+	const stamp = `${now.toISOString().slice(0, 19).replaceAll(":", "-")}Z`;
+	let to = join(folder, `${name}-${stamp}`);
+	for (let n = 2; existsSync(to) || isSymlink(to); n++) to = join(folder, `${name}-${stamp}-${n}`);
+	// Inside the spaces folder, so the same filesystem: a rename, never a copy.
+	try {
+		renameSync(from, to);
+	} catch (error) {
+		throw backupFailed(name, error);
+	}
+	return to;
+}
+
+function backupFailed(name: string, error: unknown): SpaceError {
+	const reason = error instanceof Error ? error.message : String(error);
+	return new SpaceError(`Could not back up space "${name}": ${reason}. The space was not removed; fix that, or remove it without a backup with --no-backup.`);
+}
+
 /** Renames a space after the same safety checks as removal. The new name must be free. */
 export function renameSpace(dir: string, oldName: string, newName: string, agentHome: string, protect: string[] = [], userHome: string = osHomedir()): void {
 	assertName(oldName);
@@ -174,22 +216,39 @@ function gitRepoName(source: string): string {
 	return withoutRef.replace(/\.git$/, "").split(/[/:]/).pop() ?? "";
 }
 
+/** The name in a local package folder's package.json, or undefined when there is none. */
+function localPackageName(folder: string): string | undefined {
+	try {
+		const name = JSON.parse(readFileSync(join(folder, "package.json"), "utf8"))?.name;
+		return typeof name === "string" ? name : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
 function samePath(a: string, b: string): boolean {
 	return realOrResolved(a) === realOrResolved(b);
 }
 
 /**
  * This package's declaration in the current home's settings.json, so a new space loads it the same way.
- * A local path is made absolute. Without a match (for example when loaded with -e), the package folder itself.
+ * A local path matches when it is the package folder or another folder whose package.json has this package's name,
+ * and is made absolute. Without a match (for example when loaded with -e), the fallback, which is the package folder itself
+ * unless given. An empty packageRoot (unknown folder) matches a local path only by its package.json name.
  */
-export function findOwnDeclaration(agentHome: string, packageName: string, packageRoot: string): PackageDeclaration {
+export function findOwnDeclaration(
+	agentHome: string,
+	packageName: string,
+	packageRoot: string,
+	fallback: PackageDeclaration = packageRoot,
+): PackageDeclaration {
 	let packages: unknown;
 	try {
 		packages = JSON.parse(readFileSync(join(agentHome, "settings.json"), "utf8"))?.packages;
 	} catch {
-		return packageRoot;
+		return fallback;
 	}
-	if (!Array.isArray(packages)) return packageRoot;
+	if (!Array.isArray(packages)) return fallback;
 	const repo = packageName.split("/").pop() ?? packageName;
 	for (const entry of packages) {
 		const source = typeof entry === "string" ? entry : typeof entry?.source === "string" ? entry.source : undefined;
@@ -199,11 +258,11 @@ export function findOwnDeclaration(agentHome: string, packageName: string, packa
 			if (npmName(source) === packageName) match = source;
 		} else if (isLocalSource(source)) {
 			const absolute = isAbsolute(source) ? source : resolve(agentHome, expandTilde(source, osHomedir()));
-			if (samePath(absolute, packageRoot)) match = absolute;
+			if ((packageRoot !== "" && samePath(absolute, packageRoot)) || localPackageName(absolute) === packageName) match = absolute;
 		} else if (gitRepoName(source) === repo) {
 			match = source;
 		}
 		if (match !== undefined) return typeof entry === "string" ? match : { ...entry, source: match };
 	}
-	return packageRoot;
+	return fallback;
 }