@phnx-labs/agents-cli 1.20.91 → 1.20.93

package/dist/lib/linear-project-counts.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-project Linear issue counts for the `agents projects status` card.
+ *
+ * When a project definition carries `linear.projectId` (set via
+ * `agents projects link <name> --linear`), the card shows one outcome line —
+ * `12/30 done · 5 in progress` — counted from the Linear GraphQL API by state
+ * TYPE (triage / backlog / unstarted / started / completed / canceled), never
+ * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
+ *
+ * This is a best-effort card enrichment, not an explicit command: every failure
+ * (no credential, offline, API error, timeout) degrades to `undefined` and the
+ * card simply omits the line — never a hang, never a throw. `--no-remote`
+ * skips it (it's network). The API key resolves through the same chain the rest
+ * of the stack uses: $LINEAR_API_KEY → macOS Keychain (`resolveLinearApiKey`)
+ * → the linear-cli config (`~/.linear-cli/config.json` `apiKey`).
+ *
+ * Paging is capped (10 × 250 issues) so a pathological project can't burn the
+ * budget; a capped fetch reports `truncated: true` and the card renders the
+ * total as a lower bound (`2500+ done`), never as the complete count.
+ */
+/** The counts the card renders. `total` counts every issue in the project. */
+export interface LinearProjectCounts {
+    /** Issues in a `completed`-type state. */
+    done: number;
+    /** All issues in the project (any state type, including canceled). */
+    total: number;
+    /** Issues in a `started`-type state. */
+    inProgress: number;
+    /**
+     * True when the page cap cut the fetch short — `total` is then a LOWER
+     * bound (rendered `2500+`), never presented as the complete count.
+     */
+    truncated?: boolean;
+}
+/** The GraphQL response shape this module consumes (recorded for the tests). */
+export interface LinearIssuesResponse {
+    issues?: {
+        nodes?: Array<{
+            state?: {
+                type?: string;
+            } | null;
+        }>;
+        pageInfo?: {
+            hasNextPage?: boolean;
+            endCursor?: string | null;
+        };
+    };
+}
+/**
+ * Pure mapping: a Linear issues response → card counts, grouping by state
+ * type. Defensive at the boundary — a missing `issues`/`nodes` yields zeros,
+ * an issue with no state still counts toward `total`.
+ */
+export declare function countsFromIssuesResponse(data: LinearIssuesResponse): LinearProjectCounts;
+/**
+ * Fetch issue counts for one Linear project, paging `issues` filtered by
+ * project id. One shared AbortController bounds the WHOLE paged fetch at ~8s;
+ * any failure (no key, network, API error, abort) returns undefined so the
+ * card just omits the line. `fetchPage` is injectable for tests — the
+ * accumulator (cursor hand-off, cap) is the risky logic, not the HTTP.
+ */
+export declare function fetchLinearProjectCounts(projectId: string, fetchPage?: (projectId: string, after: string | undefined, signal: AbortSignal) => Promise<LinearIssuesResponse | undefined>): Promise<LinearProjectCounts | undefined>;

package/dist/lib/linear-project-counts.js

@@ -0,0 +1,122 @@
+/**
+ * Per-project Linear issue counts for the `agents projects status` card.
+ *
+ * When a project definition carries `linear.projectId` (set via
+ * `agents projects link <name> --linear`), the card shows one outcome line —
+ * `12/30 done · 5 in progress` — counted from the Linear GraphQL API by state
+ * TYPE (triage / backlog / unstarted / started / completed / canceled), never
+ * hardcoded state names, same convention as `auto-dispatch-linear.ts`.
+ *
+ * This is a best-effort card enrichment, not an explicit command: every failure
+ * (no credential, offline, API error, timeout) degrades to `undefined` and the
+ * card simply omits the line — never a hang, never a throw. `--no-remote`
+ * skips it (it's network). The API key resolves through the same chain the rest
+ * of the stack uses: $LINEAR_API_KEY → macOS Keychain (`resolveLinearApiKey`)
+ * → the linear-cli config (`~/.linear-cli/config.json` `apiKey`).
+ *
+ * Paging is capped (10 × 250 issues) so a pathological project can't burn the
+ * budget; a capped fetch reports `truncated: true` and the card renders the
+ * total as a lower bound (`2500+ done`), never as the complete count.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { resolveLinearApiKey } from './auto-dispatch-linear.js';
+const LINEAR_API = 'https://api.linear.app/graphql';
+/** Overall budget across all pages — the card must never hang on Linear. */
+const TIMEOUT_MS = 8_000;
+const PAGE_SIZE = 250;
+/** Hard page cap so a pathological project can't page forever within the budget. */
+const MAX_PAGES = 10;
+/**
+ * Pure mapping: a Linear issues response → card counts, grouping by state
+ * type. Defensive at the boundary — a missing `issues`/`nodes` yields zeros,
+ * an issue with no state still counts toward `total`.
+ */
+export function countsFromIssuesResponse(data) {
+    const nodes = data.issues?.nodes ?? [];
+    let done = 0;
+    let inProgress = 0;
+    for (const n of nodes) {
+        const type = n?.state?.type;
+        if (type === 'completed')
+            done++;
+        else if (type === 'started')
+            inProgress++;
+    }
+    return { done, total: nodes.length, inProgress };
+}
+/** $LINEAR_API_KEY → macOS Keychain → ~/.linear-cli/config.json. Null if none. */
+function resolveApiKey() {
+    const fromChain = resolveLinearApiKey();
+    if (fromChain)
+        return fromChain;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(os.homedir(), '.linear-cli', 'config.json'), 'utf8'));
+        return cfg.apiKey?.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch issue counts for one Linear project, paging `issues` filtered by
+ * project id. One shared AbortController bounds the WHOLE paged fetch at ~8s;
+ * any failure (no key, network, API error, abort) returns undefined so the
+ * card just omits the line. `fetchPage` is injectable for tests — the
+ * accumulator (cursor hand-off, cap) is the risky logic, not the HTTP.
+ */
+export async function fetchLinearProjectCounts(projectId, fetchPage = fetchLinearIssuesPage) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    try {
+        const all = [];
+        let after;
+        let truncated = false;
+        for (let page = 0;; page++) {
+            const data = await fetchPage(projectId, after, ctrl.signal);
+            if (!data)
+                return undefined;
+            all.push(...(data.issues?.nodes ?? []));
+            const pi = data.issues?.pageInfo;
+            if (!pi?.hasNextPage || !pi.endCursor)
+                break;
+            if (page + 1 >= MAX_PAGES) {
+                // The cap cut the fetch short — total is a lower bound, say so.
+                truncated = true;
+                break;
+            }
+            after = pi.endCursor;
+        }
+        return { ...countsFromIssuesResponse({ issues: { nodes: all } }), ...(truncated ? { truncated } : {}) };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** One real GraphQL page; undefined on any HTTP/API-level failure. */
+async function fetchLinearIssuesPage(projectId, after, signal) {
+    const apiKey = resolveApiKey();
+    if (!apiKey)
+        return undefined;
+    const res = await fetch(LINEAR_API, {
+        method: 'POST',
+        headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            query: 'query($p:ID!, $after:String){ issues(filter:{ project:{ id:{ eq:$p } } }, first:' +
+                PAGE_SIZE +
+                ', after:$after){ nodes{ state{ type } } pageInfo{ hasNextPage endCursor } } }',
+            variables: { p: projectId, after: after ?? null },
+        }),
+        signal,
+    });
+    if (!res.ok)
+        return undefined;
+    const json = (await res.json());
+    if (json.errors?.length || !json.data)
+        return undefined;
+    return json.data;
+}

