orbitmap 0.4.6 → 0.6.0

package/dist/list-meta.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The honest half of a list: what the API actually answered, and what it left out.
+ *
+ * Agent API 9.0.0 (IN-nahetc) made every list span every reachable area and every assignee,
+ * paged it with an opaque keyset `cursor`, and put the whole story in `meta`: the grand
+ * `total`, the per-area shown-of-total split, and an `applied_filters` block that is ALWAYS
+ * present — not only when the result is empty or truncated. That last part is the point. A
+ * short list used to be ambiguous between "nothing exists" and "you did not ask for it", and
+ * the reported bug (`orbitmap tasks` showing one area's worth of one agent's work) was
+ * invisible precisely because nothing on screen said what had been filtered out.
+ *
+ * So every list command prints the same three lines under its rows:
+ *
+ * - the **scope** line — the filters that produced this result, spelled out;
+ * - the **truncation** line — `30 of 143 shown across 7 areas`, and how to get the rest;
+ * - the **hint** line — `meta.hint`, when the server noticed the page is mostly one intent.
+ *
+ * Everything here degrades to silence: local mode answers `{count}` and nothing else, and an
+ * older API answers without the new keys. A missing key prints no line rather than a lie.
+ */
+/** One area's contribution to a page: what it showed, and what it holds. */
+export interface PerAreaCount {
+    slug: string | null;
+    shown: number;
+    total: number;
+}
+/** `meta.applied_filters` — the caller's question, echoed back by the server. */
+export interface AppliedFilters {
+    /** `all reachable (7)` or `demo,web (2 of 7)`; null for a list with no area dimension. */
+    areas?: string | null;
+    /** The statuses kept, comma-joined, or `all`. */
+    status?: string | null;
+    /** How many rows the status filter removed. */
+    hidden_by_status?: number;
+    /** `any`, `me`, `unassigned`, or an agent slug. */
+    assignee?: string | null;
+    intent?: string | null;
+    mission?: string | null;
+    limit?: number;
+}
+/** `meta.hint` — the intent nudge. It never reorders or filters rows; it only says a thing. */
+export interface ListHint {
+    type?: string;
+    intent_number?: string;
+    intent_name?: string;
+    count?: number;
+    flag?: string;
+    message?: string;
+}
+/** The list envelope's `meta`, as of API 9.0.0. Every field past `count` is optional. */
+export interface ListMeta {
+    count?: number;
+    total?: number;
+    next_cursor?: string | null;
+    per_area?: PerAreaCount[];
+    applied_filters?: AppliedFilters;
+    scope?: string;
+    workspace?: {
+        id?: string;
+        slug?: string;
+        name?: string;
+    };
+    hint?: ListHint;
+}
+/** The list envelope itself. */
+export interface ListEnvelope<T> {
+    data: T[];
+    meta?: ListMeta;
+}
+/**
+ * The scope line: `applied_filters`, rendered for a human.
+ *
+ * `undefined` when the server said nothing about its filters (local mode, or an API older
+ * than 9.0.0) — silence beats inventing a scope nobody asserted.
+ */
+export declare function formatScopeLine(meta: ListMeta | undefined): string | undefined;
+/**
+ * The truncation line, or `undefined` when the whole result is on screen.
+ *
+ * Driven by `total` vs the rows actually printed, so it is right for a single page AND for
+ * an assembled `--all` run (where `next_cursor` has been followed to null and nothing is
+ * missing any more).
+ */
+export declare function formatTruncationLine(meta: ListMeta | undefined, shown: number): string | undefined;
+/** `meta.hint`'s message, when the server sent one. */
+export declare function formatHintLine(meta: ListMeta | undefined): string | undefined;
+/**
+ * Print the three honest lines under a result, in a fixed order: what was hidden by paging,
+ * what the server noticed, then the scope that produced all of it.
+ *
+ * The hint is printed BETWEEN them rather than woven into the rows on purpose — it must
+ * never reorder or filter what was listed (the provider is explicit about this, and implicit
+ * session scoping was rejected twice on this intent).
+ */
+export declare function printListMeta(meta: ListMeta | undefined, shown: number, log?: (line: string) => void): void;
+/**
+ * The empty answer, with the reason attached: `No tasks. Scope: all 7 reachable areas,
+ * status todo,in_progress (46 hidden, add --status all), assignee any.`
+ *
+ * One line, deliberately: "No tasks." alone is what made the reported bug survive so long.
+ */
+export declare function formatEmptyLine(noun: string, meta: ListMeta | undefined): string;
+/** How many pages `fetchAllPages` will ever ask for, however the server behaves. */
+export declare const MAX_PAGES = 200;
+/**
+ * Follow `meta.next_cursor` until it is null and return the assembled list.
+ *
+ * This is the ONLY way to see a workspace with more rows than the page cap (100) in full —
+ * raising the limit is a bigger number, not an exit. The assembled `meta` keeps the first
+ * page's `total` and `applied_filters` (they describe the whole query, not the page),
+ * reports `count` as everything fetched, recomputes each area's `shown` from the assembled
+ * rows, and clears `next_cursor`, because after this there is genuinely no next page.
+ *
+ * A server that keeps handing back the same cursor, or one that pages forever, is stopped by
+ * {@link MAX_PAGES} rather than hanging the terminal.
+ */
+export declare function fetchAllPages<T>(fetchPage: (cursor?: string) => Promise<ListEnvelope<T>>, areaSlugOf?: (row: T) => string | null | undefined): Promise<ListEnvelope<T>>;

