@ivotoby/postgram-cli 1.39.0 → 1.40.0

package/README.md

@@ -123,20 +123,81 @@ expand when the compact result already answers a direct fact.
 
 ## Workspace tracking
 
-Track features, machines, workspaces and agent sessions across worktrees:
+Track features, machines, workspaces and agent sessions across worktrees.
+For onboarding and daily use, see [docs/workspace-tracking.md](../docs/workspace-tracking.md).
 
 ```bash
 pgm here                       # report the current workspace and session
 pgm hooks install              # install the Claude Code hooks (--pi installs the pi extension)
 pgm hooks uninstall            # remove the installed hooks
-pgm where                      # features and workspaces grouped by stage
+pgm where                      # features and workspaces grouped by stage, one summary per feature (--expand lists every workspace, --all includes done and released)
 pgm feature add "my feature"   # create a feature (also: stage, pr, link, unlink)
+pgm feature done 1234abcd      # mark the feature task done; pgm where hides it unless --all
+pgm feature sync [1234abcd]    # update PR states from GitHub with gh and apply the stage rules
 pgm machine set --alias codebox # set this machine's alias or connect target (also: pgm machine list)
 pgm repo set <remote> --release-on-merge true|false  # record the repository for this worktree
 pgm worktree new 1234abcd      # create a worktree for a feature (UUID, 8-hex short id or title; --create creates the feature)
 pgm scan --root ~/src          # discover worktrees and record their features (needs --root <dir> or scan_roots; --yes-exact, --dry-run)
+pgm scan --json                # read-only inventory for agents: one entry per worktree, nothing is sent
+pgm scan --apply plan.json     # apply an approved plan (--dry-run validates and shows the result only)
+pgm worktree rm <path>         # remove a clean, pushed worktree and unregister it (no force flag)
+pgm workspace prune            # remove registrations of this machine whose directory is gone (--dry-run, --ignored)
 ```
 
+The interactive `pgm scan` needs a terminal. Without one it exits with a
+message that points to `--json`, `--apply` and `--yes-exact`.
+
+### Scan inventory and plan
+
+`pgm scan --json` prints:
+
+```json
+{
+  "machine": "codebox",
+  "generated_at": "2026-11-01T10:00:00.000Z",
+  "roots": ["/home/me/workspace"],
+  "worktrees": [
+    {
+      "path": "/home/me/workspace/app.worktrees/1a2b3c4d-kw-rank",
+      "repo_remote": "git@github.com:owner/app.git",
+      "branch": "feat/1a2b3c4d-kw-rank",
+      "last_commit": { "date": "2026-10-30T09:12:00+00:00", "subject": "fix: ranking" },
+      "git": { "dirty_count": 0, "unpushed_count": 1, "has_upstream": true },
+      "workspace_id": null,
+      "feature": null,
+      "marker_feature_id": null,
+      "sessions": { "count": 2, "last_activity_at": "2026-10-30T10:00:00.000Z" },
+      "candidates": [
+        { "kind": "short-id", "feature_id": "1a2b3c4d-...", "title": "Keyword rank fusion" }
+      ]
+    }
+  ]
+}
+```
+
+`feature` is the link Postgram already has. `candidates` (marker, short-id,
+search) are only computed for worktrees without a link. `git` is `null` when
+git timed out (then `note` says so).
+
+`pgm scan --apply plan.json` takes one entry per worktree path:
+
+```json
+{
+  "entries": [
+    { "path": "/home/me/workspace/app.worktrees/1a2b3c4d-kw-rank", "action": "link", "feature_id": "1a2b3c4d" },
+    { "path": "/home/me/workspace/app.worktrees/spike", "action": "create", "title": "Spike: new cache" },
+    { "path": "/home/me/workspace/app.worktrees/old", "action": "skip" }
+  ]
+}
+```
+
+The whole plan is validated before anything is written: paths must be
+absolute, unique, existing worktree roots outside `ignore_paths`; `link` needs
+a feature id (UUID or 8-hex) that exists; `create` needs a title. One invalid
+entry rejects the plan. Entries then run one by one and the result lists
+`linked`, `created`, `skipped` or `failed` per path (exit code 1 when any
+failed). With `--json` the result is `{ "results": [...], "failed": n }`.
+
 New `~/.pgmrc` keys (read alongside `api_url`/`api_key`):
 
 | Key | Default |
@@ -145,6 +206,7 @@ New `~/.pgmrc` keys (read alongside `api_url`/`api_key`):
 | `scan_roots` | `[]` |
 | `worktree_root` | `null` (meaning `<repo_root>.worktrees`) |
 | `here_timeout_ms` | `2000` |
+| `ignore_paths` | `[]`. Directories `pgm here`, the hooks and `pgm scan` skip. An entry matches that directory exactly; an entry ending in `/**` matches everything below it. `~` is expanded. Example: `["~/workspace"]` skips the workspace root but not the repos in it. |
 | `resume` | per-agent-kind `with_id`/`without_id` command templates |
 
 ## Memory Roles

package/dist/pgm.js

@@ -13,6 +13,7 @@ import { registerHereCommand } from './tracking/here.js';
 import { registerHooksCommands } from './tracking/hooks.js';
 import { registerScanCommand } from './tracking/scan.js';
 import { registerWhereCommand } from './tracking/where.js';
+import { registerWorkspaceCommands } from './tracking/workspace-commands.js';
 import { registerWorktreeCommand } from './tracking/worktree.js';
 import { buildSyncManifest } from './sync-walk.js';
 import { compactEdgeResponse, compactEntityListResponse, compactGraphResponse, compactSearchResponse, compactStoredEntityResponse, entityListResponseToToon, graphResponseToToon, searchResponseToToon } from './search-output.js';
@@ -920,4 +921,5 @@ registerWhereCommand(program);
 registerFeatureCommands(program);
 registerWorktreeCommand(program);
 registerScanCommand(program);
+registerWorkspaceCommands(program);
 await program.parseAsync(process.argv);

package/dist/tracking/api.js

@@ -25,6 +25,9 @@ export function createTrackingClient(options) {
         patchWorkspace(id, body) {
             return request(options, `/api/workspaces/${encodeURIComponent(id)}`, { method: 'PATCH', body });
         },
+        deleteWorkspace(id) {
+            return request(options, `/api/workspaces/${encodeURIComponent(id)}`, { method: 'DELETE' });
+        },
         putMachine(alias, connectTarget) {
             return request(options, `/api/machines/${encodeURIComponent(alias)}`, { method: 'PUT', body: { connect_target: connectTarget } });
         },

package/dist/tracking/config.js

@@ -35,6 +35,23 @@ export function expandHome(value, homeDir) {
     }
     return value;
 }