package/dist/lib/linear-projects.d.ts

@@ -0,0 +1,50 @@
+/** The minimal Linear project shape the link flow needs (id + name + url). */
+export interface LinearProjectLite {
+    id: string;
+    name: string;
+    /** Project URL, when the `linear` CLI JSON carries one. Never fabricated. */
+    url?: string;
+}
+/**
+ * Collapse a Linear name / repo slug / folder path to one comparison key:
+ * lowercase, keep only the last path segment, strip separators.
+ *   "Agents CLI"            -> "agentscli"
+ *   "phnx-labs/agents-cli"  -> "agentscli"
+ *   "~/src/.../agents-cli"  -> "agentscli"
+ */
+export declare function normalizeProjectKey(s: string): string;
+/**
+ * Find the Linear project that best matches a repo slug or folder name.
+ * Exact normalized match first, then a containment fallback (either direction),
+ * so "agents-cli-web" still suggests "Agents CLI" when no exact peer exists.
+ *
+ * Kept for parity with the Factory original — the `link` command uses
+ * {@link pickLinearProject} instead: this one returns the FIRST match (silent
+ * on duplicate names), which is fine for a UI suggestion but never for a write
+ * path.
+ */
+export declare function matchLinearProject(slugOrName: string, projects: LinearProjectLite[]): LinearProjectLite | undefined;
+/** The outcome of picking one Linear project out of the workspace list. */
+export type LinearPick = {
+    kind: 'match';
+    project: LinearProjectLite;
+} | {
+    kind: 'candidates';
+    projects: LinearProjectLite[];
+} | {
+    kind: 'none';
+};
+/**
+ * Pick the Linear project a query refers to. An exact id or exact normalized
+ * name match is confident enough to write; anything weaker (several exact-name
+ * peers, or only containment matches) comes back as a candidate LIST for the
+ * user to disambiguate — the link command never guesses on a weak signal.
+ */
+export declare function pickLinearProject(query: string, projects: LinearProjectLite[]): LinearPick;
+/**
+ * List the workspace's Linear projects via the `linear` CLI on PATH. Throws a
+ * clear error when the binary is missing, errors, or returns a shape we can't
+ * use — this backs an explicit user command, so a silent empty list would send
+ * the user down a wrong "no matches" path.
+ */
+export declare function listLinearProjects(): LinearProjectLite[];