package/dist/list-meta.js

@@ -0,0 +1,160 @@
+/**
+ * The honest half of a list: what the API actually answered, and what it left out.
+ *
+ * Agent API 9.0.0 (IN-nahetc) made every list span every reachable area and every assignee,
+ * paged it with an opaque keyset `cursor`, and put the whole story in `meta`: the grand
+ * `total`, the per-area shown-of-total split, and an `applied_filters` block that is ALWAYS
+ * present — not only when the result is empty or truncated. That last part is the point. A
+ * short list used to be ambiguous between "nothing exists" and "you did not ask for it", and
+ * the reported bug (`orbitmap tasks` showing one area's worth of one agent's work) was
+ * invisible precisely because nothing on screen said what had been filtered out.
+ *
+ * So every list command prints the same three lines under its rows:
+ *
+ * - the **scope** line — the filters that produced this result, spelled out;
+ * - the **truncation** line — `30 of 143 shown across 7 areas`, and how to get the rest;
+ * - the **hint** line — `meta.hint`, when the server noticed the page is mostly one intent.
+ *
+ * Everything here degrades to silence: local mode answers `{count}` and nothing else, and an
+ * older API answers without the new keys. A missing key prints no line rather than a lie.
+ */
+/**
+ * The scope line: `applied_filters`, rendered for a human.
+ *
+ * `undefined` when the server said nothing about its filters (local mode, or an API older
+ * than 9.0.0) — silence beats inventing a scope nobody asserted.
+ */
+export function formatScopeLine(meta) {
+    const filters = meta?.applied_filters;
+    if (!filters)
+        return undefined;
+    const parts = [];
+    if (typeof filters.areas === 'string' && filters.areas !== '') {
+        // `all reachable (7)` reads as a machine field; `all 7 reachable areas` reads as an
+        // answer. An explicit narrowing (`demo,web (2 of 7)`) is already legible, so it is
+        // passed through verbatim — including the count that says how much it hid.
+        const everything = /^all reachable \((\d+)\)$/.exec(filters.areas);
+        parts.push(everything ? `all ${everything[1]} reachable areas` : `areas ${filters.areas}`);
+    }
+    if (typeof filters.status === 'string' && filters.status !== '') {
+        const hidden = filters.hidden_by_status ?? 0;
+        parts.push(hidden > 0
+            ? `status ${filters.status} (${hidden} hidden, add --status all)`
+            : `status ${filters.status}`);
+    }
+    if (typeof filters.assignee === 'string' && filters.assignee !== '') {
+        parts.push(`assignee ${filters.assignee}`);
+    }
+    if (filters.intent)
+        parts.push(`intent ${filters.intent}`);
+    if (filters.mission)
+        parts.push(`mission ${filters.mission}`);
+    if (parts.length === 0)
+        return undefined;
+    return `Scope: ${parts.join(', ')}.`;
+}
+/**
+ * The truncation line, or `undefined` when the whole result is on screen.
+ *
+ * Driven by `total` vs the rows actually printed, so it is right for a single page AND for
+ * an assembled `--all` run (where `next_cursor` has been followed to null and nothing is
+ * missing any more).
+ */
+export function formatTruncationLine(meta, shown) {
+    const total = meta?.total;
+    if (typeof total !== 'number' || shown >= total)
+        return undefined;
+    const areas = meta?.per_area?.length ?? 0;
+    const where = areas > 1 ? ` across ${areas} areas` : '';
+    return `${shown} of ${total} shown${where} — run with --all for every row.`;
+}
+/** `meta.hint`'s message, when the server sent one. */
+export function formatHintLine(meta) {
+    const hint = meta?.hint;
+    if (!hint)
+        return undefined;
+    if (typeof hint.message === 'string' && hint.message !== '')
+        return hint.message;
+    if (typeof hint.flag === 'string' && hint.flag !== '')
+        return `Focus with ${hint.flag}.`;
+    return undefined;
+}
+/**
+ * Print the three honest lines under a result, in a fixed order: what was hidden by paging,
+ * what the server noticed, then the scope that produced all of it.
+ *
+ * The hint is printed BETWEEN them rather than woven into the rows on purpose — it must
+ * never reorder or filter what was listed (the provider is explicit about this, and implicit
+ * session scoping was rejected twice on this intent).
+ */
+export function printListMeta(meta, shown, log = console.log) {
+    const lines = [
+        formatTruncationLine(meta, shown),
+        formatHintLine(meta),
+        formatScopeLine(meta),
+    ].filter((line) => line !== undefined);
+    if (lines.length === 0)
+        return;
+    log('');
+    for (const line of lines)
+        log(line);
+}
+/**
+ * The empty answer, with the reason attached: `No tasks. Scope: all 7 reachable areas,
+ * status todo,in_progress (46 hidden, add --status all), assignee any.`
+ *
+ * One line, deliberately: "No tasks." alone is what made the reported bug survive so long.
+ */
+export function formatEmptyLine(noun, meta) {
+    const scope = formatScopeLine(meta);
+    return scope ? `No ${noun}. ${scope}` : `No ${noun} found.`;
+}
+/** How many pages `fetchAllPages` will ever ask for, however the server behaves. */
+export const MAX_PAGES = 200;
+/**
+ * Follow `meta.next_cursor` until it is null and return the assembled list.
+ *
+ * This is the ONLY way to see a workspace with more rows than the page cap (100) in full —
+ * raising the limit is a bigger number, not an exit. The assembled `meta` keeps the first
+ * page's `total` and `applied_filters` (they describe the whole query, not the page),
+ * reports `count` as everything fetched, recomputes each area's `shown` from the assembled
+ * rows, and clears `next_cursor`, because after this there is genuinely no next page.
+ *
+ * A server that keeps handing back the same cursor, or one that pages forever, is stopped by
+ * {@link MAX_PAGES} rather than hanging the terminal.
+ */
+export async function fetchAllPages(fetchPage, areaSlugOf = () => undefined) {
+    const rows = [];
+    const seenCursors = new Set();
+    let first;
+    let cursor;
+    let pages = 0;
+    do {
+        const page = await fetchPage(cursor);
+        first ??= page;
+        rows.push(...(page.data ?? []));
+        const next = page.meta?.next_cursor;
+        cursor = typeof next === 'string' && next !== '' ? next : undefined;
+        // A repeated cursor means the server is not advancing; taking it again would loop.
+        if (cursor !== undefined && seenCursors.has(cursor))
+            cursor = undefined;
+        if (cursor !== undefined)
+            seenCursors.add(cursor);
+    } while (cursor !== undefined && ++pages < MAX_PAGES);
+    const meta = { ...(first?.meta ?? {}) };
+    meta.count = rows.length;
+    meta.next_cursor = null;
+    if (meta.per_area) {
+        const shown = new Map();
+        for (const row of rows) {
+            const slug = areaSlugOf(row) ?? null;
+            shown.set(slug, (shown.get(slug) ?? 0) + 1);
+        }
+        meta.per_area = meta.per_area.map((entry) => ({
+            ...entry,
+            shown: shown.get(entry.slug) ?? 0,
+        }));
+    }
+    return { data: rows, meta };
+}
+//# sourceMappingURL=list-meta.js.map