+function trimTrailingSlashes(value) {
+    return value.length > 1 ? value.replace(/\/+$/, '') || '/' : value;
+}
+/**
+ * An entry matches that directory exactly. An entry ending in `/**` matches
+ * everything below the directory, but not the directory itself.
+ */
+export function isIgnoredPath(target, ignorePaths) {
+    const candidate = trimTrailingSlashes(target);
+    return ignorePaths.some((entry) => {
+        if (entry.endsWith('/**')) {
+            const base = trimTrailingSlashes(entry.slice(0, -3));
+            return candidate.startsWith(base === '/' ? '/' : `${base}/`);
+        }
+        return candidate === trimTrailingSlashes(entry);
+    });
+}
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -68,6 +85,14 @@ export function parseTrackingConfig(raw, input) {
     const hereTimeoutMs = typeof timeout === 'number' && Number.isFinite(timeout) && timeout > 0
         ? timeout
         : 2000;
+    const ignorePaths = [];
+    if (isRecord(raw) && Array.isArray(raw.ignore_paths)) {
+        for (const entry of raw.ignore_paths) {
+            if (typeof entry === 'string' && entry !== '') {
+                ignorePaths.push(expandHome(entry, input.homeDir));
+            }
+        }
+    }
     const resume = cloneResume(DEFAULT_RESUME);
     const rawResume = isRecord(raw) && isRecord(raw.resume) ? raw.resume : {};
     for (const kind of AGENT_KINDS) {
@@ -83,7 +108,15 @@ export function parseTrackingConfig(raw, input) {
             resume[kind].without_id = kindConfig.without_id;
         }
     }
-    return { alias, connectTarget, scanRoots, worktreeRoot, hereTimeoutMs, resume };
+    return {
+        alias,
+        connectTarget,
+        scanRoots,
+        worktreeRoot,
+        hereTimeoutMs,
+        ignorePaths,
+        resume
+    };
 }
 export async function loadTrackingConfig(input) {
     const homeDir = input?.homeDir ?? os.homedir();

package/dist/tracking/feature-commands.js

@@ -6,6 +6,7 @@ import { parseCommaList, shortId } from '../shared.js';
 import { runTrackingCommand } from './api.js';
 import { UsageError, usageExit, writeMachineConfig } from './config.js';
 import { readBootId, removeMarker, resolveLocalWorkspace, writeMarker } from './local.js';
+import { formatSync, runFeatureSync, runGhPrState } from './feature-sync.js';
 import { FEATURE_STAGES } from './types.js';
 export async function runFeatureAdd(title, options, deps) {
     const tags = parseCommaList(options.tags);
@@ -25,6 +26,54 @@ export async function runFeatureStage(id, stage, deps) {
         ? response
         : [`${shortId(response.entity.id)} ${response.previous_stage ?? '-'} → ${stage}`];
 }
+const FULL_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHORT_HEX = /^[0-9a-f]{8}$/i;
+async function resolveTaskId(id, deps) {
+    if (FULL_UUID.test(id)) {
+        return id.toLowerCase();
+    }
+    if (!SHORT_HEX.test(id)) {
+        throw new UsageError('feature id must be a full UUID or an 8-hex short id');
+    }
+    const prefix = id.toLowerCase();
+    const matches = [];
+    for (let offset = 0;; offset += 100) {
+        const page = await deps.pgm.listTasks({ limit: 100, offset });
+        for (const item of page.items) {
+            if (item.id.startsWith(prefix)) {
+                matches.push(item.id);
+            }
+        }
+        if (page.items.length < 100) {
+            break;
+        }
+    }
+    if (matches.length > 1) {
+        throw new AppError(ErrorCode.CONFLICT, `feature id ${id} is ambiguous`);
+    }
+    const [match] = matches;
+    if (match === undefined) {
+        throw new AppError(ErrorCode.NOT_FOUND, `no feature matches ${id}`);
+    }
+    return match;
+}
+/**
+ * Marks the feature's task done. `pgm where` already hides done tasks unless
+ * --all is given, so a feature needs no stage of its own for this.
+ */
+export async function runFeatureDone(id, deps) {
+    const taskId = await resolveTaskId(id, deps);
+    const current = await deps.pgm.recallEntity(taskId);
+    if (current.entity.status === 'done') {
+        return deps.json
+            ? { id: taskId, status: 'done', changed: false }
+            : [`${shortId(taskId)} already done`];
+    }
+    const completed = await deps.pgm.completeTask(taskId, current.entity.version);
+    return deps.json
+        ? { id: taskId, status: completed.entity.status, changed: true }
+        : [`${shortId(taskId)} done`];
+}
 const PR_STATES = ['open', 'merged', 'closed'];
 export async function runFeaturePr(id, url, options, deps) {
     const state = options.state ?? 'open';
@@ -185,6 +234,27 @@ export function registerFeatureCommands(program) {
         .option('--state <state>', 'open, merged or closed', 'open')).action(async (id, url, options, command) => {
         await runTrackingCommand(command, (context) => runFeaturePr(id, url, options, featureDeps(context)));
     });
+    usageExit(feature
+        .command('done')
+        .description('Mark a feature done so pgm where hides it (pgm where --all shows it)')
+        .argument('<id>', 'feature id (UUID or 8-hex)')).action(async (id, _options, command) => {
+        await runTrackingCommand(command, (context) => runFeatureDone(id, { pgm: context.pgm, json: context.json }));
+    });
+    usageExit(feature
+        .command('sync')
+        .description('Update PR states from GitHub (needs gh) and apply the stage rules')
+        .argument('[id]', 'only this feature (UUID or 8-hex)')).action(async (id, _options, command) => {
+        await runTrackingCommand(command, async (context) => {
+            const result = await runFeatureSync(id, {
+                client: context.client,
+                gh: (url) => runGhPrState(url)
+            });
+            if (result.errors.length > 0) {
+                process.exitCode = 1;
+            }
+            return context.json ? result : formatSync(result);
+        });
+    });
     usageExit(feature
         .command('link')
         .description('Link a workspace to a feature')

package/dist/tracking/feature-sync.js

@@ -0,0 +1,151 @@
+// cli/src/tracking/feature-sync.ts: pgm feature sync — follow GitHub PR state.
+import { execFile } from 'node:child_process';
+import { AppError, ErrorCode } from '../errors.js';
+import { shortId } from '../shared.js';
+import { UsageError } from './config.js';
+const GH_STATES = {
+    OPEN: 'open',
+    MERGED: 'merged',
+    CLOSED: 'closed'
+};
+export function parseGhState(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const state = parsed.state;
+    return typeof state === 'string' ? (GH_STATES[state] ?? null) : null;
+}
+export function classifyGhFailure(error) {
+    const stderr = error.stderr ?? '';
+    if (error.code === 'ENOENT') {
+        return { ok: false, kind: 'missing', message: 'gh is not installed' };
+    }
+    if (/gh auth login|not logged in|not logged into|authentication/i.test(stderr)) {
+        return { ok: false, kind: 'unauthenticated', message: 'gh is not logged in' };
+    }
+    const first = stderr.split('\n').find((line) => line.trim() !== '');
+    return { ok: false, kind: 'error', message: first?.trim() ?? 'gh failed' };
+}
+const defaultExec = (cmd, args) => new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 20_000 }, (error, stdout, stderr) => {
+        if (error !== null) {
+            reject(Object.assign(error, { stderr }));
+        }
+        else {
+            resolve({ stdout });
+        }
+    });
+});
+export async function runGhPrState(url, exec = defaultExec) {
+    let stdout;
+    try {
+        ({ stdout } = await exec('gh', ['pr', 'view', url, '--json', 'state']));
+    }
+    catch (error) {
+        const failure = error;
+        return classifyGhFailure({ code: failure.code, stderr: failure.stderr });
+    }
+    const state = parseGhState(stdout);
+    return state === null
+        ? { ok: false, kind: 'error', message: 'unexpected output from gh pr view' }
+        : { ok: true, state };
+}
+function collectFeatures(response) {
+    const features = [];
+    for (const group of response.groups) {
+        if ('features' in group) {
+            features.push(...group.features);
+        }
+    }
+    return features;
+}
+/**
+ * Asks gh for the state of every PR that is not merged yet and sends changes
+ * through the feature PR endpoint, so the server's derived-stage rules apply.
+ * A merged PR is final and is not asked again.
+ */
+export async function runFeatureSync(id, deps) {
+    const response = await deps.client.where(id === undefined
+        ? { view: 'stage' }
+        : { view: 'stage', includeReleased: true, includeDone: true });
+    let features = collectFeatures(response);
+    if (id !== undefined) {
+        const wanted = id.toLowerCase();
+        features = features.filter((feature) => feature.id === wanted || feature.id.startsWith(wanted));
+        if (features.length === 0) {
+            throw new AppError(ErrorCode.NOT_FOUND, `no feature matches ${id}`);
+        }
+    }
+    const result = { checked: 0, unchanged: 0, changed: [], errors: [] };
+    const answers = new Map();
+    for (const feature of features) {
+        for (const pull of feature.pull_requests) {
+            if (pull.state === 'merged') {
+                continue;
+            }
+            let answer = answers.get(pull.url);
+            if (answer === undefined) {
+                answer = await deps.gh(pull.url);
+                answers.set(pull.url, answer);
+            }
+            if (!answer.ok && answer.kind === 'missing') {
+                throw new UsageError('gh (GitHub CLI) was not found on PATH. Install it from https://cli.github.com to use `pgm feature sync`.');
+            }
+            if (!answer.ok && answer.kind === 'unauthenticated') {
+                throw new UsageError('gh is not logged in. Run `gh auth login`, then retry `pgm feature sync`.');
+            }
+            result.checked += 1;
+            if (!answer.ok) {
+                result.errors.push({
+                    feature_id: feature.id,
+                    url: pull.url,
+                    error: answer.message
+                });
+                continue;
+            }
+            if (answer.state === pull.state) {
+                result.unchanged += 1;
+                continue;
+            }
+            try {
+                const updated = await deps.client.addPullRequest(feature.id, {
+                    url: pull.url,
+                    state: answer.state
+                });
+                result.changed.push({
+                    feature_id: feature.id,
+                    url: pull.url,
+                    from: pull.state,
+                    to: answer.state,
+                    stage_from: updated.from,
+                    stage_to: updated.to
+                });
+            }
+            catch (error) {
+                result.errors.push({
+                    feature_id: feature.id,
+                    url: pull.url,
+                    error: error instanceof Error ? error.message : 'update failed'
+                });
+            }
+        }
+    }
+    return result;
+}
+export function formatSync(result) {
+    const lines = result.changed.map((change) => `${shortId(change.feature_id)} ${change.url} ${change.from} → ${change.to}${change.stage_from !== change.stage_to
+        ? `, stage ${change.stage_from} → ${change.stage_to}`
+        : ''}`);
+    for (const error of result.errors) {
+        lines.push(`error ${shortId(error.feature_id)} ${error.url}: ${error.error}`);
+    }
+    lines.push(`checked ${result.checked} pull requests: ${result.changed.length} changed, ${result.unchanged} unchanged, ${result.errors.length} failed`);
+    return lines;
+}

