@ivotoby/postgram-cli 1.39.0 → 1.40.1

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/client.js

@@ -120,6 +120,9 @@ export function createPgmClient(options) {
         },
         listTasks(input = {}) {
             const params = new URLSearchParams();
+            if (input.kind) {
+                params.set('kind', input.kind);
+            }
             if (input.status) {
                 params.set('status', input.status);
             }

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';
@@ -615,6 +616,7 @@ taskCommand
     await runWithClient(command, async (client, json) => {
         validateToonOptions(options, json);
         const body = await client.listTasks({
+            kind: 'task',
             status: options.status,
             context: options.context,
             limit: Number(options.limit),
@@ -920,4 +922,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,57 @@ 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) && item.metadata.kind === 'feature') {
+                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.metadata.kind !== 'feature') {
+        throw new UsageError(`${shortId(taskId)} is not a feature`);
+    }
+    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 +237,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,159 @@
+// 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 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;
+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();
+        if (!FULL_UUID.test(wanted) && !SHORT_HEX.test(wanted)) {
+            throw new UsageError('feature id must be a full UUID or an 8-hex short id');
+        }
+        features = features.filter((feature) => FULL_UUID.test(wanted) ? feature.id === wanted : feature.id.startsWith(wanted));
+        if (features.length === 0) {
+            throw new AppError(ErrorCode.NOT_FOUND, `no feature matches ${id}`);
+        }
+        if (features.length > 1) {
+            throw new AppError(ErrorCode.CONFLICT, `feature id ${id} is ambiguous`);
+        }
+    }
+    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 ${result.checked === 1 ? 'request' : '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,16 @@ 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);
+    }
+    // A directory outside git holds no project code, so it is never a workspace.
+    if (local.repoRoot === null) {
+        return {
+            stdout: options.hook ? '' : `skipped ${local.path} (not a git repository)\n`,
+            exitCode: 0
+        };
+    }
     const marker = await deps.readMarker(local.path);
     const bootId = await deps.bootId();
     const session = sessionId !== null || event !== null