package/dist/list-meta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-meta.js","sourceRoot":"","sources":["../src/list-meta.ts"],"names":[],"mappings":"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"}

package/dist/list-options.d.ts

@@ -0,0 +1,33 @@
+/** The sentence every area-scoped list carries: what it spans, and how to narrow it. */
+export declare const LIST_SCOPE_NOTE: string;
+export declare const LIMIT_HELP = "Rows per page (default 30, max 100)";
+export declare const ALL_HELP = "Follow every page to the end and print every row";
+export declare const TASKS_DESCRIPTION: string;
+export declare const ISSUES_DESCRIPTION = "List issues. Spans every area you can reach, not just this directory's \u2014 pass --area <slug[,slug]> to narrow";
+export declare const IDEAS_DESCRIPTION = "List ideas. Spans every area you can reach, not just this directory's \u2014 pass --area <slug[,slug]> to narrow";
+export declare const VIBES_DESCRIPTION = "List vibes. Spans every area you can reach, not just this directory's \u2014 pass --area <slug[,slug]> to narrow";
+export declare const DOCS_DESCRIPTION: string;
+export declare const INTENTS_DESCRIPTION = "List intents \u2014 workspace-wide, every assignee";
+export declare const MISSIONS_DESCRIPTION = "List missions \u2014 workspace-wide, every assignee";
+/** `all` is accepted by every list since API 9.0.0 and is the one spelling of "do not filter". */
+export declare const TASK_STATUS_HELP = "Filter by status (comma-separated, or `all`; default todo,in_progress)";
+export declare const ISSUE_STATUS_HELP = "Filter by status (comma-separated, or `all`; default open,investigating)";
+export declare const IDEA_STATUS_HELP = "Filter by status (comma-separated, or `all`; default pending,accepted)";
+export declare const INTENT_STATUS_HELP = "Filter by status (comma-separated, or `all`; default new,design,plan,build,in_review)";
+export declare const MISSION_STATUS_HELP = "Filter by status (comma-separated, or `all`; default new,active)";
+/**
+ * The commands that accept `--area a,b`, i.e. the ones where an area is a FILTER.
+ *
+ * Everywhere else an area is the write target or the lookup context and exactly one is
+ * required: silently taking the first of several would create an object in an area the caller
+ * did not name — the IS-vse335 failure with extra steps. Names are `command` or
+ * `parent command`, matching how a user types them.
+ */
+export declare const MULTI_AREA_COMMANDS: readonly string[];
+/** `tasks`, or `issue list` — the path a user would type, for the check below. */
+export declare function commandPath(name: string, parent?: string): string;
+/**
+ * Reject `--area a,b` on a command that needs exactly one area, naming what to do instead.
+ * Returns the message, or `undefined` when the invocation is fine.
+ */
+export declare function multiAreaRejection(path: string, area: string | undefined): string | undefined;