package/dist/lib/linear-projects.js

@@ -0,0 +1,114 @@
+// Linear project matching for `agents projects link --linear`.
+//
+// A project's identity shows up three ways — a Linear project name ("Agents CLI"),
+// a GitHub repo slug ("phnx-labs/agents-cli"), and a filesystem folder
+// (".../agents-cli"). normalizeProjectKey() collapses all three to one comparison
+// key so they compare equal, and matchLinearProject() binds a repo/folder to the
+// Linear project the user most likely means.
+//
+// Ported from apps/factory/src/core/linearProjects.ts (no cross-package imports —
+// repo rule); keep the two in sync. The matcher half is PURE so it unit-tests
+// without a live `linear` binary; the `linear projects --json` shell-out lives at
+// the bottom (listLinearProjects) and fails LOUD — it's behind an explicit user
+// command, not a best-effort card enrichment.
+import { execFileSync } from 'child_process';
+/**
+ * Collapse a Linear name / repo slug / folder path to one comparison key:
+ * lowercase, keep only the last path segment, strip separators.
+ *   "Agents CLI"            -> "agentscli"
+ *   "phnx-labs/agents-cli"  -> "agentscli"
+ *   "~/src/.../agents-cli"  -> "agentscli"
+ */
+export function normalizeProjectKey(s) {
+    const last = s.toLowerCase().split('/').filter(Boolean).pop() ?? '';
+    return last.replace(/[-_\s.]/g, '');
+}
+/**
+ * Find the Linear project that best matches a repo slug or folder name.
+ * Exact normalized match first, then a containment fallback (either direction),
+ * so "agents-cli-web" still suggests "Agents CLI" when no exact peer exists.
+ *
+ * Kept for parity with the Factory original — the `link` command uses
+ * {@link pickLinearProject} instead: this one returns the FIRST match (silent
+ * on duplicate names), which is fine for a UI suggestion but never for a write
+ * path.
+ */
+export function matchLinearProject(slugOrName, projects) {
+    const key = normalizeProjectKey(slugOrName);
+    if (!key)
+        return undefined;
+    const exact = projects.find((p) => normalizeProjectKey(p.name) === key);
+    if (exact)
+        return exact;
+    return projects.find((p) => {
+        const pk = normalizeProjectKey(p.name);
+        return pk.length > 0 && (pk.includes(key) || key.includes(pk));
+    });
+}
+/**
+ * Pick the Linear project a query refers to. An exact id or exact normalized
+ * name match is confident enough to write; anything weaker (several exact-name
+ * peers, or only containment matches) comes back as a candidate LIST for the
+ * user to disambiguate — the link command never guesses on a weak signal.
+ */
+export function pickLinearProject(query, projects) {
+    const q = query.trim();
+    if (!q)
+        return { kind: 'none' };
+    const byId = projects.find((p) => p.id === q);
+    if (byId)
+        return { kind: 'match', project: byId };
+    const key = normalizeProjectKey(q);
+    if (!key)
+        return { kind: 'none' };
+    const exact = projects.filter((p) => normalizeProjectKey(p.name) === key);
+    if (exact.length === 1)
+        return { kind: 'match', project: exact[0] };
+    if (exact.length > 1)
+        return { kind: 'candidates', projects: exact };
+    const containment = projects.filter((p) => {
+        const pk = normalizeProjectKey(p.name);
+        return pk.length > 0 && (pk.includes(key) || key.includes(pk));
+    });
+    return containment.length > 0 ? { kind: 'candidates', projects: containment } : { kind: 'none' };
+}
+/**
+ * List the workspace's Linear projects via the `linear` CLI on PATH. Throws a
+ * clear error when the binary is missing, errors, or returns a shape we can't
+ * use — this backs an explicit user command, so a silent empty list would send
+ * the user down a wrong "no matches" path.
+ */
+export function listLinearProjects() {
+    let out;
+    try {
+        out = execFileSync('linear', ['projects', '--json'], {
+            encoding: 'utf8',
+            timeout: 8000,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+    }
+    catch {
+        throw new Error('Could not list Linear projects — is the `linear` CLI installed and logged in? (`brew install linear-cli`, `linear auth login`)');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(out);
+    }
+    catch {
+        throw new Error('`linear projects --json` returned invalid JSON');
+    }
+    if (!Array.isArray(parsed))
+        throw new Error('`linear projects --json` did not return a list');
+    return parsed.flatMap((x) => {
+        if (x && typeof x === 'object' && !Array.isArray(x)) {
+            const o = x;
+            if (typeof o.id === 'string' && typeof o.name === 'string') {
+                const p = { id: o.id, name: o.name };
+                if (typeof o.url === 'string')
+                    p.url = o.url;
+                return [p];
+            }
+        }
+        return [];
+    });
+}

package/dist/lib/menubar/install-menubar.d.ts

@@ -30,7 +30,16 @@ export declare function menubarServiceInstalled(): boolean;
 /** True when the bundle carries a signature the kernel will accept at launch. */
 export declare function codesignVerifies(appPath: string): boolean;
 /**
- * Guarantee the installed bundle has a valid signature on THIS machine.
+ * True when Gatekeeper will let the bundle execute on this machine.
+ * A Developer-ID-signed but un-notarized app is rejected by `spctl --assess`,
+ * which macOS surfaces as "the app is damaged" and can crash AppKit during
+ * launch. This is separate from `codesign --verify`: a signature can be valid
+ * while Gatekeeper still refuses to run it.
+ */
+export declare function gatekeeperAssesses(appPath: string): boolean;
+/**
+ * Guarantee the installed bundle has a signature Gatekeeper will accept on THIS
+ * machine.
  *
  * npm's pack/extract strips the ad-hoc/linker signature the release baked into
  * the helper, leaving `code object is not signed at all`. On macOS 26+ the
@@ -42,9 +51,10 @@ export declare function codesignVerifies(appPath: string): boolean;
  * matching cdhash, which the kernel accepts.
  *
  * A Developer-ID-signed helper survives npm untouched — its embedded signature
- * still verifies — so we leave it alone and only re-sign when verification
- * fails. Returns whether the bundle ends up validly signed. No-op cost on the
- * common (already-valid) path is a single `codesign --verify`.
+ * still verifies — but if the release was not notarized, Gatekeeper rejects it.
+ * In that case we strip the quarantine xattr and re-sign ad-hoc so the helper
+ * can launch locally. The stable fix is to notarize the release build; this
+ * fallback just prevents a crash-loop while the user is on an un-notarized cut.
  */
 export declare function ensureValidSignature(appPath: string): boolean;
 /**

package/dist/lib/menubar/install-menubar.js

@@ -177,7 +177,19 @@ export function codesignVerifies(appPath) {
     return r.status === 0;
 }
 /**
- * Guarantee the installed bundle has a valid signature on THIS machine.
+ * True when Gatekeeper will let the bundle execute on this machine.
+ * A Developer-ID-signed but un-notarized app is rejected by `spctl --assess`,
+ * which macOS surfaces as "the app is damaged" and can crash AppKit during
+ * launch. This is separate from `codesign --verify`: a signature can be valid
+ * while Gatekeeper still refuses to run it.
+ */
+export function gatekeeperAssesses(appPath) {
+    const r = spawnSync('spctl', ['--assess', '--type', 'exec', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
+    return r.status === 0;
+}
+/**
+ * Guarantee the installed bundle has a signature Gatekeeper will accept on THIS
+ * machine.
  *
  * npm's pack/extract strips the ad-hoc/linker signature the release baked into
  * the helper, leaving `code object is not signed at all`. On macOS 26+ the
@@ -189,15 +201,17 @@ export function codesignVerifies(appPath) {
  * matching cdhash, which the kernel accepts.
  *
  * A Developer-ID-signed helper survives npm untouched — its embedded signature
- * still verifies — so we leave it alone and only re-sign when verification
- * fails. Returns whether the bundle ends up validly signed. No-op cost on the
- * common (already-valid) path is a single `codesign --verify`.
+ * still verifies — but if the release was not notarized, Gatekeeper rejects it.
+ * In that case we strip the quarantine xattr and re-sign ad-hoc so the helper
+ * can launch locally. The stable fix is to notarize the release build; this
+ * fallback just prevents a crash-loop while the user is on an un-notarized cut.
  */
 export function ensureValidSignature(appPath) {
-    if (codesignVerifies(appPath))
+    if (codesignVerifies(appPath) && gatekeeperAssesses(appPath))
         return true;
     // Drop any quarantine/xattrs the tarball round-trip added (they can break
-    // codesign), then re-sign ad-hoc under the helper's stable bundle identifier.
+    // both codesign and Gatekeeper), then re-sign ad-hoc under the helper's
+    // stable bundle identifier.
     spawnSync('xattr', ['-cr', appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
     spawnSync('codesign', ['--force', '--sign', '-', '--identifier', SERVICE_LABEL, appPath], { stdio: ['ignore', 'ignore', 'ignore'] });
     return codesignVerifies(appPath);

package/dist/lib/menubar/notify-desktop.d.ts

@@ -4,8 +4,12 @@
  * The one place the daemon (overdue routines, heal, routine start/finish/output)
  * emits a native desktop notification. On macOS it routes through the installed
  * `MenubarHelper.app` companion — a one-shot `MenubarHelper --notify` invocation —
- * so the notification is attributed to that bundle and carries the agents-cli /
- * Agentialized mark instead of the generic AppleScript icon. When the companion
+ * so the notification is attributed to that bundle and carries the agents-cli
+ * mark instead of the generic AppleScript icon. A banner carries two images: the
+ * agents-cli app icon on the LEFT (the sender) and, when the event belongs to one
+ * harness, that agent's avatar on the RIGHT (`agent`, rendered by
+ * AgentAvatar.swift) — the same layout macOS gives a YouTube notification, app on
+ * the left and the channel on the right. When the companion
  * app is not installed (menu bar disabled, a Linux package, a dev checkout), it
  * degrades to `osascript` so an overdue/heal notice is never silently lost — the
  * generic icon is the acceptable cost of preserving delivery, not a bug hidden by
@@ -32,6 +36,17 @@ export interface DesktopNotification {
      * macOS-only (osascript / notify-send have no click target). See routine-notify.ts.
      */
     action?: string;
+    /**
+     * Harness the notification is ABOUT (`claude`, `codex`, … — an `AgentId`).
+     * macOS draws two images on a banner: the sending bundle's app icon on the
+     * LEFT and `contentImage` on the RIGHT. The companion renders this id as the
+     * right-hand avatar (AgentAvatar.swift), so a banner reads "agents-cli, about
+     * Claude" the way a YouTube notification reads "YouTube, from this channel".
+     * Omit it when no single harness owns the event (a daemon heal, a fan-out
+     * across several agents) — the right slot then stays empty rather than
+     * repeating the left one. macOS-only; osascript / notify-send carry no image.
+     */
+    agent?: string;
 }
 /** Argv for the MenubarHelper one-shot notify mode. Exported for tests. */
 export declare function buildMenubarNotifyArgs(n: DesktopNotification): string[];

package/dist/lib/menubar/notify-desktop.js

@@ -4,8 +4,12 @@
  * The one place the daemon (overdue routines, heal, routine start/finish/output)
  * emits a native desktop notification. On macOS it routes through the installed
  * `MenubarHelper.app` companion — a one-shot `MenubarHelper --notify` invocation —
- * so the notification is attributed to that bundle and carries the agents-cli /
- * Agentialized mark instead of the generic AppleScript icon. When the companion
+ * so the notification is attributed to that bundle and carries the agents-cli
+ * mark instead of the generic AppleScript icon. A banner carries two images: the
+ * agents-cli app icon on the LEFT (the sender) and, when the event belongs to one
+ * harness, that agent's avatar on the RIGHT (`agent`, rendered by
+ * AgentAvatar.swift) — the same layout macOS gives a YouTube notification, app on
+ * the left and the channel on the right. When the companion
  * app is not installed (menu bar disabled, a Linux package, a dev checkout), it
  * degrades to `osascript` so an overdue/heal notice is never silently lost — the
  * generic icon is the acceptable cost of preserving delivery, not a bug hidden by
@@ -35,6 +39,8 @@ export function buildMenubarNotifyArgs(n) {
         args.push('--subtitle', n.subtitle);
     if (n.action)
         args.push('--action', n.action);
+    if (n.agent)
+        args.push('--agent', n.agent);
     return args;
 }
 /** AppleScript for the osascript degradation path. Exported for tests. */

package/dist/lib/project-key.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The one worktree-aware cwd -> project fold.
+ *
+ * Several surfaces bucket work "by project": the `agents sessions` overview,
+ * the `agents activity` timeline, and anything else that has a cwd and needs a
+ * stable repo-level key. They must agree, or the same session shows up under
+ * `agents-cli` in one view and `my-branch-slug` in another — so the rule lives
+ * here and every caller delegates.
+ *
+ * The rule: a worktree cwd (`…/<repo>/.agents/worktrees/<slug>[/sub]`) folds to
+ * the REPO directory name, so a worktree groups with the repo it branched from;
+ * any other path resolves to its own basename. {@link projectKeyFromCwd} is pure
+ * — no filesystem, no git, so it works identically for a remote peer's events as
+ * for local ones; {@link resolveProjectKey} adds the filesystem repo-root walk
+ * for paths this machine can see.
+ */
+/**
+ * Resolve a stable project key from a working directory, or `undefined` when
+ * the path carries nothing usable (empty, `/`, whitespace).
+ */
+export declare function projectKeyFromCwd(cwd?: string | null): string | undefined;
+/**
+ * The git working-tree root containing `dir`, by walking up for a `.git` entry
+ * — a directory in a normal checkout, a file in a linked worktree, so one
+ * `existsSync` covers both. Filesystem-only: no `git` process per lookup, which
+ * matters because a timeline can hold dozens of distinct cwds.
+ *
+ * Returns `undefined` when `dir` is not inside a repo, when it does not exist
+ * (a path from another machine), or when the only repo found IS the home
+ * directory — a dotfiles repo at `$HOME` would otherwise swallow every
+ * non-project directory under it into one bogus "project".
+ */
+export declare function repoRootForCwd(dir: string, home?: string): string | undefined;
+/**
+ * Resolve the project key for a cwd **on this machine**: the repository it
+ * belongs to when there is one (so a monorepo subdir like `<repo>/apps/cli`
+ * groups under `<repo>`, not `cli`), else the directory itself.
+ *
+ * Each machine resolves its own paths — a peer answering a fan-out stamps the
+ * project for its events before they cross the wire — so this is never asked
+ * about a path it cannot see. {@link projectKeyFromCwd} is the pure fold for
+ * everything else.
+ */
+export declare function resolveProjectKey(cwd?: string | null, home?: string): string | undefined;

package/dist/lib/project-key.js

@@ -0,0 +1,79 @@
+/**
+ * The one worktree-aware cwd -> project fold.
+ *
+ * Several surfaces bucket work "by project": the `agents sessions` overview,
+ * the `agents activity` timeline, and anything else that has a cwd and needs a
+ * stable repo-level key. They must agree, or the same session shows up under
+ * `agents-cli` in one view and `my-branch-slug` in another — so the rule lives
+ * here and every caller delegates.
+ *
+ * The rule: a worktree cwd (`…/<repo>/.agents/worktrees/<slug>[/sub]`) folds to
+ * the REPO directory name, so a worktree groups with the repo it branched from;
+ * any other path resolves to its own basename. {@link projectKeyFromCwd} is pure
+ * — no filesystem, no git, so it works identically for a remote peer's events as
+ * for local ones; {@link resolveProjectKey} adds the filesystem repo-root walk
+ * for paths this machine can see.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+const WORKTREE_SEGMENT = '/.agents/worktrees/';
+/**
+ * Resolve a stable project key from a working directory, or `undefined` when
+ * the path carries nothing usable (empty, `/`, whitespace).
+ */
+export function projectKeyFromCwd(cwd) {
+    if (!cwd)
+        return undefined;
+    const norm = cwd.replace(/\\/g, '/').replace(/\/+$/, '').trim();
+    if (!norm)
+        return undefined;
+    const wtIdx = norm.indexOf(WORKTREE_SEGMENT);
+    if (wtIdx > 0) {
+        const repoPath = norm.slice(0, wtIdx);
+        const base = repoPath.slice(repoPath.lastIndexOf('/') + 1);
+        if (base)
+            return base;
+    }
+    const base = norm.slice(norm.lastIndexOf('/') + 1);
+    return base || undefined;
+}
+/**
+ * The git working-tree root containing `dir`, by walking up for a `.git` entry
+ * — a directory in a normal checkout, a file in a linked worktree, so one
+ * `existsSync` covers both. Filesystem-only: no `git` process per lookup, which
+ * matters because a timeline can hold dozens of distinct cwds.
+ *
+ * Returns `undefined` when `dir` is not inside a repo, when it does not exist
+ * (a path from another machine), or when the only repo found IS the home
+ * directory — a dotfiles repo at `$HOME` would otherwise swallow every
+ * non-project directory under it into one bogus "project".
+ */
+export function repoRootForCwd(dir, home = os.homedir()) {
+    const stop = path.resolve(home);
+    let current = path.resolve(dir);
+    for (;;) {
+        if (fs.existsSync(path.join(current, '.git')))
+            return current === stop ? undefined : current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+/**
+ * Resolve the project key for a cwd **on this machine**: the repository it
+ * belongs to when there is one (so a monorepo subdir like `<repo>/apps/cli`
+ * groups under `<repo>`, not `cli`), else the directory itself.
+ *
+ * Each machine resolves its own paths — a peer answering a fan-out stamps the
+ * project for its events before they cross the wire — so this is never asked
+ * about a path it cannot see. {@link projectKeyFromCwd} is the pure fold for
+ * everything else.
+ */
+export function resolveProjectKey(cwd, home) {
+    if (!cwd)
+        return undefined;
+    const root = repoRootForCwd(cwd, home);
+    return projectKeyFromCwd(root ?? cwd);
+}