package/dist/tracking/here.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { readStdinText, resolvePgmConfig, shortId } from '../shared.js';
 import { createTrackingClient } from './api.js';
-import { loadTrackingConfig, usageExit } from './config.js';
+import { isIgnoredPath, loadTrackingConfig, usageExit } from './config.js';
 import { readBootId, readMarker, resolveLocalWorkspace } from './local.js';
 import { AGENT_KINDS } from './types.js';
 const HOOK_EVENTS = {
@@ -79,6 +79,12 @@ function asSessionEvent(value) {
 function featureLine(feature) {
     return `Postgram: this worktree belongs to feature ${shortId(feature.id)} "${feature.title}" (stage: ${feature.stage ?? 'building'}).`;
 }
+function ignoredResult(options, target) {
+    return {
+        stdout: options.hook ? '' : `ignored ${target} (ignore_paths)\n`,
+        exitCode: 0
+    };
+}
 export async function runHere(options, deps) {
     let agent;
     let sessionId;
@@ -125,6 +131,10 @@ export async function runHere(options, deps) {
         return { stdout: '', exitCode: 0 };
     }
     const config = deps.config;
+    // Checked before any git call so an ignored directory costs nothing.
+    if (isIgnoredPath(cwd, config.ignorePaths)) {
+        return ignoredResult(options, cwd);
+    }
     if (deps.client === null) {
         await deps.log('missing credentials');
         return { stdout: '', exitCode: 0 };
@@ -136,6 +146,9 @@ export async function runHere(options, deps) {
         await deps.log('git timeout');
         return { stdout: '', exitCode: 0 };
     }
+    if (isIgnoredPath(local.path, config.ignorePaths)) {
+        return ignoredResult(options, local.path);
+    }
     const marker = await deps.readMarker(local.path);
     const bootId = await deps.bootId();
     const session = sessionId !== null || event !== null

package/dist/tracking/scan.js

@@ -1,12 +1,13 @@
 // cli/src/tracking/scan.ts: pgm scan — discover worktrees and record their features.
 import { existsSync } from 'node:fs';
+import { readFile, realpath } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import readline from 'node:readline';
 import { shortId } from '../shared.js';
 import { runTrackingCommand } from './api.js';
-import { slug, usageExit, UsageError } from './config.js';
-import { readMarker, resolveLocalWorkspace, writeMarker } from './local.js';
+import { expandHome, isIgnoredPath, slug, usageExit, UsageError } from './config.js';
+import { readMarker, resolveLocalWorkspace, runGit, writeMarker } from './local.js';
 import { discoverWorktrees, findClaudeSessions, findPiSessions } from './scan-discovery.js';
 import { syncMissing } from './where.js';
 export const BRANCH_SHORT_ID = /(?:^|\/)([0-9a-f]{8})(?:-|$)/;
@@ -69,13 +70,51 @@ function sessionsFor(worktree, claude, pi) {
         ...(pi.get(worktree.path) ?? [])
     ];
 }
-export async function runScan(options, deps) {
+function scanRoots(options, deps) {
     const roots = options.root.length > 0
         ? options.root.map((root) => path.resolve(root))
         : deps.config.scanRoots;
     if (roots.length === 0) {
         throw new UsageError('no scan roots: pass --root <dir> or set scan_roots in ~/.pgmrc');
     }
+    return roots;
+}
+async function discoverNotIgnored(roots, depth, deps) {
+    const worktrees = await deps.discover(roots, depth);
+    return worktrees.filter((worktree) => !isIgnoredPath(worktree.path, deps.config.ignorePaths));
+}
+async function findSessions(paths, deps) {
+    const claudeDir = deps.env.CLAUDE_CONFIG_DIR ?? path.join(deps.homeDir, '.claude');
+    const piDir = deps.env.PI_CODING_AGENT_DIR ?? path.join(deps.homeDir, '.pi', 'agent');
+    const claude = await deps.claudeSessions(paths, claudeDir);
+    for (const note of claude.notes) {
+        deps.info(note);
+    }
+    const pi = await deps.piSessions(paths, piDir);
+    return { claude: claude.sessions, pi };
+}
+async function recordLocal(local, featureId, sessions, deps) {
+    const body = {
+        source: 'scan',
+        machine: {
+            alias: deps.config.alias,
+            hostname: deps.hostname,
+            boot_id: null
+        },
+        workspace: local.workspace,
+        feature_id: featureId,
+        sessions
+    };
+    await deps.client.report(body);
+    if ((await deps.readMarker(local.path)) !== featureId) {
+        await deps.writeMarker(local.path, featureId);
+    }
+}
+export async function runScan(options, deps) {
+    if (!options.yesExact && !deps.isTty()) {
+        throw new UsageError('pgm scan needs a terminal for its interactive flow. Without one, use `pgm scan --json` to list worktrees, `pgm scan --apply <plan.json>` to apply a plan, or `pgm scan --yes-exact`.');
+    }
+    const roots = scanRoots(options, deps);
     const depth = parseDepth(options.depth);
     const knownResponse = await deps.client.listWorkspaces({
         machine: deps.config.alias
@@ -88,15 +127,8 @@ export async function runScan(options, deps) {
         });
     }
     const known = new Set(knownResponse.workspaces.map((workspace) => workspace.path));
-    const worktrees = await deps.discover(roots, depth);
-    const paths = worktrees.map((worktree) => worktree.path);
-    const claudeDir = deps.env.CLAUDE_CONFIG_DIR ?? path.join(deps.homeDir, '.claude');
-    const piDir = deps.env.PI_CODING_AGENT_DIR ?? path.join(deps.homeDir, '.pi', 'agent');
-    const claude = await deps.claudeSessions(paths, claudeDir);
-    for (const note of claude.notes) {
-        deps.info(note);
-    }
-    const pi = await deps.piSessions(paths, piDir);
+    const worktrees = await discoverNotIgnored(roots, depth, deps);
+    const { claude, pi } = await findSessions(worktrees.map((worktree) => worktree.path), deps);
     const tasks = await deps.tasks();
     const lines = [];
     for (const worktree of worktrees) {
@@ -158,25 +190,264 @@ export async function runScan(options, deps) {
             lines.push(`skipped ${worktree.path} (git timeout)`);
             continue;
         }
-        const body = {
-            source: 'scan',
-            machine: {
-                alias: deps.config.alias,
-                hostname: deps.hostname,
-                boot_id: null
-            },
-            workspace: local.workspace,
-            feature_id: id,
-            sessions: sessionsFor(worktree, claude.sessions, pi)
-        };
-        await deps.client.report(body);
-        if ((await deps.readMarker(worktree.path)) !== id) {
-            await deps.writeMarker(worktree.path, id);
-        }
+        await recordLocal(local, id, sessionsFor(worktree, claude, pi), deps);
         lines.push(`recorded ${worktree.path} → ${shortId(id)}`);
     }
     return lines;
 }
+const INVENTORY_CONCURRENCY = 6;
+function sessionSummary(sessions) {
+    if (sessions.length === 0) {
+        return null;
+    }
+    let latest = '';
+    for (const session of sessions) {
+        const observed = session.observed_at ?? '';
+        if (observed > latest) {
+            latest = observed;
+        }
+    }
+    return { count: sessions.length, last_activity_at: latest };
+}
+/** Read-only: lists what is on disk and what Postgram knows. Sends nothing. */
+export async function runScanInventory(options, deps) {
+    const roots = scanRoots(options, deps);
+    const depth = parseDepth(options.depth);
+    const known = new Map((await deps.client.listWorkspaces({ machine: deps.config.alias })).workspaces.map((workspace) => [workspace.path, workspace]));
+    const worktrees = await discoverNotIgnored(roots, depth, deps);
+    const { claude, pi } = await findSessions(worktrees.map((worktree) => worktree.path), deps);
+    const tasks = await deps.tasks();
+    const titleFor = (id) => tasks.find((task) => task.id === id)?.title ?? '';
+    const describe = async (worktree) => {
+        const [local, lastCommit] = await Promise.all([
+            deps.resolveWorkspace(worktree.path),
+            deps.lastCommit(worktree.path)
+        ]);
+        const workspace = known.get(worktree.path) ?? null;
+        const linkedId = workspace?.feature_id ?? null;
+        const marker = await deps.readMarker(worktree.path);
+        const candidates = (linkedId === null
+            ? await buildProposals(worktree, deps, tasks, false)
+            : []).map((proposal) => ({
+            kind: proposal.kind,
+            feature_id: proposal.featureId,
+            title: proposal.title
+        }));
+        const entry = {
+            path: worktree.path,
+            repo_remote: local.kind === 'ok'
+                ? (local.workspace.repo_remote ?? workspace?.repo_remote ?? null)
+                : (workspace?.repo_remote ?? null),
+            branch: local.kind === 'ok'
+                ? (local.workspace.branch ?? worktree.branch)
+                : worktree.branch,
+            last_commit: lastCommit,
+            git: local.kind === 'ok' ? (local.workspace.git ?? null) : null,
+            workspace_id: workspace?.id ?? null,
+            feature: linkedId !== null ? { id: linkedId, title: titleFor(linkedId) } : null,
+            marker_feature_id: marker,
+            sessions: sessionSummary(sessionsFor(worktree, claude, pi)),
+            candidates
+        };
+        if (local.kind === 'timeout') {
+            entry.note = 'git timeout';
+        }
+        return entry;
+    };
+    const entries = [];
+    for (let i = 0; i < worktrees.length; i += INVENTORY_CONCURRENCY) {
+        entries.push(...(await Promise.all(worktrees.slice(i, i + INVENTORY_CONCURRENCY).map(describe))));
+    }
+    return {
+        machine: deps.config.alias,
+        generated_at: new Date().toISOString(),
+        roots,
+        worktrees: entries
+    };
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHORT_ID_RE = /^[0-9a-f]{8}$/i;
+function isRecordValue(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function resolveTaskId(raw, tasks) {
+    const lower = raw.toLowerCase();
+    let hits = [];
+    if (UUID_RE.test(lower)) {
+        hits = tasks.filter((task) => task.id === lower);
+    }
+    else if (SHORT_ID_RE.test(lower)) {
+        hits = tasks.filter((task) => task.id.startsWith(lower));
+    }
+    const hit = hits[0];
+    if (hit === undefined) {
+        return { error: `no feature matches ${raw}` };
+    }
+    if (hits.length > 1) {
+        return { error: `feature id ${raw} is ambiguous` };
+    }
+    return { id: hit.id };
+}
+/** Validates the whole plan; nothing is written while this runs. */
+async function validatePlan(plan, deps) {
+    const rawEntries = Array.isArray(plan)
+        ? plan
+        : isRecordValue(plan) && Array.isArray(plan.entries)
+            ? plan.entries
+            : null;
+    if (rawEntries === null) {
+        throw new UsageError('plan must be {"entries": [...]} or a JSON array of entries');
+    }
+    const tasks = await deps.tasks();
+    const errors = [];
+    const valid = [];
+    const seen = new Set();
+    for (const [index, raw] of rawEntries.entries()) {
+        if (!isRecordValue(raw) || typeof raw.path !== 'string' || raw.path === '') {
+            errors.push(`entry ${index + 1}: path is required`);
+            continue;
+        }
+        const expanded = expandHome(raw.path, deps.homeDir);
+        if (!path.isAbsolute(expanded)) {
+            errors.push(`${raw.path}: path must be absolute`);
+            continue;
+        }
+        const target = path.resolve(expanded);
+        if (seen.has(target)) {
+            errors.push(`duplicate path ${target}`);
+            continue;
+        }
+        seen.add(target);
+        const action = raw.action;
+        if (action === 'skip') {
+            valid.push({ entry: { path: target, action: 'skip' } });
+            continue;
+        }
+        let item;
+        if (action === 'link') {
+            if (typeof raw.feature_id !== 'string' || raw.feature_id === '') {
+                errors.push(`${target}: link needs feature_id`);
+                continue;
+            }
+            const resolved = resolveTaskId(raw.feature_id, tasks);
+            if ('error' in resolved) {
+                errors.push(`${target}: ${resolved.error}`);
+                continue;
+            }
+            item = {
+                entry: { path: target, action: 'link', feature_id: raw.feature_id },
+                featureId: resolved.id
+            };
+        }
+        else if (action === 'create') {
+            const title = typeof raw.title === 'string' ? raw.title.trim() : '';
+            if (title === '') {
+                errors.push(`${target}: create needs a non-empty title`);
+                continue;
+            }
+            item = { entry: { path: target, action: 'create', title } };
+        }
+        else {
+            errors.push(`${target}: unknown action '${String(action)}'`);
+            continue;
+        }
+        if (isIgnoredPath(target, deps.config.ignorePaths)) {
+            errors.push(`${target}: path is in ignore_paths`);
+            continue;
+        }
+        if (!deps.exists(target)) {
+            errors.push(`${target}: path does not exist`);
+            continue;
+        }
+        const local = await deps.resolveWorkspace(target);
+        if (local.kind === 'timeout') {
+            errors.push(`${target}: git timed out`);
+            continue;
+        }
+        if (local.repoRoot === null) {
+            errors.push(`${target}: not a git worktree`);
+            continue;
+        }
+        if (local.path !== (await deps.realpath(target))) {
+            errors.push(`${target}: not the root of a worktree (${local.path})`);
+            continue;
+        }
+        if (isIgnoredPath(local.path, deps.config.ignorePaths)) {
+            errors.push(`${target}: path is in ignore_paths`);
+            continue;
+        }
+        valid.push({ ...item, local });
+    }
+    if (errors.length > 0) {
+        throw new UsageError(`plan rejected, nothing was written:\n${errors.map((line) => `  ${line}`).join('\n')}`);
+    }
+    return valid;
+}
+export async function runScanApply(plan, options, deps) {
+    const valid = await validatePlan(plan, deps);
+    const paths = valid
+        .filter((item) => item.entry.action !== 'skip')
+        .map((item) => item.entry.path);
+    const sessions = options.dryRun || paths.length === 0
+        ? { claude: new Map(), pi: new Map() }
+        : await findSessions(paths, deps);
+    const results = [];
+    for (const item of valid) {
+        const { entry } = item;
+        if (entry.action === 'skip') {
+            results.push({ path: entry.path, action: 'skip', status: 'skipped' });
+            continue;
+        }
+        if (options.dryRun) {
+            results.push({
+                path: entry.path,
+                action: entry.action,
+                status: entry.action === 'link' ? 'would link' : 'would create',
+                ...(item.featureId !== undefined ? { feature_id: item.featureId } : {})
+            });
+            continue;
+        }
+        let featureId = item.featureId;
+        try {
+            if (entry.action === 'create') {
+                const created = await deps.client.createFeature({ content: entry.title });
+                featureId = created.entity.id;
+            }
+            if (featureId === undefined || item.local === undefined) {
+                throw new Error('internal: unresolved plan entry');
+            }
+            await recordLocal(item.local, featureId, sessionsFor({ path: entry.path, branch: null }, sessions.claude, sessions.pi), deps);
+            results.push({
+                path: entry.path,
+                action: entry.action,
+                status: entry.action === 'link' ? 'linked' : 'created',
+                feature_id: featureId
+            });
+        }
+        catch (error) {
+            results.push({
+                path: entry.path,
+                action: entry.action,
+                status: 'failed',
+                ...(featureId !== undefined ? { feature_id: featureId } : {}),
+                error: error instanceof Error ? error.message : 'unknown error'
+            });
+        }
+    }
+    return {
+        results,
+        failed: results.filter((result) => result.status === 'failed').length
+    };
+}
+export function formatApplyResults(results) {
+    return results.map((result) => {
+        const target = result.feature_id !== undefined ? ` → ${shortId(result.feature_id)}` : '';
+        if (result.status === 'failed') {
+            return `failed ${result.path}${target}: ${result.error ?? 'unknown error'}`;
+        }
+        return `${result.status} ${result.path}${target}`;
+    });
+}
 function firstLineTitle(content) {
     return (content ?? '').split('\n')[0]?.trim() ?? '';
 }
@@ -203,6 +474,21 @@ function askLine(question) {
         rl.on('SIGINT', () => finish(''));
     });
 }
+async function readPlan(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        throw new UsageError(`cannot read plan ${file}: ${error instanceof Error ? error.message : 'read failed'}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new UsageError(`plan ${file} is not valid JSON: ${error instanceof Error ? error.message : 'parse failed'}`);
+    }
+}
 export function registerScanCommand(program) {
     const command = usageExit(program
         .command('scan')
@@ -210,52 +496,84 @@ export function registerScanCommand(program) {
         .option('--root <dir>', 'scan root (repeatable)', collectRoot, [])
         .option('--depth <n>', `directory depth below each root (default ${DEFAULT_DEPTH})`)
         .option('--yes-exact', 'accept marker and short-id proposals, skip the rest')
-        .option('--dry-run', 'show what would be recorded without sending')).action(async () => {
+        .option('--dry-run', 'show what would be recorded without sending')
+        .option('--apply <plan.json>', 'apply an approved plan (link, create or skip per worktree path)')).action(async () => {
         const opts = command.opts();
-        await runTrackingCommand(command, (context) => runScan({
-            root: opts.root ?? [],
-            ...(opts.depth !== undefined ? { depth: opts.depth } : {}),
-            yesExact: opts.yesExact === true,
-            dryRun: opts.dryRun === true
-        }, {
-            client: context.client,
-            config: context.config,
-            hostname: os.hostname(),
-            env: process.env,
-            homeDir: context.homeDir,
-            tasks: async () => {
-                const items = [];
-                for (let offset = 0;; offset += 100) {
-                    const page = await context.pgm.listTasks({ limit: 100, offset });
-                    for (const item of page.items) {
-                        items.push({ id: item.id, title: firstLineTitle(item.content) });
+        await runTrackingCommand(command, async (context) => {
+            const scanOptions = {
+                root: opts.root ?? [],
+                ...(opts.depth !== undefined ? { depth: opts.depth } : {}),
+                yesExact: opts.yesExact === true,
+                dryRun: opts.dryRun === true
+            };
+            if (opts.apply !== undefined && scanOptions.yesExact) {
+                throw new UsageError('--apply cannot be combined with --yes-exact');
+            }
+            const deps = {
+                client: context.client,
+                config: context.config,
+                hostname: os.hostname(),
+                env: process.env,
+                homeDir: context.homeDir,
+                tasks: async () => {
+                    const items = [];
+                    for (let offset = 0;; offset += 100) {
+                        const page = await context.pgm.listTasks({ limit: 100, offset });
+                        for (const item of page.items) {
+                            items.push({ id: item.id, title: firstLineTitle(item.content) });
+                        }
+                        if (page.items.length < 100) {
+                            break;
+                        }
                     }
-                    if (page.items.length < 100) {
-                        break;
+                    return items;
+                },
+                search: async (query) => {
+                    const response = await context.pgm.searchEntities({
+                        query,
+                        type: 'task',
+                        limit: 3
+                    });
+                    return response.results.map((result) => ({
+                        id: result.entity.id,
+                        title: firstLineTitle(result.entity.content)
+                    }));
+                },
+                ask: askLine,
+                discover: discoverWorktrees,
+                claudeSessions: findClaudeSessions,
+                piSessions: findPiSessions,
+                resolveWorkspace: (p) => resolveLocalWorkspace(p),
+                readMarker,
+                writeMarker: (worktree, featureId) => writeMarker(worktree, featureId, new Date()),
+                exists: existsSync,
+                isTty: () => process.stdin.isTTY === true,
+                realpath: (p) => realpath(p),
+                lastCommit: async (worktree) => {
+                    const result = await runGit(['log', '-1', '--format=%cI%n%s'], {
+                        cwd: worktree,
+                        timeoutMs: 5000
+                    });
+                    if (!result.ok || result.stdout === '') {
+                        return null;
                     }
+                    const [date = '', ...subject] = result.stdout.split('\n');
+                    return { date, subject: subject.join('\n') };
+                },
+                info: (line) => process.stderr.write(`${line}\n`)
+            };
+            if (opts.apply !== undefined) {
+                const plan = await readPlan(opts.apply);
+                const applied = await runScanApply(plan, { dryRun: scanOptions.dryRun }, deps);
+                if (applied.failed > 0) {
+                    process.exitCode = 1;
                 }
-                return items;
-            },
-            search: async (query) => {
-                const response = await context.pgm.searchEntities({
-                    query,
-                    type: 'task',
-                    limit: 3
-                });
-                return response.results.map((result) => ({
-                    id: result.entity.id,
-                    title: firstLineTitle(result.entity.content)
-                }));
-            },
-            ask: askLine,
-            discover: discoverWorktrees,
-            claudeSessions: findClaudeSessions,
-            piSessions: findPiSessions,
-            resolveWorkspace: (p) => resolveLocalWorkspace(p),
-            readMarker,
-            writeMarker: (worktree, featureId) => writeMarker(worktree, featureId, new Date()),
-            exists: existsSync,
-            info: (line) => process.stderr.write(`${line}\n`)
-        }));
+                return context.json ? applied : formatApplyResults(applied.results);
+            }
+            if (context.json && !scanOptions.yesExact) {
+                return runScanInventory(scanOptions, deps);
+            }
+            return runScan(scanOptions, deps);
+        });
     });
 }

package/dist/tracking/where.js

@@ -105,9 +105,33 @@ export function augmentWhere(response, input) {
     });
     return { ...response, groups };
 }
-const CUT_WIDTH = 60;
-function cut(line) {
-    return line.length > CUT_WIDTH ? `${line.slice(0, CUT_WIDTH - 1)}…` : line;
+const PATH_WIDTH = 70;
+/**
+ * Home-relative for local workspaces. A path that is still too long loses its
+ * leading segments, never its end: the end is what tells worktrees apart.
+ */
+function displayPath(workspace, input) {
+    let shown = workspace.path;
+    const home = input.homeDir;
+    if (home !== undefined &&
+        workspace.machine === input.localAlias &&
+        (shown === home || shown.startsWith(`${home}/`))) {
+        shown = `~${shown.slice(home.length)}`;
+    }
+    if (shown.length <= PATH_WIDTH) {
+        return shown;
+    }
+    const segments = shown.split('/');
+    let tail = segments.pop() ?? '';
+    while (segments.length > 1) {
+        const next = segments[segments.length - 1] ?? '';
+        if (`…/${next}/${tail}`.length > PATH_WIDTH) {
+            break;
+        }
+        tail = `${next}/${tail}`;
+        segments.pop();
+    }
+    return `…/${tail}`;
 }
 function workspaceLines(workspace, input) {
     const risks = displayRisks(workspace, input).map((risk) => riskText(risk, workspace));
@@ -138,13 +162,49 @@ function workspaceLines(workspace, input) {
         })
             .join(', ');
     }
-    const line2 = `  ${workspace.path}  git ${gitAge}  ${sessions}`;
+    const line2 = `  ${displayPath(workspace, input)}  git ${gitAge}  ${sessions}`;
     const resume = renderResume(workspace, {
         localAlias: input.localAlias,
         templates: input.templates,
         transcriptGone: transcriptGone(workspace, input)
     });
-    return [cut(line1), cut(line2), `  resume: ${resume}`];
+    return [line1, line2, `  resume: ${resume}`];
+}
+function riskLabels(workspace, input) {
+    return displayRisks(workspace, input).map((risk) => riskText(risk, workspace));
+}
+function latestWorkspace(workspaces) {
+    let latest = null;
+    for (const workspace of workspaces) {
+        if (latest === null ||
+            Date.parse(workspace.last_activity_at) > Date.parse(latest.last_activity_at)) {
+            latest = workspace;
+        }
+    }
+    return latest;
+}
+function compactFeatureLines(workspaces, input) {
+    const withRisks = workspaces.filter((workspace) => displayRisks(workspace, input).length > 0).length;
+    const latest = latestWorkspace(workspaces);
+    const lines = [
+        `  ${workspaces.length} workspaces, ${withRisks} with risks (--expand lists them)`
+    ];
+    if (latest !== null) {
+        lines.push(`  latest: ${latest.machine}  ${latest.branch ?? '-'}  ${displayPath(latest, input)}  ${formatAge(latest.last_activity_at, input.now)}`, `  resume: ${renderResume(latest, {
+            localAlias: input.localAlias,
+            templates: input.templates,
+            transcriptGone: transcriptGone(latest, input)
+        })}`);
+    }
+    return lines;
+}
+function compactWorkspaceLine(workspace, input) {
+    const parts = [displayPath(workspace, input), workspace.machine, workspace.branch ?? '-'];
+    const risks = riskLabels(workspace, input);
+    if (risks.length > 0) {
+        parts.push(risks.join(' '));
+    }
+    return `  ${parts.join('  ')}`;
 }
 export function renderWhere(response, input) {
     const lines = [];
@@ -159,8 +219,13 @@ export function renderWhere(response, input) {
                     .map((pullRequest) => ` PR:${pullRequest.state}`)
                     .join('');
                 lines.push(`${shortId(feature.id)} ${feature.title}  [${feature.stage}]${pullRequests}`);
-                for (const workspace of feature.workspaces) {
-                    lines.push(...workspaceLines(workspace, input));
+                if (input.expand === true || feature.workspaces.length <= 1) {
+                    for (const workspace of feature.workspaces) {
+                        lines.push(...workspaceLines(workspace, input));
+                    }
+                }
+                else {
+                    lines.push(...compactFeatureLines(feature.workspaces, input));
                 }
             }
         }
@@ -170,7 +235,12 @@ export function renderWhere(response, input) {
             }
             lines.push(`== ${group.label} (${group.workspaces.length}) ==`);
             for (const workspace of group.workspaces) {
-                lines.push(...workspaceLines(workspace, input));
+                if (input.expand === true || group.workspaces.length <= 1) {
+                    lines.push(...workspaceLines(workspace, input));
+                }
+                else {
+                    lines.push(compactWorkspaceLine(workspace, input));
+                }
             }
         }
     }
@@ -199,7 +269,9 @@ export async function runWhere(options, deps) {
         templates: deps.templates,
         now: deps.now,
         exists: deps.exists,
-        failedIds
+        failedIds,
+        ...(deps.homeDir !== undefined ? { homeDir: deps.homeDir } : {}),
+        ...(options.expand === true ? { expand: true } : {})
     };
     return deps.json ? augmentWhere(response, input) : renderWhere(response, input);
 }
@@ -211,21 +283,24 @@ export function registerWhereCommand(program) {
         .option('--machine <alias>', 'only workspaces on this machine')
         .option('--repo <remote>', 'only workspaces of this repo')
         .option('--all', 'include released and done features')
-        .option('--include-ended', 'include ended sessions')).action(async () => {
+        .option('--include-ended', 'include ended sessions')
+        .option('--expand', 'list every workspace instead of a summary per feature')).action(async () => {
         const opts = command.opts();
         await runTrackingCommand(command, (context) => runWhere({
             actions: opts.actions === true,
             ...(opts.machine !== undefined ? { machine: opts.machine } : {}),
             ...(opts.repo !== undefined ? { repo: opts.repo } : {}),
             all: opts.all === true,
-            includeEnded: opts.includeEnded === true
+            includeEnded: opts.includeEnded === true,
+            expand: opts.expand === true
         }, {
             client: context.client,
             json: context.json,
             localAlias: context.config.alias,
             templates: context.config.resume,
             now: new Date(),
-            exists: existsSync
+            exists: existsSync,
+            homeDir: context.homeDir
         }));
     });
 }

package/dist/tracking/workspace-commands.js

@@ -0,0 +1,94 @@
+// cli/src/tracking/workspace-commands.ts: pgm workspace prune.
+import { existsSync } from 'node:fs';
+import { shortId } from '../shared.js';
+import { runTrackingCommand } from './api.js';
+import { isIgnoredPath, usageExit } from './config.js';
+/**
+ * Removes workspace registrations of this machine whose directory is gone
+ * (and, with `ignored`, those under ignore_paths). Features are never touched.
+ */
+export async function runWorkspacePrune(options, deps) {
+    const { workspaces } = await deps.client.listWorkspaces({
+        machine: deps.config.alias
+    });
+    const result = {
+        removed: [],
+        failed: [],
+        dry_run: options.dryRun
+    };
+    for (const workspace of workspaces) {
+        if (workspace.machine !== deps.config.alias) {
+            continue;
+        }
+        let reason = null;
+        if (!deps.exists(workspace.path)) {
+            reason = 'missing';
+        }
+        else if (options.ignored === true &&
+            isIgnoredPath(workspace.path, deps.config.ignorePaths)) {
+            reason = 'ignored';
+        }
+        if (reason === null) {
+            continue;
+        }
+        if (!options.dryRun) {
+            try {
+                await deps.client.deleteWorkspace(workspace.id);
+            }
+            catch (error) {
+                result.failed.push({
+                    id: workspace.id,
+                    path: workspace.path,
+                    error: error instanceof Error ? error.message : 'delete failed'
+                });
+                continue;
+            }
+        }
+        result.removed.push({
+            id: workspace.id,
+            path: workspace.path,
+            feature_id: workspace.feature_id,
+            reason
+        });
+    }
+    return result;
+}
+export function formatPrune(result) {
+    const verb = result.dry_run ? 'would remove' : 'removed';
+    const lines = result.removed.map((entry) => {
+        const feature = entry.feature_id !== null ? ` (feature ${shortId(entry.feature_id)})` : '';
+        return `${verb} ${entry.path} [${entry.reason}]${feature}`;
+    });
+    for (const entry of result.failed) {
+        lines.push(`failed ${entry.path}: ${entry.error}`);
+    }
+    if (lines.length === 0) {
+        lines.push('nothing to prune');
+    }
+    return lines;
+}
+export function registerWorkspaceCommands(program) {
+    const workspace = usageExit(program.command('workspace').description('Manage workspace registrations'));
+    const prune = usageExit(workspace
+        .command('prune')
+        .description('Remove registrations of this machine whose directory is gone (features are kept)')
+        .option('--dry-run', 'show what would be removed without deleting')
+        .option('--ignored', 'also remove registrations that match ignore_paths in ~/.pgmrc'));
+    prune.action(async () => {
+        const opts = prune.opts();
+        await runTrackingCommand(prune, async (context) => {
+            const result = await runWorkspacePrune({
+                dryRun: opts.dryRun === true,
+                ...(opts.ignored === true ? { ignored: true } : {})
+            }, {
+                client: context.client,
+                config: context.config,
+                exists: existsSync
+            });
+            if (result.failed.length > 0) {
+                process.exitCode = 1;
+            }
+            return context.json ? result : formatPrune(result);
+        });
+    });
+}

package/dist/tracking/worktree.js

@@ -1,5 +1,6 @@
 // cli/src/tracking/worktree.ts: pgm worktree new — create a feature worktree.
 import { existsSync } from 'node:fs';
+import { realpath } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { AppError, ErrorCode } from '../errors.js';
@@ -145,6 +146,69 @@ export async function runWorktreeNew(feature, options, deps) {
     }
     return [worktreePath];
 }
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+/**
+ * Removes a linked worktree only when nothing would be lost: no changed files
+ * and no commits that no remote has. There is no force flag and `git worktree
+ * remove` runs without --force. The workspace registration goes afterwards.
+ */
+export async function runWorktreeRemove(target, deps) {
+    const abs = path.resolve(deps.cwd, target);
+    if (!deps.exists(abs)) {
+        throw new UsageError(`no such directory: ${abs}`);
+    }
+    const local = await deps.resolveWorkspace(abs);
+    if (local.kind === 'timeout') {
+        throw new AppError(ErrorCode.INTERNAL, 'git timed out reading the worktree state; nothing was removed');
+    }
+    if (local.repoRoot === null) {
+        throw new UsageError(`not a git worktree: ${abs}`);
+    }
+    if (local.path !== (await deps.realpath(abs))) {
+        throw new UsageError(`not the root of a worktree: pass ${local.path} instead of ${abs}`);
+    }
+    if (local.repoRoot === local.path) {
+        throw new UsageError(`refusing to remove the main working tree: ${local.path}`);
+    }
+    const git = local.workspace.git ?? null;
+    const reasons = [];
+    if (git === null) {
+        reasons.push('git state is unknown');
+    }
+    else {
+        if (git.dirty_count > 0) {
+            reasons.push(plural(git.dirty_count, 'changed file'));
+        }
+        if (git.unpushed_count > 0) {
+            reasons.push(`${plural(git.unpushed_count, 'unpushed commit')}${git.has_upstream ? '' : ' (no upstream; no remote has them)'}`);
+        }
+    }
+    if (reasons.length > 0) {
+        throw new AppError(ErrorCode.CONFLICT, `refusing to remove ${local.path}: ${reasons.join(', ')}`);
+    }
+    const commonDir = await deps.run(['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: local.path, timeoutMs: GIT_TIMEOUT_MS });
+    if (commonDir.ok === false) {
+        throw new AppError(ErrorCode.INTERNAL, 'could not determine the git common dir');
+    }
+    const removed = await deps.run(['--git-dir', commonDir.stdout, 'worktree', 'remove', local.path], { cwd: local.repoRoot, timeoutMs: GIT_TIMEOUT_MS });
+    if (removed.ok === false) {
+        throw new AppError(ErrorCode.INTERNAL, `git worktree remove failed${removed.timedOut ? ' (timed out)' : ''}; nothing was unregistered`);
+    }
+    let unregistered = false;
+    try {
+        const looked = await deps.client.lookup(deps.config.alias, local.path);
+        if (looked.workspace !== null && looked.workspace.path === local.path) {
+            await deps.client.deleteWorkspace(looked.workspace.id);
+            unregistered = true;
+        }
+    }
+    catch (error) {
+        deps.warn(`worktree removed, but unregistering failed: ${error instanceof Error ? error.message : 'unknown error'}; run \`pgm workspace prune\` later`);
+    }
+    return { path: local.path, removed: true, unregistered };
+}
 async function promptConfirm(question) {
     process.stderr.write(`${question} [y/N] `);
     const answer = (await readStdinText()).trim().toLowerCase();
@@ -160,6 +224,28 @@ export function registerWorktreeCommand(program) {
         .option('--base <ref>', 'base ref for the new branch (default: origin/HEAD or HEAD)')
         .option('--path <dir>', 'worktree path (default: <worktree_root>/<8-hex>-<slug>)')
         .option('--create', 'create the feature when it does not exist'));
+    const removeCommand = usageExit(worktree
+        .command('rm <path>')
+        .description('Remove a clean worktree and unregister it. Refuses when there are changed files or unpushed commits; there is no force flag'));
+    removeCommand.action(async (target) => {
+        await runTrackingCommand(removeCommand, async (context) => {
+            const result = await runWorktreeRemove(target, {
+                client: context.client,
+                config: context.config,
+                cwd: process.cwd(),
+                run: runGit,
+                exists: existsSync,
+                realpath: (p) => realpath(p),
+                resolveWorkspace: (cwd) => resolveLocalWorkspace(cwd, { budgetMs: 5000 }),
+                warn: (line) => process.stderr.write(`${line}\n`)
+            });
+            return context.json
+                ? result
+                : [
+                    `removed ${result.path}${result.unregistered ? ' and unregistered the workspace' : ''}`
+                ];
+        });
+    });
     newCommand.action(async (feature) => {
         const opts = newCommand.opts();
         await runTrackingCommand(newCommand, async (context) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ivotoby/postgram-cli",
-  "version": "1.39.0",
+  "version": "1.40.0",
   "description": "Postgram CLI — store, search, and manage entities from the command line",
   "type": "module",
   "bin": {