package/dist/list-options.js

@@ -0,0 +1,70 @@
+/**
+ * The shared option surface of the list commands (TS-rhpn2n).
+ *
+ * Lives outside `src/index.ts` so it can be read by a test: `index.ts` calls
+ * `program.parse()` at import time, so nothing can import it, and the help text is part of
+ * this deliverable rather than decoration. The `tasks` description used to read "List your
+ * assigned tasks" while the API hard-filtered `agent_id = caller` — an agent that could not
+ * see a task it had been given had no way to learn that the list was lying by omission. That
+ * is exactly how the bug behind IN-nahetc was reported, which is why every list now states
+ * what it spans and what would narrow it.
+ */
+import { ALL_AREAS, splitAreaRefs } from './workspace-resolve.js';
+/** The sentence every area-scoped list carries: what it spans, and how to narrow it. */
+export const LIST_SCOPE_NOTE = "Spans every area you can reach, not just this directory's — pass --area <slug[,slug]> " +
+    'to narrow';
+export const LIMIT_HELP = 'Rows per page (default 30, max 100)';
+export const ALL_HELP = 'Follow every page to the end and print every row';
+export const TASKS_DESCRIPTION = 'List tasks across EVERY area you can reach and EVERY assignee — not just your own, and ' +
+    "not just this directory's area. Grouped by area, 30 rows per page. Narrow with --area / " +
+    '--agent / --unassigned / --intent / --mission, or take the whole thing with --all';
+export const ISSUES_DESCRIPTION = `List issues. ${LIST_SCOPE_NOTE}`;
+export const IDEAS_DESCRIPTION = `List ideas. ${LIST_SCOPE_NOTE}`;
+export const VIBES_DESCRIPTION = `List vibes. ${LIST_SCOPE_NOTE}`;
+export const DOCS_DESCRIPTION = 'List documents (with sections count and context). Spans every area you can reach plus the ' +
+    'workspace-level ones — pass --area <slug[,slug]> to narrow';
+export const INTENTS_DESCRIPTION = 'List intents — workspace-wide, every assignee';
+export const MISSIONS_DESCRIPTION = 'List missions — workspace-wide, every assignee';
+/** `all` is accepted by every list since API 9.0.0 and is the one spelling of "do not filter". */
+export const TASK_STATUS_HELP = 'Filter by status (comma-separated, or `all`; default todo,in_progress)';
+export const ISSUE_STATUS_HELP = 'Filter by status (comma-separated, or `all`; default open,investigating)';
+export const IDEA_STATUS_HELP = 'Filter by status (comma-separated, or `all`; default pending,accepted)';
+export const INTENT_STATUS_HELP = 'Filter by status (comma-separated, or `all`; default new,design,plan,build,in_review)';
+export const MISSION_STATUS_HELP = 'Filter by status (comma-separated, or `all`; default new,active)';
+/**
+ * The commands that accept `--area a,b`, i.e. the ones where an area is a FILTER.
+ *
+ * Everywhere else an area is the write target or the lookup context and exactly one is
+ * required: silently taking the first of several would create an object in an area the caller
+ * did not name — the IS-vse335 failure with extra steps. Names are `command` or
+ * `parent command`, matching how a user types them.
+ */
+export const MULTI_AREA_COMMANDS = [
+    'tasks',
+    'issues',
+    'ideas',
+    'vibes',
+    'docs',
+    'issue list',
+    'idea list',
+    'vibe list',
+];
+/** `tasks`, or `issue list` — the path a user would type, for the check below. */
+export function commandPath(name, parent) {
+    return parent && parent !== 'orbitmap' ? `${parent} ${name}` : name;
+}
+/**
+ * Reject `--area a,b` on a command that needs exactly one area, naming what to do instead.
+ * Returns the message, or `undefined` when the invocation is fine.
+ */
+export function multiAreaRejection(path, area) {
+    if (!area)
+        return undefined;
+    const refs = splitAreaRefs(area).filter((ref) => ref.toLowerCase() !== ALL_AREAS);
+    if (refs.length < 2 || MULTI_AREA_COMMANDS.includes(path))
+        return undefined;
+    return (`--area named ${refs.length} areas (${refs.join(', ')}), but \`${path}\` needs exactly ` +
+        'one: it is the area this command writes to, or looks the object up in. Several areas ' +
+        `are a list filter — they work on ${MULTI_AREA_COMMANDS.join(', ')}.`);
+}
+//# sourceMappingURL=list-options.js.map

package/dist/list-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-options.js","sourceRoot":"","sources":["../src/list-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAElE,wFAAwF;AACxF,MAAM,CAAC,MAAM,eAAe,GAC1B,wFAAwF;IACxF,WAAW,CAAC;AAEd,MAAM,CAAC,MAAM,UAAU,GAAG,qCAAqC,CAAC;AAEhE,MAAM,CAAC,MAAM,QAAQ,GAAG,kDAAkD,CAAC;AAE3E,MAAM,CAAC,MAAM,iBAAiB,GAC5B,yFAAyF;IACzF,0FAA0F;IAC1F,mFAAmF,CAAC;AAEtF,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,eAAe,EAAE,CAAC;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,eAAe,EAAE,CAAC;AAClE,MAAM,CAAC,MAAM,iBAAiB,GAAG,eAAe,eAAe,EAAE,CAAC;AAClE,MAAM,CAAC,MAAM,gBAAgB,GAC3B,4FAA4F;IAC5F,4DAA4D,CAAC;AAC/D,MAAM,CAAC,MAAM,mBAAmB,GAAG,+CAA+C,CAAC;AACnF,MAAM,CAAC,MAAM,oBAAoB,GAAG,gDAAgD,CAAC;AAErF,kGAAkG;AAClG,MAAM,CAAC,MAAM,gBAAgB,GAC3B,wEAAwE,CAAC;AAC3E,MAAM,CAAC,MAAM,iBAAiB,GAC5B,0EAA0E,CAAC;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAC3B,wEAAwE,CAAC;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAC7B,uFAAuF,CAAC;AAC1F,MAAM,CAAC,MAAM,mBAAmB,GAC9B,kEAAkE,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAsB;IACpD,OAAO;IACP,QAAQ;IACR,OAAO;IACP,OAAO;IACP,MAAM;IACN,YAAY;IACZ,WAAW;IACX,WAAW;CACZ,CAAC;AAEF,kFAAkF;AAClF,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,MAAe;IACvD,OAAO,MAAM,IAAI,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,IAAwB;IACvE,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAE5B,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,CAAC;IAClF,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,mBAAmB,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAE5E,OAAO,CACL,gBAAgB,IAAI,CAAC,MAAM,WAAW,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,IAAI,mBAAmB;QACxF,uFAAuF;QACvF,oCAAoC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACtE,CAAC;AACJ,CAAC"}

package/dist/workspace-resolve.d.ts

@@ -193,11 +193,48 @@ export declare function isWithin(dir: string, child: string): boolean;
  * exactly the directories that would have resolved an area.
  */
 export declare function resolveAreaDirectoryMap(options?: ResolveOptions): AreaDirectoryMapping[];
-/** An area slug together with the rung it came from. */
+/**
+ * The literal `--area` / `ORBITMAP_AREA` value that means "do not narrow at all".
+ *
+ * Needed because narrowing is now a *filter* rather than the ambient context (API 9.0.0):
+ * with `ORBITMAP_AREA` exported in a shell, or a `--area` in a wrapper script, there has to
+ * be a spelling of "this one command spans the whole workspace" that does not require
+ * unsetting an environment variable. `--area all` is that spelling; it clears the explicit
+ * narrowing and leaves the rest of the ladder (which only ever supplies the *context* area)
+ * untouched.
+ */
+export declare const ALL_AREAS = "all";
+/**
+ * An area slug together with the rung it came from, plus the full list the caller asked for.
+ *
+ * `area` is the CONTEXT area — one area, the `X-Orbitmap-Area` header, what a write lands in
+ * and what a single-entity read is looked up in. It is resolved exactly as it always was.
+ *
+ * `areas` is the LIST FILTER — every area the caller *explicitly* named, in the order typed
+ * (`--area a,b` → `['a','b']`). It is empty unless someone named one: since API 9.0.0 the
+ * `X-Orbitmap-Area` header no longer narrows a list, so a directory-derived area must not
+ * silently narrow one either — that is the bug this whole intent exists to fix. Only the
+ * `flag` and `env` rungs (someone typed it) fill it.
+ *
+ * `allAreas` records an explicit {@link ALL_AREAS}: "I know something set an area, span the
+ * workspace anyway".
+ */
 export interface ResolvedAreaSlug {
     area?: string;
     source?: AreaSource;
+    /** Explicitly requested area refs — the `area_id` filter. Empty means "the whole reach". */
+    areas: string[];
+    /** True when the caller spelled out {@link ALL_AREAS}. */
+    allAreas: boolean;
 }
+/**
+ * Split an area reference — one ref, several comma-separated refs, or an array of either —
+ * into a list of non-empty refs.
+ *
+ * Deliberately the same parser the API uses (`BaseAgentApiController::splitAreaRefs`), so
+ * `--area a,b`, `ORBITMAP_AREA=a,b` and `area_id=a,b` cannot drift apart.
+ */
+export declare function splitAreaRefs(value: string | string[] | undefined | null): string[];
 /**
  * Area resolution (ADR 0002, extending spec §3.3), explicit sources only:
  * `--area` → `ORBITMAP_AREA` → `link.json.area` → nearest `.orbitmap/config.json`
@@ -315,6 +352,15 @@ export interface ResolvedWorkspaceContext {
     area?: string;
     /** Which rung of the area ladder produced {@link ResolvedWorkspaceContext.area}. */
     areaSource?: AreaSource;
+    /**
+     * The areas the caller EXPLICITLY named (`--area a,b`, `ORBITMAP_AREA=a,b`) — the list
+     * filter, not the context. Empty means "every area the key reaches": since API 9.0.0 a
+     * list is narrowed by the `area_id` parameter alone, never by the `X-Orbitmap-Area`
+     * header, so {@link ResolvedWorkspaceContext.area} must not leak into one.
+     */
+    areas: string[];
+    /** True when the caller spelled out `--area all` — narrowing explicitly cleared. */
+    allAreas: boolean;
     /** `'area'` when an area resolved, `'workspace'` otherwise. Never absent. */
     scope: ContextScope;
     link?: FoundWorkspaceLink;

package/dist/workspace-resolve.js

@@ -339,6 +339,59 @@ function resolveAreaFromCwd(options) {
     const cwd = resolve(options.cwd ?? process.cwd());
     return resolveAreaDirectoryMap(options).find((mapping) => isWithin(mapping.dir, cwd))?.area;
 }
+/**
+ * The literal `--area` / `ORBITMAP_AREA` value that means "do not narrow at all".
+ *
+ * Needed because narrowing is now a *filter* rather than the ambient context (API 9.0.0):
+ * with `ORBITMAP_AREA` exported in a shell, or a `--area` in a wrapper script, there has to
+ * be a spelling of "this one command spans the whole workspace" that does not require
+ * unsetting an environment variable. `--area all` is that spelling; it clears the explicit
+ * narrowing and leaves the rest of the ladder (which only ever supplies the *context* area)
+ * untouched.
+ */
+export const ALL_AREAS = 'all';
+/**
+ * Split an area reference — one ref, several comma-separated refs, or an array of either —
+ * into a list of non-empty refs.
+ *
+ * Deliberately the same parser the API uses (`BaseAgentApiController::splitAreaRefs`), so
+ * `--area a,b`, `ORBITMAP_AREA=a,b` and `area_id=a,b` cannot drift apart.
+ */
+export function splitAreaRefs(value) {
+    if (value === undefined || value === null)
+        return [];
+    const refs = [];
+    for (const entry of Array.isArray(value) ? value : [value]) {
+        if (typeof entry !== 'string')
+            continue;
+        for (const part of entry.split(',')) {
+            const trimmed = part.trim();
+            if (trimmed !== '' && !refs.includes(trimmed))
+                refs.push(trimmed);
+        }
+    }
+    return refs;
+}
+/**
+ * The explicit half of the area ladder: what `--area` / `ORBITMAP_AREA` asked for.
+ *
+ * Returns the refs (empty when nothing was named or when {@link ALL_AREAS} was), whether
+ * `all` was spelled out, and which of the two rungs spoke.
+ */
+function explicitAreaRefs(options) {
+    const fromFlag = splitAreaRefs(options.area);
+    const fromEnv = fromFlag.length > 0 ? [] : splitAreaRefs(process.env['ORBITMAP_AREA']);
+    const refs = fromFlag.length > 0 ? fromFlag : fromEnv;
+    if (refs.length === 0)
+        return { refs: [], allAreas: false };
+    const source = fromFlag.length > 0 ? 'flag' : 'env';
+    if (refs.some((ref) => ref.toLowerCase() === ALL_AREAS)) {
+        // `all` is not an area; it is the absence of narrowing. It also does not name a context
+        // area, so the lower rungs keep supplying one for writes and single-entity reads.
+        return { refs: [], allAreas: true, source };
+    }
+    return { refs, allAreas: false, source };
+}
 /**
  * Area resolution (ADR 0002, extending spec §3.3), explicit sources only:
  * `--area` → `ORBITMAP_AREA` → `link.json.area` → nearest `.orbitmap/config.json`
@@ -369,26 +422,34 @@ function resolveAreaFromCwd(options) {
  * explicit request apart from the machine-wide default.
  */
 export function resolveArea(options = {}) {
-    if (options.area)
-        return { area: options.area, source: 'flag' };
-    const env = process.env['ORBITMAP_AREA'];
-    if (env)
-        return { area: env, source: 'env' };
+    const explicit = explicitAreaRefs(options);
+    const filter = { areas: explicit.refs, allAreas: explicit.allAreas };
+    // One explicit ref is both the filter and the context area — the historical behaviour.
+    // SEVERAL refs name a filter and no context area: there is no single area to put in the
+    // `X-Orbitmap-Area` header, and picking one of them silently would be a write landing
+    // somewhere the caller did not name. Commands that need one area say so (see
+    // `assertSingleArea` in `src/index.ts`).
+    if (explicit.refs.length === 1) {
+        return { area: explicit.refs[0], source: explicit.source, ...filter };
+    }
+    if (explicit.refs.length > 1) {
+        return { source: explicit.source, ...filter };
+    }
     const cwd = resolve(options.cwd ?? process.cwd());
     // Everything below reads a file, and a file above the workspace boundary names an area of
     // a different workspace (IS-e6q7je). No config sets `workspace` ⇒ no boundary ⇒ unchanged.
     const boundary = workspaceBoundary(cwd);
     const found = options.link !== undefined ? options.link : findLinkFile(cwd);
     if (found?.link.area && withinWorkspace(boundary, found.file)) {
-        return { area: found.link.area, source: 'link' };
+        return { area: found.link.area, source: 'link', ...filter };
     }
     const projectArea = resolveProjectConfigField('area', cwd);
     if (projectArea && withinWorkspace(boundary, projectArea.file)) {
-        return { area: projectArea.value, source: 'project-config' };
+        return { area: projectArea.value, source: 'project-config', ...filter };
     }
     const mapped = resolveAreaFromCwd({ ...options, cwd, link: found });
     if (mapped)
-        return { area: mapped, source: 'cwd-map' };
+        return { area: mapped, source: 'cwd-map', ...filter };
     // The machine-wide rung is bounded too, and for the same reason: a slug written once in
     // `~/.orbitmap/config.json` cannot be known to name an area of *this* workspace, and when a
     // project has declared which workspace it is, taking it anyway reproduces IS-e6q7je one rung
@@ -396,9 +457,9 @@ export function resolveArea(options = {}) {
     const configured = options.config?.area;
     if (configured && !boundary) {
         warnDeprecatedGlobalArea();
-        return { area: configured, source: 'config' };
+        return { area: configured, source: 'config', ...filter };
     }
-    return {};
+    return { ...filter };
 }
 let warnedDeprecatedGlobalArea = false;
 /**
@@ -532,7 +593,7 @@ export async function resolveWorkspaceContext(options = {}) {
     const link = options.link !== undefined ? options.link : findLinkFile(cwd);
     const opts = { ...options, cwd, config, link };
     const mode = resolveMode(opts);
-    const { area, source: areaSource } = resolveArea(opts);
+    const { area, source: areaSource, areas, allAreas } = resolveArea(opts);
     const { workspace, source: workspaceSource } = resolveWorkspaceId(opts);
     const scope = area ? 'area' : 'workspace';
     const base = {
@@ -541,6 +602,8 @@ export async function resolveWorkspaceContext(options = {}) {
         workspaceSource,
         area,
         areaSource,
+        areas,
+        allAreas,
         scope,
         link,
         config,